XMJ(6)

📦
version 1.17.2 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay bestie, welcome to xmj(6) — the Games Manual page for a whole little trio: xmj, mj-server, and mj-player. these are programs for playing Mah-Jong, and they are lowkey iconic. 🀄💖

🌸 SYNOPSIS 🌸

       xmj [--id idnumber]
                [--server address]
                [--name playername]
                [--connect]
                [--show-wall | --no-show-wall]
                [--size N]
                [--animate | --no-animate]
                [--tileset directory]
                [--tileset-path directory-path]
                [--dialogs-popup | --dialogs-below | --dialogs-central]
                [--use-system-gtkrc | --no-use-system-gtkrc]
                [--gtk2-rcfile file]
                [--echo-server]
                [--pass-stdin]
                [--monitor]

       mj-server [--server address]  [--timeout seconds]
                [--pause deciseconds]
                [--random-seats | --id-order-seats]
                [--disconnect-penalties N1,N2,N3]
                [--end-on-disconnect]
                [--exit-on-disconnect]
                [--save-on-exit]
                [--option-file file]
                [--load-game file]
                [--no-id-required]
                [--no-manager]
                [--auth-basic id:password]*4
                [--debug]
                [--logfile file]
                [--no-special-scores]
                [--seed N]
                [--wallfile file]
                [--hand-history]
                [--nohist]

       mj-player [--id idnumber] [--name playername]
                [--server address] [--password password]
                [strategy options]

💅 DESCRIPTION 💅

so basically, it's a set of three programs to play Mah-Jong on Unix systems — against people or against programs, over the Internet. no cap.

  • mj-server — this is the program that handles communications and control of the game. the rules and scoring are enforced right there. players, whether human or computer, connect to a server via the network. 👑
  • mj-player — this is a computer player. at present, it's fairly simplistic: it only has offensive tactics and knows nothing about defensive play. ngl, it's giving baby bot energy.
  • xmj — this is the X client for human players. it's the one you actually look at and click on. 💖

🎀 QUICK START 🎀

if you don't want to read this long document: to start a game against three computer players, start xmj, select "New local game..." from the "Game" menu, and click "Start Game". (wait about ten seconds for everything to start up.) that's it, you're in. slay. ✨

🔥 OPTIONS 🔥

💖 All Programs 💖

  • --server address — specifies the network address to listen on (for mj-server) or to connect to (for mj-player and xmj). if address contains a colon, it specifies an Internet socket, and it should have the form host:port. if address does not contain a colon, it is interpreted as a Unix file name and a Unix socket is used. the default value for address is localhost:5000. address can also be set in a dialog box in xmj. 🌈

🦋 xmj and mj-player 🦋

  • --id idnumber — the server assigns a unique integer ID to each player (which is currently just 1 to 4 in order of connection). this ID should be quoted when reconnecting to a game in progress — after, for example, losing a network connection or accidentally killing xmj 😭. the default ID is 0, which denotes no pre-assigned ID.
  • --name name — players can give themselves names which will be used by client programs. this option specifies the name. for xmj, the default is the value of the environment variable LOGNAME, or failing that the username of the logged in user. for mj-player, the default is "Robot(PID)" where PID is the process id. 🎀

🌸 xmj 🌸

  • --connect — by default, xmj does not automatically connect to a server, but waits for the user to connect via a menu. if this option is specified, xmj immediately connects. periodt.
  • --show-wall / --no-show-wall — tells xmj (not) to display the wall. by default, the wall is shown only if running on a big enough screen. this option is also controllable via the Display Options preference panel.
  • --size number — this option adjusts the size of the main window. it should be thought of as the length of a tile rack, measured in tiles. the default, and the largest value accepted, is 19, or 18 if on an 800x600 display. the smallest usable value is 14. this option is also controllable via the Display Options preference panel. if the --show-wall option is given, a --size smaller than 19 will have no effect.
  • --animate / --no-animate — this option switches on (off) some animation. not all tile movements are animated: only those that involve moving tiles to or from a hand from outside. this option is also controllable via the Display Options preference panel.
  • --tileset directory — xmj needs pixmaps to display the tiles and the tong box. this option tells it which directory to find them in. the default is set at compilation time; the default default is to use the compiled-in tiles.
  • --tileset-path directory-path — this gives a colon-separated (or semicolon-separated under Microsoft Windows) list of directories in which to look for the directory named by the --tileset option.
  • --dialogs-popup — by default, most of the dialog boxes for player actions are part of the main window. if this option is used, they will instead appear as separate transient windows.
  • --dialogs-below — by default, dialog boxes appear in the centre of the table. if this option is given, dialogs (apart from some popups) are positioned below the table area. please let me know which style you prefer! 🙈
  • --dialogs-central — the default: dialog boxes appear in the middle of the table. these options are also controllable via the Display Options preference panel.
  • --gtk2-rcfile file — if xmj is compiled with GTK+2, this option specifies a GTK rc file to be used instead of the program's compiled-in style file. this may be used to change the appearance of the program. see description under the Display Options... panel for more details. the file should be an absolute filename; if it is relative, it will be sought in the current directory (Unix) or the program directory (Windows). this option is also controllable via the Display Options preference panel.
  • --use-system-gtkrc / --no-use-system-gtkrc — when xmj is compiled with GTK+2, by default it ignores the system provided settings, to ensure a consistent behaviour across systems. if you wish it to use your system settings, set this option. this option is also controllable via the Display Options preference panel.
  • --echo-server — if this option is given, xmj will echo to stdout all the protocol messages received from the server. this option is for use in debugging. 🔍
  • --pass-stdin — if this option is given, xmj will send any text given on stdin to the server. this option is for use in debugging.
  • --monitor — if this option is given, xmj will send requests to the server only in direct response to user actions; it will take no action itself (and hence all auto-declaring and playing is also disabled). this option is for use in debugging.

👑 mj-server 👑

  • --timeout seconds — when a discard is made, there is a limit on the time players have to claim it. this option sets the timeout; a value of zero disables it. the default is 15 seconds. this value can also be set via a GameOption request from a player.
  • --pause deciseconds — this will make the server enforce a delay of deciseconds/10 seconds between each action in the game; the purpose is to slow programmed players down to human speed (or, in a teaching situation, to slow the game even more). the current server considers that 50 (i.e. 5 seconds) is the maximum reasonable value for this option. the option can also be requested by players, via a PlayerOption protocol request.
  • --random-seats — by default, players are seated in order of connection to the server. this option seats them randomly. it will become the default later.
  • --id-order-seats — this option causes the players to be seated in numerical order of their ids. it is used by the xmj program to make the New local game.. work as expected.
  • --disconnect-penalties N1,N2,N3 — this specifies the penalties applied by the following option for players who disconnect before the end of a game. N1 is the penalty for disconnecting in the middle of a hand; N2 at the end of a hand but in the middle of a round; N3 at the end of a round (other than end of game). they all default to 0 if not specified.
  • --end-on-disconnect — if this option is given, a disconnection by one player will gracefully terminate the game. mid-hand, the hand is declared a wash-out; after Mah-Jong has been declared, then if a losing player disconnects, their tiles are shown, the hand is scored, and then the game ends; if a winning player disconnects, the hand is a wash-out. the disconnecting player may be assigned a penalty, according to the --disconnect-penalties option, which will be included in the scores printed out by the server. (the penalties will not be visible to the other players.)
  • --exit-on-disconnect — if this option is given, the server will quit if any player disconnects, rather than waiting indefinitely for reconnection.
  • --save-on-exit — if this option is given, the server will save the state of the game if it quits as a result of a player disconnecting. (it will not save the state if it quits as the result of an internal error.)
  • --option-file file — this names a file of protocol commands which will be applied to every game when it starts. its main purpose is to set non-default game options, via the GameOption protocol message (note that this is a CMsg, not a PMsg). however, users will normally set options and preferences via the xmj control panel, not by this means.
  • --load-game file — this names a file containing a saved game (as a suitable sequence of protocol commands). the server will load the game; clients connecting will be treated as if they had disconnected and rejoined the game.
  • --no-id-required — okay so picture the most common resume-the-saved-game situation: one human versus three robots. The robots are NOT gonna have the same names or ids as the robots from the original game, right? So this flag tells the server: if you can't match a reconnecting player by id or by name, just go ahead and match them to one of the players who was previously disconnected anyway. (In this case the human normally connects first with the same name, so they get matched correctly. 💖)
  • --no-manager — usually whoever connects first becomes the game manager and can change all the game settings. Give this option and nobody is allowed to change the game settings. No manager era. ✨
  • --auth-basic id:password — this hands you basic authorization: the player with id id has to give the specified password to connect. And bestie, it's insecure, because the password goes over the wire in plaintext. 🫣 Also, important: if you give this argument at all, you have to give it four times, once for each authorized player — any player id you don't mention is not allowed to connect. And you can let a player connect with no password at all by making password empty.
  • --debug — turns on a bunch of debugging features. In particular, it enables protocol commands that let you change the tiles in a hand...
  • --logfile file — the server writes a complete record of the game to file. Heads up, this thing gets quite large, and it's really only useful for automatic comparison of different computer players. 💀
  • --no-special-scores — suppresses the scoring of points and doubles for flowers and seasons. Its main character purpose is running tests of different players; for actual human use, a game option will be provided to eliminate the specials altogether.
  • --seed n — picks the seed for the random number functions. Used for repeatable tests. 🔥
  • --wallfile file — names a file containing space separated tile codes giving the wall; used for repeatable tests. (This is a testing option; it is not robust.)
  • --hand-history — an option to facilitate certain automatic analyses; if it's set, a history of each hand gets dumped to the file hand-NN.mjs.
  • --nohist — another one that's only used in automatic comparison: it saves some CPU time by disabling the book-keeping required to let players disconnect and reconnect.

🎀 mj-player 🎀

  • --password password — sets the password, if basic authorization is in use.

🌸 strategy options 🌸

The player has some options that can change its "personality". The meanings are kinda approximate, ngl, since they actually change parameters that get used in a rather complex way — but the idea is right. These options each take a floating point value in the given range, and they are:

  • --randomness 0.0 .. 1.0 — the most generally useful option: it adds random noise to the player's choice calculations, which lowers its skill level. Values above 1.0 are possible, but they don't seem to make matters worse. And the dumbed-down players are still not stupid, okay. 😌
  • --chowness -1.0 .. 1.0 — this affects how much the player likes chows: at 1.0 it will go all out for the chicken hand, at -1.0 it will never chow. The default is 0.0.
  • --hiddenness 0.0 .. 1.0 — cranking this up makes the player reluctant to make exposed sets. At 1.0 it will never claim (except possibly to go mah-jong). The default is 0.0.
  • --majorness 0.0 .. 1.0 — increasing this biases the player towards collecting major tiles. At 1.0 it will discard all minor tiles, if possible. The default is 0.0.
  • --suitness 0.0 .. 1.0 — increasing this makes the player try to go for one-suit hands. The default is 0.0

In practice, the --majorness option seems not to be very useful, but the other options change the personality without completely destroying the playing ability. 🦋

In fact, all these options take a comma-separated list of values, which lets you specify a set of strategies that the player will switch between. In that case, the --hysteresis hhh option specifies how much better a strategy should be to switch to it. However, using this option, and multiple strategies, is probably only useful if you first read the code to see how it works. iykyk. 👑

🌈 USING THE XMJ PROGRAM 🌈

The main window contains a menu-bar and a table area; the table is in a tasteful shade of dark green. 🌿 The table shows a stylized version of the game — stylized in that there's no jazzy graphics or perspective, and the tiles are not intended to be pictures of real objects, and so on. Otherwise, the layout is exactly what you'd expect of a real game. However, the wall may or may not be displayed, depending on option settings and screen size. (See above.)

Specifically, the four players are arranged around the four edges of the table, with "us" at the bottom. For each player, the concealed tiles are displayed nearest the edge of the table; our own tiles are visible, and the other players' tiles are face-down. The rightmost concealed tile of other players is highlighted in red when it's their turn to discard.

In front of the concealed tiles are (to the player's left) any declared sets, and (to the player's right) flowers and seasons, and the tong box if the player is East. The tong box displays the wind of the round in a white circle. If necessary, the flowers and seasons will overflow into the concealed row.

The discards are displayed face-up in the middle of the board: they're laid down in order by each player, in the natural orientation. TODO: add options to display discards randomly, or face-down. If animation (see --animate option) is not being used, then the most recent discard will be highlighted in red.

The name of a face-up tile can be displayed by right-clicking in the tile. Alternatively, the Tiletips display option can be set, in which case the name of a tile is displayed whenever the mouse enters it. 🖱️✨

Our tiles are displayed in sorted order, which happens to be Bamboos (1-9), Characters (1-9), Circles (1-9), Winds (ESWN), Dragons (RWG), Flowers, Seasons. We can also arrange the tiles ourselves — see the "Sort tiles in hand" display preference described below.

Actions are generally carried out by clicking a button in a dialog box that appears in the middle of the board. For many actions, a tile must be selected. A tile is selected or unselected by single-clicking it; when selected, it appears as a depressed button. The program will generally pre-select a sensible tile: specifically:

  • during the initial declaration of special tiles, the rightmost special is selected;
  • after we draw a tile from the wall, the drawn tile is selected;
  • when declaring concealed sets after going Mah Jong, the first undeclared tile is selected.

To describe the possible actions, let us run through the course of a game. 🎮

First select "New local game..." from the "Game" menu. A panel will appear. The default options are to play a game against the computer, so click "Start Game". After a second or two, a game will start. (NOTE: this assumes correct installation. If this fails, start a server and players manually, and use the "Join server..." menu item.)

The first thing that happens is a dialog box "Ready to start next hand". The server will not start playing a hand until all players have indicated their willingness to continue play.

Next, the tiles are dealt. Then each player in turn is expected to declare flowers and seasons. When it's our turn, a dialog will appear with the following buttons:

  • Declare — declare the selected flower or season. (Note: the program auto-selects the rightmost special tile.) If no tile is selected, this finishes declarations. This button will not appear if the game is being played without flowers and seasons.
  • Kong — if we have a concealed kong, we can declare it now with this button.
  • Finish — finish declaring specials and kongs.

When all players have finished declaring specials and kongs, a dialog box appears, asking (on East's behalf) permission to continue.

During play, when we draw a tile from the wall, it will be auto-selected. We may also of course select a different tile. A dialog will appear giving us the following possibilities:

  • Discard — discard the selected tile. This button also serves to declare a flower or season, and the label changes to "Declare" when one is selected.
  • &Calling — discard the selected tile and declare a calling hand. This button is only shown when calling is allowed (by default, only Original Call is allowed).
  • Kong — declare a concealed kong of the selected tile, or add the selected tile to an exposed pung, as appropriate. Note: In most rules, a concealed kong can only be declared (or a tile added to an existing pung) immediately after drawing from the wall, but not after claiming somebody else's discard. Up to and including version 1.10, the server enforced this rule strictly. As from version 1.11, it allows a tile to be added to a pung that you have just claimed: in real life, this corresponds to correcting your Pung! claim to a Kong! claim, which is allowed by all rules. (Obscure note: if you are playing the KongHas3Types option, the resulting kong will be counted as annexed, instead of the exposed kong that would have resulted from a genuine change of claim. This is a bug, but not worth the trouble of fixing.)
  • Mah Jong! — declare Mah Jong! (no selection needed)

If the wall is not being shown, the dialog will note the number of tiles left in the live wall.

A tile can also be discarded simply by double-clicking it.

When another player discards, a dialog appears to allow us to claim it. If the dialogs are in the middle of the table, the dialog displays the tile in a position and orientation to indicate the player who discarded; if the dialogs are at the bottom, this is not done, to save space. In any case the dialog displays the name of the tile, and buttons for the possible claims. If the wall is not being shown, the dialog will note the number of tiles left in the live wall. There is also a progress bar which shows how time is running out. The buttons use one variant of traditional English terminology, viz:

  • No claim — nope, not us, we're not taking this tile. If there's no timeout running, you have to click this to say "pass", and honestly even when there is one, clicking it just makes everything go faster. 💨
  • Chow — claiming for a sequence. If our claim goes through and there's more than one sequence we could actually make with it, a dialog pops up asking which one we want.
  • Pung — claiming for a triplet.
  • Kong — claiming for a quadruplet.
  • Mah Jong! — claiming for Mah Jong. If the claim succeeds, a dialog box shows up asking if we want the tile for "Eyes", "Chow", "Pung", or a "Special Hand" (think Thirteen Unique Wonders and friends). (They call it "Eyes" instead of "Pair" so that the keyboard accelerators can use E and leave P free for "Pung". ikyk. 🫶)

When a player claims — us included — the word "Chow!" or whatever it is shows up in big letters on a yellow background (by default) for a couple of seconds, right above that player's tiles. very dramatic. very demure. 💅

Once everybody has claimed or timed out, the successful claim just… happens. No extra announcement, no confetti. 😭

If a player adds a tile to an exposed pung and that tile would give us Mah Jong, a dialog box pops up asking whether we want to rob the kong. (yes. yes we do. 🩸)

After somebody goes Mah Jong, we're asked to declare our concealed sets. A dialog appears with buttons for "Eyes", "Chow", and "Pung". To declare a set you select a tile — and for a chow it must be the first tile in the set — then click the right button. (If we're the one going Mah Jong, the first undeclared tile gets auto-selected for us. slay.) When you're done, hit "Finished" to reveal whatever's left to the other players.

If we're the winner, there's a "Special Hand" button too — that's the one for declaring hands of non-standard shape, like Thirteen Unique Wonders. (Quick note bestie: the Seven Pairs hand, if it's in use, gets declared with the "Eyes" button, not the "Special Hand" button. don't get got. 🙈)

At this point a brand new top-level window appears to show the scoring info. All the scoring is done entirely by the server, not by the players — the server sends over a text description of the score calculation and that gets displayed for each player in the Scoring window. The info in the Scoring window just chills there until the next hand is scored, and you can bring the window up whenever you want from the "Show" menu. 👑

Finally, the "continue with next hand" dialog appears. The hand you just finished stays visible on the table until the next hand starts.

🎹 Keyboard Accelerators

There are keyboard accelerators for every single action during play. For picking tiles, the Left and Right arrow keys move the selection left or right along the row of tiles. In all dialogs, Space or Return activates the shadowed button, which is usually the most common choice. Every button can also be activated by typing its underlined letter.

Heads up for the Windows GTK1 build: use l (ell) and r instead of Left and Right. And the button accelerators don't work there, for reasons unknown to me. 💀

The menus are accelerator-accessible too. To open a menu, press Meta-X (Alt-X on Windows), where X is the underlined letter in the menu name. (Meta-X is often — confusingly — Alt-X on Linux systems.) Then each entry has an underlined letter, and pressing it activates that entry.

An extra top-level window showing the state of the game can be summoned by selecting "Game info" from the "Show" menu. 🌸

A record of the scores so far in the game lives under "Scoring history" in the "Show" menu. Players are listed in board order, with the original east marked by @. For each hand, the player's hand score appears in parentheses, then their gain or loss for the hand, and beneath that is the running total. 🧾

There's also a facility for sending text messages to the other players. Select "Messages" from the "Show" menu and a window appears: the top is a display of all messages sent, and below is a single line where you type your message. It gets sent when you hit Return. The message window pops up automatically whenever a message arrives — unless a display preference stops it.

If the "Display status and messages in main window" display option is set, then this window instead appears in the main window, above the table. In that case there's a checkbox called "Keep cursor here" next to the message entry line. Checking it keeps the keyboard focus pinned in the message entry field, even when you click on buttons in the game. (Which means — plot twist — you can't use keyboard accelerators while that option is checked. 💀)

🎮 Starting games and re-connecting

The "Game" menu has the "New local game..." item for starting a fresh game on your own computer, and the "Join server..." item for connecting to an existing game. Both of their dialogs have these entries:

  • Checkboxes for Internet/Unix server — these say whether the server is listening on an Internet socket or a Unix socket. If it's an Internet (TCP) socket, the host name ("Join Game..." only) and port number go in the appropriate boxes; if it's a Unix socket, you can enter the file name of the socket, or leave it blank and a temporary file gets used instead. These fields are remembered from game to game. 💾
  • "Player ID" and "Name" fields — leave "Player ID" at 0, unless you're reconnecting to an existing game, in which case it should be the ID the server assigned when you first connected to that game. The "Name" field can be literally anything. When reconnecting to an existing game, if the ID is given as 0, the server will try to use the "Name" to identify the player. (This may not be true in future. ⏳) The "Name" field is remembered from game to game.

The "Join server..." dialog then just has a "Connect" button to establish the connection. The "New local game..." has these fields instead:

  • For each of three further players — a checkbox saying whether to start a computer player. (Some of) these should be unchecked if you want other humans to join the games. If checked, there's a text entry to set the player's name, and a text entry field where options can be given to the players; that last one should only be used if you actually understand the options! (fr fr.) The options are remembered from game to game.
  • An "allow disconnection" checkbox — if checked, the server that gets started will keep running even if players disconnect. If it's not checked, the server quits if any player disconnects. If you're playing one against the computer, this should generally stay unchecked, so you don't end up with server processes accidentally left lying around. If you're playing against people, check it, so players can go away or so you're guarded against network outages. 🌐
  • A "save game state on exit" checkbox — if checked, the server saves the game state (see below on saving and resuming games) when a player disconnects and causes it to quit.
  • A "seat players randomly" checkbox — if left unchecked, players are initially seated as East, South, West, North in order of connection. (We always connect first. 😌) If it's checked, the seating is random.
  • A "robot difficulty" numeric entry field — values from 0 to 10, making the robots more skilful. Actually, lower values effectively make the robots a bit tired, so they make mistakes. Beginners probably want 0 to stand a chance of winning sometimes. 🤖
  • A numeric entry field — to specify the time limit for claiming discards. If set to 0, there is no time limit.
  • A button to start the game — note that it takes a few seconds to start a game, during which time the dialog stays up with the button pressed. (TODO: fix this!)

💾 Saving and resuming games

At any time during the play of a game you can choose the "Save" entry from the "Game" menu. This makes the server save the current state of the game into a file. By default the file is named game-date.mjs; if a name has previously been specified, or if the game was resumed from a file, that name gets used instead. To specify a name, use the "Save as..." entry in the "Game" menu.

Note that for security, directories cannot be specified (except by resuming a game), so the file will be created in the working directory of the server. 🔒

To resume a saved game, use the "Resume game..." entry from the "Game" menu. It's just like the "New local game..." panel, except it has a box to specify the file containing the saved game. You can either type the file name into the box, or click the "Browse..." button to get a file chooser dialog. (File chooser not available on Windows GTK1 build. 😭)

⚙️ Setting display and game options

The "Options" menu of xmj brings up panels to set various options related to the display and to the game rules. Most of these options can be stored in the preferences file, which is .xmjrc in your home directory on Unix, and xmj.ini in your home (whatever that means) directory on Microsoft Windows. 🪟

🌈 Display Options

This panel controls options related to the local display. At the bottom are three buttons: "Save & Apply" applies changes and saves them in the preferences file for future sessions; "Apply (no save)" applies any changes but does not save them; "Cancel" ignores changes.

Note that many display options can also be controlled by command-line arguments; if an option is specified both in the preferences file and on the command line, the command line takes priority. 👑
  • Position of action dialogs. — this determines where the dialogs for user actions in the game are popped up; see the description of the --dialogs-central etc. options above. This option is stored in the preferences file as
Display DialogPosition posn

where posn is one of "central", "below" or "popup".

  • Animation — determines whether tile movements are animated (see the --animate option above). This option is stored in the preferences file as
Display Animate bool

where bool is "0" or "1".

  • Display status and messages in main window — puts the game status and message (chat) windows in the main window, above the table, instead of having separate popup windows. This option is stored in the preferences file as
Display InfoInMain bool

where bool is "0" or "1".

  • Don't popup scoring/message windows — bestie this one is the ✨peace and quiet✨ switch. It kills the automatic popup of the scoring window at the end of a hand, the message window on the arrival of a message, AND the game status window at the end of the game. All three, gone. This option is stored in the preferences file as Display NoPopups bool where bool is "0" or "1".
  • Tiletips always shown — means the name of a tile pops up whenever the mouse enters it, and the name of the selected tile is always shown. (Otherwise? Right-click to display the name, bestie. You gotta ask.) This option is stored in the preferences file as Display Tiletips bool where bool is "0" or "1".
  • Rotate player info text — decides whether the player information labels on the main board get rotated vertically for the left and right players, or stay horizontal. The default is to rotate them. This option is stored in the preferences file as Display RotateLabels bool where bool is "0" or "1".
  • Show when players are thinking — when this is on, "..." will be displayed in other players' claim alerts while they are "thinking", that is, while they have not yet claimed or passed. This option requires a recent server. The default is off. This option is stored in the preferences file as Display ThinkingClaim bool where bool is "0" or "1".
  • Alert on possible mah-jong — determines whether to pop up an alert when a discard or drawn tile makes mah-jong possible. ⚠️ Beware though: only the server knows the full rules, so this is not infallible. The default is off. This option is stored in the preferences file as Display AlertMahjong bool where bool is "0" or "1".
  • Display size — this drop-down list specifies the size of the display. Think of the size as the length of a tile rack, okay? This is only relevant if the wall is not being displayed. Values range from 14 to 19; if "(auto)" (the default) is specified, the client tries to choose a size as big as will fit in the display. This option can also be specified by the command line --size argument. This option is stored in the preferences file as Display Size n.
  • Show the wall — "always" is equivalent to the --show-wall option; "never" is equivalent to the --no-show-wall option; and "when room" is the default. This option is stored in the preferences file as Display ShowWall when where when is one of "always", "when-room" or "never".
  • Sort tiles in hand — by default, the program maintains your own tiles in sorted order. If you prefer to leave them unsorted (which is often recommended in real life, to avoid giving information to your opponents 👀), or to arrange them yourself, you can set this option to "never", or to "on deal" if you want them sorted at the beginning but then left alone. To rearrange tiles, use Shift-Left and Shift-Right (i.e. the left and right arrow keys while holding Shift) — these move the selected tile left or right in your hand. (In the Windows GTK1 build, use L (Shift-l) and R (Shift-r) instead.) On GTK2 builds, you can also drag a tile to its new position with the mouse. 🖱️ This option is stored in the preferences file as Display SortTiles when where when is one of "always", "deal" or "never".
  • Iconify all windows with main — if this option is set (the default), then when the main xmj window is iconified, (almost) all other open windows such as dialogs will also be iconified; when the main window is uniconified, the other windows will also be uniconified. If it is not set, all windows are independent of one another. This option is stored in the preferences file as Display IconifyDialogs bool. This option is not currently supported under Microsoft Windows.
  • Tileset — this is the tile pixmap directory, also given by the --tileset option. This option is stored in the preferences file as Display Tileset dirname.
  • Tileset Path — this is the search path for tileset directories, also given by the --tileset-path option. This option is stored in the preferences file as Display TilesetPath search-path.
  • Main font selection... — this button brings up a font selection dialog to choose the font used in buttons, menus, etc. in the client. This option is stored in the preferences file as Display MainFont font-name where font-name is a font name, which may be an X LFD in the Unix GTK+1 version, or a Pango font name in the Windows and Unix GTK+2 versions.
  • Text font selection... — this button brings up a font selection dialog to choose the font used in text display (such as scoring info and chat) in the client. This option is stored in the preferences file as Display TextFont font-name.
  • Table colour selection... — unaccountably, not everybody likes my choice of dark green for the table background. 😤 This button brings up a colour selection box to allow the table colour to be changed. This option is stored in the preferences file as Display TableColour col where col is a GTK colour specification. The format depends on whether xmj is built with GTK+1 — in which case it is an X color of the form rgb:RRRR/GGGG/BBBB — or GTK+2 — in which case it is a GTK2 color of the form #RRRRGGGGBBBB. GTK+2 programs will convert an old GTK1 specification.
  • Gtk2 Rcfile: — in the GTK+2 build, xmj by default ignores completely the system and user settings for look and feel, and uses its own built in settings. These settings use the Clearlooks theme, if it is available, to provide a simple but clean look with slightly rounded tiles; and fall back to a plain theme, as compact as possible with the standard engine. If you wish, you can use this option to specify the name of a GTK rcfile which will be read instead of the built in settings. A minimal set of settings will be read before your file is read. Such a file can specify many details of the appearance, provided that you know how to write a GTK rcfile. 🧚 You will need to know that xmj uses the following styles and bindings:
    • gtk-font-name = fontname — can be used to change the overall font used by widgets. This will overridden by the font specified by the Main Font option, if set.
    • style "table" — is used to give the green (or whatever you set) colour to the table. All widgets that should have this style are named "table", so the appropriate binding (already set in the minimal set) is
widget "*.table" style "table"
  • style "playerlabel" — is used to give the white text colour to the player status labels in the corners of the board (if shown). All widgets that should have this style are named "playerlabel", so the appropriate binding (already set in the minimal set) is
widget "*.playerlabel" style "playerlabel"
  • style "tile" — is used in the default settings for all widgets named "tile", which are all tiles except the tiles in your own concealed hand. This style is not used in the minimal settings, but if set it should be bound with
widget "*.tile" style "tile"
  • style "mytile" — is used in the default settings for the concealed tiles in your hand, which are active buttons. These tiles are all named "mytile". This style is not used in the minimal settings, but if set it should be bound with
widget "*.mytile" style "mytile"
  • style "claim" — is used to set the yellow background and large font of the claim announcement popups. These popups are named "claim", so the appropriate binding (already set in the minimal set) is
widget "*.claim" style "claim"
  • style "text" — is used to change the font for the text widgets such as message boxes and input fields. In the minimal settings, it is empty, but is defined and bound to the relevant widgets. The binding should not be changed, but the style itself can be redefined. If the Text Font option is set, this style will be redefined in order to implement it.
  • binding "topwindow" — is defined and bound to the top-level window to implement the use of the left and right arrow keys to change the selected tile. It is probably not helpful to change this.

The distribution contains three example gtkrc files, called gtkrc-minimal, gtkrc-plain, and gtkrc-clearlooks, which contain the program's compiled in settings. This option is stored in the preferences files as Display Gtk2Rcfile file-name. Note that if the file-name is relative, it will be interpreted relative to the current directory in Unix, or the program directory in Windows.

  • Use system gtkrc — as noted above, xmj does not normally load the system settings in the GTK+2 build. If this option is checked, it will (after the minimal settings, but before the default or user-specified settings). This option is stored in the preferences files as Display UseSystemGtkrc bool where bool is 0 or 1.
  • Note for GTK+1 builds — under a GTK+1 build, xmj does what any other application does. This should allow the use of a .gtkrc file to change colours, using the styles and bindings given above. However, this is not a supported activity. 🙈

🎮 Playing Preferences 🎮

This panel controls what actions the client may take on your behalf. The first (and currently only) section specifies when the client should declare tiles and sets for you. It has the following checkboxes:

  • flowers and seasons — if checked, will be automatically declared as soon as drawn. 🌸
  • losing hands — if this is checked, then when somebody else goes out, the client will declare your closed sets. It declares in the order pungs, pairs, chows.
  • winning hands — this is the same for when you go out. 👑

The panel has "Save & Apply", "Apply (no save)" and "Cancel" buttons, as in the display options panel.

✨ Game Option Preferences ✨

Okay so bestie, this panel is where you curate your preferred game options — the settings that get yeeted over to the server the moment a game starts. 🎀

Here's the tea though: your prefs only get applied if you are the game manager, or if the game literally has no manager at all. (And just so you know, normally the first human player to connect to the server is the one who becomes the game manager. 👑)

For the details of what the options actually are and what they mean, go check the Game Options section in the rules. That's where the lore lives.

This panel has two action buttons: "Save Changes" and "Cancel", and yes, their meanings are exactly as obvious as they sound. 🙈 One thing to clock: if a game is already in progress, your changed preferences are NOT applied to it. Not even a little. But don't stress — there's a button over in the Current Game Options panel that will apply your preferences for you. 💅

The main body of the panel is a scrollable window listing every known option. If no preference is stored for the FooBar option, you'll see an "Add pref" button sitting right next to a description of that FooBar option. Click it and an entry for setting that option appears. And the format of that entry depends on the type of the option — see the Game Options section of the rules for the deets on types:

Boolean (on/off) options

These get a checkbox. Simple. Iconic. 💖

Integer options

These get a spinbutton for numerical entry — you can type the value straight in, or use the up and down arrows to nudge it around. 🔢

Score options

These get radio buttons for selecting Limit, Half-Limit, or other. For other, the number of doubles and/or points gets entered with spinbuttons. (Note: the underlying protocol does allow percentages — possibly more than 100% — of limits to be specified for scores. However, the current graphical interfaces allow only limits or half-limits. Even half-limits are pretty strange, but some bizarre sets of rules, like those of the British Mah-Jong Association (which plays a weird American/Western/Chinese mix), allow other fractions of limits.) 😭

String options

These get a simple text entry field. Type away, babe. ✨

Every single option entry has a "Reset" button that returns the entry to its previous state. 🫶

And a preference gets removed by clicking the "Remove pref" button. Bye bestie, gone, no cap. 👋

💜 Current Game Options 💜

When there's a connected game, this panel lets you modify its game options (if we have permission to do so, obviously — we're not out here breaking into servers 🚫).

The three action buttons are:

  • "Apply changes" — applies the panel's settings to the current game.
  • "Apply prefs" — applies our preferences (the ones described above) to the current game.
  • "Cancel" — you know what this one does.

The body of the panel contains entries for all the options of the current game, in the exact same format as the preferences panel (see above ⬆️).

🌈 UPDATES 🌈

The latest release of the Unix Mah-Jong programs should be available at http://mahjong.julianbradfield.org/

👑 RULES 👑

The game currently implemented is a version of the classical Chinese game. The most convenient and comprehensive set of rules is the one provided by A. D. Millington, "The Complete Book of Mah-Jongg", Weidenfield & Nicolson (1993), ISBN 0 297 81340 4. 📚

In the following, M 103 denotes item 103 of the rules laid out in Chapter 3 of that book. I'm only describing the differences from these rules here — some of which are just consequences of using computers, and some of which are spots where my house rules differ from Millington's version. In due course, all variations (of Chinese classical) will be accommodated, if there's sufficient desire. 💫

Classification of tiles (M 1-8)

The tiles are a standard Chinese set. The tiles do not have Arabic numerals, except for the flowers and seasons, where the identifying Chinese characters are too small to be legible. A numbered set is included in the distribution and can be used via the Tileset display preference.

The flowers and seasons may be removed from the tile set by unsetting the Flowers game option. 🌸

Preliminary (M 9-10)

Nothing to say. Literally nothing. Moving on. 💀

Duration of the game (M 11-14)

Standard rules. In particular, the title of East does not pass after a wash-out. 🀄

Selection of seats (M 15)

The players are seated in the order they connect to the server, or randomly, according to the option given to the server. 🎲

The deal etc. (M 16-27)

There is no attempt to simulate the usual dealing ritual (M 16-20, 23-26); the wall is built randomly by the server. The dead wall is also maintained by the server. 🧱

The existence of a dead wall is controlled by the DeadWall game option; normally there is a dead wall.

The deal wall is either 14 tiles and kept at 13 or 14 during play (as in most authors), or is 16 tiles, not extended during play (per Millington (M 22)), according to the DeadWall16 game option.

Replacement tiles for kongs are always taken from the loose tiles, but replacements for bonus tiles may be drawn from the live wall (M 31), or from the loose tiles, according to the FlowersLoose game option. 🌷

Object of game (M 28-31)

All winning hands must comprise four sets and a pair, with the exception of the Thirteen Unique Wonders. If the SevenPairs game option is set, then a hand of any seven pairs is also allowed as a winning hand. 🔥

Bonus tiles (M 31)

M requires that bonus tiles must be declared in the turn in which they are drawn; otherwise the player may not exchange or score them (and thus they cannot go out). We do not make this restriction, because it is (a) pointless (b) unenforceable in real life. 💅

Bonus tiles may be declared at any time after drawing from the wall. (Obviously, there is no reason not to declare them immediately. Like, why would you wait. 🙄)

Commencement of the Game (M 32-33)

Standard. ✨

Playing procedure (M 34-38)

Standard. In particular, the other players have to give permission for east to start playing (M 34). The display of discards cannot be controlled by the server; the current X client displays them in an organized fashion, rather than the random layout required by M 35.

Chow (M 39-42)

Standard. 🍜

Pung (M 43-45)

Standard. 💥

Kongs (M 46-52)

M distinguishes three types of kong: concealed, claimed (by Kong), and annexed (formed by adding a discard to an exposed pung), and allows claimed kongs to be counted as concealed for the purposes of doubling combinations. I have not seen this anywhere else; normally, a claimed kong is treated as exposed for all purposes. We follow the normal convention; however, the game option KongHas3Types can be set to implement M's rules. In this case, the xmj program will distinguish claimed kongs by displaying them with the last tile face down, whereas annexed kongs are all face up. 👀

Players may declare a concealed kong, or add to a pung, only when they have just drawn a tile from the wall (live or dead); not just after claiming a discard. (A silly restriction in my view, but one that all rule sets seem to have (M 51).) As from program version 1.11 (protocol version 1110), we also allow a player to add to a pung they have just claimed (see note above in the description of play).

Calling and Mah Jong (M 53-54)

Standard. (I.e. there is no "Calling" declaration.) 🀅

NOTE

M permits players to change their mind about making a claim (M 69); we do not, and all claims are irrevocable. Periodt. 🚫 As a special concession, we allow adding to a just claimed pung, so simulating the effect of correcting a pung claim to a kong.

Original Call (M 55)

The Original Call declaration must be made simultaneously with the first discard, rather than afterwards.

NOTE: the server does not check that the declarer does indeed have a calling hand, as a mistaken original call does not damage the other players or the progress of the game. The server does, however, thereafter prevent the declarer from changing their hand; therefore a mistaken original call will make it impossible to go out. (Note: in M, an Original Caller may change their hand, but will thereby lose the ability to go out (M 55(b)); is this a better way to treat it?)

Note also: as per M, an original call can be made even if another player has claimed a discard before, unlike the Japanese version. 🇯🇵

Robbing a Kong (M 57-60)

Robbing a kong is implemented. 🏴‍☠️ However, as with discards, we require that kongs are robbed before anything else happens, and in particular before the konger draws a replacement tile. Therefore, after a kong, all other players must either claim Mah Jong or pass. (The provided programs will pass automatically if robbing is not possible.) As for discards, there is a time limit. ⏰

Precedence of claims for discard (M 61-65)

Many rules allow a discard to be claimed up until the time the next discard is made. M does this, with elaborate rules for the precise specification. For ease of implementation, we do not allow this: instead, all players are required to make a claim or pass, and once all players have claimed, the successful claim is implemented irrevocably.

The server imposes a time limit; players that do not claim within the limit are deemed to have passed. This defaults to 15 seconds, but can be changed or disabled by the Timeout game option. ⏳

Irregularities in Play (M 66-81)

The server does not permit unlawful moves, and so no irregularities can arise. Slay, no crime possible. 😇

False Declaration of Mah Jong (M 82-83)

Such declarations are not permitted by the server. 🚫

False Naming of Discards (M 84-88)

This also cannot happen.

Incorrect Hands (M 89)

Cannot happen.

Letting Off a Cannon (M 90-96)

As in M. However, if a player makes a dangerous discard, but has no choice, the server will determine this; it is not necessary to plead "no choice" explicitly, and neither is the player's hand revealed to the other players. 💣

Wash-Out (M 97-99)

Standard. 🚿

Points of Etiquette (M 100-102)

Not applicable.

Displaying the Hand (M 103-106)

The format of display is a matter for the client program, and cannot be controlled by the server.

After Mah Jong, the players are responsible for declaring concealed sets in whatever way they wish. The winner, of course, is required to declare a complete hand; but the losers may declare as they wish. Once a set is declared, it cannot be revoked. Note that the losers may declare multiple scoring pairs. 👯

Procedure in Settlement (M 107-111)

The settlement is classical: that is, the winner gets the value of their hand from all players; the losers pay one another the differences between their scores; except all payments to or from East are doubled; and if players let off a cannon, they pay everybody's debt. 💸

Unlike normal play (M 110), all hands are scored by the server, rather than by the players. Settlement is also computed by the server. 🖥️

Some variations in settlement are provided: if the LosersSettle game option is set to false, there are no payments between losers; if the EastDoubles game option is set to false, payments to or from East are not doubled; if the DiscDoubles game option is set to true, then the discarder of the tile that gave Mah-Jong will pay double to the winner, and a self-draw is paid double by everybody. ✨

🌸 Method of Scoring (M 112-122) 🌸

ok bestie so the method is literally the standard one (M 112) — you count up the points you got from your sets and bonuses, and then you apply the doubles. that's the whole thing, no cap. 💅

🎀 Points for tiles 🎀

here's what each tile sitch is worth:

  • Bonus tiles: 4 each. (M 114(a))
  • Pungs: 2 for an exposed minor tile; 4 for an exposed major tile or a concealed minor one; 8 for a concealed major. (M 114(b))
  • Kongs: 8 for exposed minor; 16 for exposed major or concealed minor; 32 for concealed major. (M 114(c))
  • Chows: no score, sorry babe. (M 114(d))
  • Pair: 2 for a pair of Dragons, your Own Wind, or the Prevailing Wind. a pair that is BOTH your Own and the Prevailing Wind scores 4. (M 114(e)) Non-winning hands may score more than one pair, so keep an eye out 👀

✨ Basic points ✨

  • the winner gets 20 points for going Mah Jong. this can be changed by the MahJongScore game option (M 115(a) has 10 points).
  • Seven Pairs hand: if Seven Pairs hands are allowed, they receive an additional score of 20 points, changed by the SevenPairsVal game option.
  • Winning from wall: if the final tile is drawn from the wall, 2 points get added. (M 115(b))
  • Filling the only place: if the final tile is the only denomination that could have completed the hand, 2 points get added. (M 115(c)) NOTE: as in M, if all four copies of a tile are exposed on the table, it does not count as available for completing the hand.
  • Fishing the eyes: a player who completes by obtaining a pair gets 2 points if the pair is minor, or 4 if it's major. (M 115(d)) Note: to obtain these points for a discard, the player must actually claim the discard for a pair — like, if you're waiting on 5677 and a 7 gets discarded, you must claim for the pair, not the chow. no sneaky shortcuts 🫶

💜 Doubles that apply to all hands 💜

these apply to all hands, and all possible clauses apply unless stated otherwise.

  • Having own flower or own season: no extra score. Changed by the FlowersOwnEach game option.
  • Having own flower AND own season: 1 double. (M 116(a)) Changed by the FlowersOwnBoth game option.
  • Having all four flowers: 1 double. (M 116(b)) Changed by the FlowersBouquet game option.
  • Having all four seasons: 1 double. (M 116(b)) Changed by the FlowersBouquet game option.
  • Each set of dragons: 1 double. (M 116(d))
  • A set of the player's own wind: 1 double. (M 116(e))
  • A set of the prevailing wind: 1 double. (M 116(f))
  • "Little Three Dragons" — two sets and a pair of dragons: 1 double. (M 116(g))
  • "Big Three Dragons" — three sets of dragons: 2 doubles. (M 116(h))
  • "Little Four Winds" — three sets and a pair of winds: 1 double. (M 116(i))
  • "Big Four Winds" — four sets of winds: 2 doubles. (M 116(j))
(Note: the definitions of these last four doubles when applied to non-winning hands are subject to wide variations. Possibly there should be options to allow other possibilities.)
  • Three concealed pungs: 1 double. (M 116(k)) (Note: if the KongHas3Types game option is set, a claimed kong counts as concealed for this hand; see the note above under "Kongs".)

🌈 Doubles that apply to the winning hand only 🌈

  • No score hand — four chows and a non-scoring pair: 1 double. (M 117(a)) (Note: like M, we allow any of the extra points (Fishing the Eyes, etc) to go with this double. Some rules say that the extra points invalidate this hand. Possibly there should be an option for this.)
  • No chows: 1 double. (M 117(b))
  • Concealed hand: 1 double (M 117(c)), changeable with the ConcealedFully game option. (Note: this means a hand that is fully concealed after going out. Another common value for this is 3 doubles, in which case 1 double is usually given for a semi-concealed hand — see below.) (Note: if the KongHas3Types game option is set, a claimed kong counts as concealed for this hand; see the note above under "Kongs".)

🦋 Doubles that normally apply to the winning hand only 🦋

these normally apply to the winning hand only; however, the LosersPurity game option can be set to allow losing hands to score them. (this is a highly deprecated American feature, but has been requested by a user.)

  • Semi-concealed hand: no doubles, changeable with the ConcealedAlmost game option. (Not in M) (Note: this means a winning hand that is concealed up to the point of going out, or, if enabled, a concealed losing hand. According to a discussion on rec.games.mahjong, a winning semi-concealed hand is classically awarded one double (with three given for fully concealed). One book in my possession (U.S.A., early 1920s) awards this double only to a hand that is concealed except for the pair.) (Note: if the KongHas3Types game option is set, a claimed kong counts as concealed for this hand; see the note above under "Kongs".)
  • One suit with honours: 1 double. (M 117(d))
  • One suit only: 3 doubles. (M 117(e))
  • All majors: 1 double. (M 117(f))
  • All honours (in an unlimited game): 2 doubles. (M 117(g)) (Note: such a hand will also score the double for all majors.)
  • All terminals (in an unlimited game): 2 doubles. (Not in M) (Note: such a hand will also score the double for all majors.)

👑 Doubles that apply only to the winning hand 👑

  • Winning with loose tile: 1 double. (M 117(h)) (Note: with the default settings, replacements for bonus tiles come from the live wall. Hence this double applies only to winning after Kong.)
  • Winning from the bottom of the sea (winning with last tile): 1 double. (M 117(i))
  • Catching a fish from the bottom of the sea (winning with last discard): 1 double. (M 117(j))
  • Robbing a kong: 1 double. (M 117(k))
  • Completing Original Call: 1 double. (M 117(l))

💎 Limit (M 118-120) 💎

the limit is 1000 by default, and you can change it with the ScoreLimit game option. and the NoLimit game option lets you play a game "with the roof off". 🚀

⭐ The limit hands ⭐

these hands are limit hands:

  • Heaven's Blessing: East wins with dealt hand. (M 122(a))
  • Earth's Blessing: player wins with East's first discard. (M 122(b))
  • Gathering Plum Blossom from the Roof: winning with 5 Circles from the loose wall. (M 122(c))
  • Catching the Moon from the Bottom of the Sea: winning with 1 Circle as the last tile. (M 122(d)) (Note: M says that the tile must be drawn. It seems more reasonable also to allow it to be the last discard, which is what we do. Objections?)
  • Scratching a Carrying Pole: robbing a kong of 2 Bamboos. (M 122(e))
(Note: these last three limits are rather arbitrary, but of the arbitrary limits they are apparently the most common. There should be options to disable them.)
  • Kong upon Kong: making a Kong, making another Kong with the loose tile, and with the second loose tile obtaining Mah Jong. (Also, of course, with three or four successive kongs.) (M 122(f))
  • Four Kongs. (M 122(g))
  • Buried Treasure: all concealed and no chows. (M 122(h))
  • The Three Great Scholars: three sets of dragons and no chows. (M 122(i)) (Note: in most rules I have seen, there is no restriction to a no chow hand. Since in M's rules, three sets and a chow scores at least (10 (M has 10 for Mah Jong) + 12 (at least 3 pungs)) times 8 (2 for each set of dragons) times 4 (for Big Three Dragons) = 704, this is significant with the default limit. For us, with 20 for going out, Big Three Dragons is over the default limit anyway.)
  • Four Blessings o'er the Door: four sets of winds and a pair. (M 122(j))
  • All Honours. (M 122(k))
  • Heads and Tails: all terminals. (M 122(l))
  • Imperial Jade: contains only Green Dragon and 2,3,4,6,8 Bamboo. (M 122(m)) (Note: another rather arbitrary hand, but widely adopted.)
  • Nine Gates: calling on 1-1-1-2-3-4-5-6-7-8-9-9-9 of one suit. (M 122(n)).
  • Wriggling Snake: 1-1-1-2-3-4-5-6-7-8-9-9-9 plus 2, 5 or 8 of one suit (M 122(o)). (Note: another rather arbitrary hand.)
  • Concealed Clear Suit: one suit only and all concealed. (M 122(p))
  • Thirteen Unique Wonders: one of each major tile, and a match to any of them. (M 122(q))
  • East's 13th consecutive Mah-Jong. (M 122(r))

🌸 General note 🌸

there are many other doubles and limits kicking around, fr fr. I welcome opinions on which should be possible options; and also on which of the above I should eject from the default set. I dislike Imperial Jade, Wriggling Snake, and the ones depending on a specific tile (Gathering Plum Blossom, Catching the Moon, Scratching a Carrying Pole): which of these are so commonly adopted that they should be in even a fairly minimalist default set?

🎮 GAME OPTIONS 🎮

Okay so this section describes the options that can be set in the game. Whether an option can be used depends on the version of the programs. This is described by a "protocol version number"; this is not strictly speaking a version just of the communication protocol, but a version number reflecting the combination of protocol and programs. When playing by oneself, this does not matter, but in the case of a networked game, players might have different versions of the software, in which case the game is played according to the lowest version of any player.

Game options can be controlled in two ways: the --option-file argument to the mj-server program gives options to be applied to the game, or options can be set by the players, using the interface described in the manual section for xmj.

In the user interface, the options are referred to by a one line description, but each option also has a short name, given here.

Options are of several types:

  • bool — boolean, or on/off, options.
  • int — integer options.
  • nat — non-negative integer options.
  • string — a miscellaneous type, whose values are strings of at most 127 characters which must not contain white space.
  • score — the type used for options that give the score of some combination or feature in a hand. A score is either a limit (or a half-limit; the underlying protocol supports percentages of limits, but the current user programs only support limits and half limits); or a number of doubles to be awarded; or a number of points to be added. It is possible (though never needed) to have both points and doubles. If points/doubles are specified as well as a limit, they will be used in a no-limit game. (The server implements a hard limit of 100000000 on all scores to avoid arithmetic overflow, but that's unlikely to worry anybody.)

🌟 Currently supported options 🌟

The following options are implemented in the versions of the program with which this document is distributed. If playing against people with older versions of the software, some options may not be available. The list gives for each option the short name, type, and short description, followed by a detailed explanation.

  • Timeout (nat) — time limit for claims. This is the time in seconds allowed to claim a discard, or to rob a kong. If set to zero, there is no timeout. The default is 15 seconds.
  • TimeoutGrace (nat) — grace period when clients handle timeouts. This period (in seconds) is added to the Timeout above before the server actually forces a timeout. This is for when clients handle timeouts locally, and allows for network lags. If this option is zero, clients are not permitted to handle timeouts locally. The current server also only allows players to handle timeouts locally if all of them wish to do so.
  • ScoreLimit (nat) — limit on hand score. This is the limit for the score of a hand. In a no-limit game, it is the notional value of a "limit" hand. The default is 1000.
  • NoLimit (bool) — no-limit game. If this option is set, the game has no limit on hand scores. The default is unset.
  • MahJongScore (score) — base score for going out. This is the number of points for obtaining Mah-Jong. The default is 20.
  • SevenPairs (bool) — seven pairs hand allowed. If this option is set, then Mah-Jong hands of seven pairs (any seven pairs) are allowed. The default is unset.
  • SevenPairsVal (score) — score for a seven pair hand. This gives the score (in addition to the base Mah-Jong score) for a seven pairs hand. The default is 20.
  • Flowers (bool) — play using flowers and seasons. If this option is set, the deal includes four flowers and four seasons in the Chinese Classical style. If unset, only the 136 standard tiles are used. The default is set.
  • FlowersLoose (bool) — flowers replaced by loose tiles. If playing with flowers, this option determines whether flowers and seasons are replaced from the live wall (unset), or by loose tiles (set). The default is unset.
  • FlowersOwnEach (score) — score for each own flower or season. This option gives the score for having one's own flower or season. If one has both, this score will be given twice. The default is no score.
  • FlowersOwnBoth (score) — score for own flower and own season. This is the score for having both one's own flower and one's own season. Note that this is awarded in addition to twice the previous score. The default is 1 double.
  • FlowersBouquet (score) — score for all four flowers or all four seasons. This is the score for having all four flowers or all four seasons. The default is 1 double.
  • DeadWall (bool) — there is a dead wall. This determines whether there is a dead wall, so that play ends when it is reached (set), or whether all tiles may be drawn (unset). The default is set.
  • DeadWall16 (bool) — dead wall is 16 tiles, unreplenished. If this option is set, then the dead wall initially has 16 tiles, and does not have any more tiles added to it (this is the set-up described by Millington). If the option is unset, then the dead wall initially has 14 tiles, and after two loose tiles have been taken, two tiles are moved from the live wall to the dead wall (this is the set-up described by almost everyone else). The default is unset in versions 1.1 onwards, and set previously. (To be precise, the protocol level default is set, but all servers from 1.1 onwards will change this to unset.)
  • ConcealedFully (score) — score for fully concealed hand. This is the score for a winning hand with no open sets. The default is 1 double.
  • ConcealedAlmost (score) — score for almost concealed hand. This is the score for a hand that is concealed up to the point of going out. The default is no additional score.
  • LosersPurity (bool) — losing hands score doubles for pure, concealed etc. If this option is set, losing hands will score various doubles for one suit, almost concealed, etc. See the rules for details. This option is an (Anglo-)Americanism alien to Chinese Classical (see Foster for a spirited but faulty argument in its favour, and Millington for the rejoinder). The default is unset.
  • KongHas3Types (bool) — claimed kongs count as concealed for doubling. If this option is set, claimed kongs count as concealed for various doubling combinations, although they score as exposed for basic points. See the note above under "Kongs". The default is unset.
  • LosersSettle (bool) — losers pay each other. If this option is set, the losers pay each other the difference between their scores. If it unset, they pay only the winner. The default is set.
  • EastDoubles (bool) — east pays and receives double. If this option is set, payments to and from East Wind are doubled, as in the Chinese Classical game. The default is set.
  • DiscDoubles (bool) — the discarder pays double. If this option is set, the settlement procedure is changed to a style common in Singapore. That is, if the winning player wins off a discard, the discarder pays double the hand value, and the other players pay the hand value. If the winner wins from the wall, then all other players pay double the hand value. The default is unset. Note: EastDoubles and DiscDoubles can be set together, but nobody plays such a rule.
  • ShowOnWashout (bool) — reveal tiles on washout. If this option is set, the players' hands will be revealed in the event of a washout.
  • NumRounds (nat) — number of rounds to play. This option says how many rounds to play in the game. For aesthetic reasons, the possible values are 1, 2, or a multiple of 4. In the 2 round case, the East and South rounds will be played. It defaults to the usual 4 rounds.

📝 Option file format 📝

Both in the option file and in the .xmjrc file, options are recorded in the format used by the server protocol. This is a line of the form

GameOption 0 name type minprot enabled value desc

The meanings of the elements are:

  • GameOption 0 — identifies this as a game option line (the 0 is an irrelevant field from the protocol).
  • name — is the name of the option.
  • type — is the type of the option.
  • minprot — is the minimum protocol version with which the option can be used (which is not necessarily the version at which it was introduced).
  • enabled — will always be 1.
  • value — is the value: a decimal (signed) integer for nat and int; 0 or 1 for bool; the string for string; and for score, if the score is c centi-limits, d doubles and p points, the value is c*1000000 + d*10000 + p.
  • desc — is a short description of the option, which is not required but is usually copied in from the server.

And that's the footer, bestie: J.C.Bradfield, Mah-Jong, XMJ(6). That's the source/version/section right there — the date slot is doing its own mysterious thing (not shown here), but the vibe is timeless. Go slay. 💅🀄✨

📦 where this page comes from