1XMJ(1) General Commands Manual XMJ(1)
2
6 xmj, mj-server, mj-player - programs for playing Mah-Jong
7
9 xmj [--id idnumber]
10 [--server address]
11 [--name playername]
12 [--connect]
13 [--show-wall | --no-show-wall]
14 [--size N]
15 [--animate | --no-animate]
16 [--tileset directory]
17 [--tileset-path directory-path]
18 [--dialogs-popup | --dialogs-below | --dialogs-central]
19 [--use-system-gtkrc | --no-use-system-gtkrc]
20 [--gtk2-rcfile file]
21 [--echo-server]
22 [--pass-stdin]
23 [--monitor]
24 mj-server [--server address] [--timeout seconds]
26 [--pause deciseconds]
27 [--random-seats | --id-order-seats]
28 [--disconnect-penalties N1,N2,N3]
29 [--end-on-disconnect]
30 [--exit-on-disconnect]
31 [--save-on-exit]
32 [--option-file file]
33 [--load-game file]
34 [--no-id-required]
35 [--no-manager]
36 [--auth-basic id:password]*4
37 [--debug]
38 [--logfile file]
39 [--no-special-scores]
40 [--seed N]
41 [--wallfile filefP]
42 [--hand-history]
43 [--nohist]
44 mj-player [--id idnumber] [--name playername]
46 [--server address] [--password password]
47 [strategy options]
48
51 A set of three programs to play Mah-Jong on Unix systems, against peo‐
52 ple or programs, over the Internet.
53 mj-server
55 is the program that handles communications and control of the
56 game; the rules and scoring are enforced there. Players, human
57 or computer, connect to a server via the network.
58 mj-player
60 is a computer player. At present, it is fairly simplistic, hav‐
61 ing only offensive tactics with no knowledge of defensive play.
62 xmj is the X client for human players.
64
67 If you don't want to read this long document: to start a game against
68 three computer players, start xmj, select "New local game..." from the
69 "Game" menu, and click "Start Game". (Wait about ten seconds for every‐
70 thing to start up.)
71
74 All Programs
75 --server address
76 specifies the network address to listen on (for mj-server) or to
77 connect to (for mj-player and xmj). If address contains a
78 colon, it specifies an Internet socket, and should have the form
79 host:port . If address does not contain a colon, it is inter‐
80 preted as a Unix file name and a Unix socket is used. The
81 default value for address is localhost:5000 . address can also
82 be set in a dialog box in xmj.
83 xmj and mj-player
86 --id idnumber
87 The server assigns a unique integer ID (which is currently just
88 1 to 4 in order of connection) to each player. This ID should be
89 quoted when reconnecting to a game in progress (after, for exam‐
90 ple, losing a network connection or accidentally killing xmj).
91 The default ID is 0, which denotes no pre-assigned ID.
92 --name name
94 Players can give themselves names which will be used by client
95 programs. This option specifies the name. For xmj, the default
96 is the value of the environment variable LOGNAME, or failing
97 that the username of the logged in user. For mj-player, the
98 default is "Robot(PID)" where PID is the process id.
99 xmj
102 --connect
103 By default, xmj does not automatically connect to a server, but
104 waits for the user to connect via a menu. If this option is
105 specified, xmj immediately connects.
106 --show-wall
108 --no-show-wall
109 Tells xmj (not) to display the wall. By default, the wall is
110 shown only if running on a big enough screen. This option is
111 also controllable via the Display Options preference panel.
112 --size number
114 This option adjusts the size of the main window. It should be
115 thought of as the length of a tile rack, measured in tiles. The
116 default, and the largest value accepted, is 19, or 18 if on an
117 800x600 display. The smallest usable value is 14. This option is
118 also controllable via the Display Options preference panel.
119 If the --show-wall option is given, a --size smaller than 19
120 will have no effect.
121 --animate
123 --no-animate
124 This option switches on (off) some animation. Not all tile move‐
125 ments are animated: only those that involve moving tiles to or
126 from a hand from outside. This option is also controllable via
127 the Display Options preference panel.
128 --tileset directory
130 xmj needs pixmaps to display the tiles and the tong box. This
131 option tells it which directory to find them in. The default is
132 set at compilation time; the default default is to use the com‐
133 piled-in tiles.
134 --tileset-path directory-path
136 This gives a colon-separated (or semicolon-separated under Mi‐
137 crosoft Windows) list of directories in which to look for the
138 directory named by the --tileset option.
139 --dialogs-popup
141 By default, most of the dialog boxes for player actions are part
142 of the main window. If this option is used, they will instead
143 appear as separate transient windows.
144 --dialogs-below
146 By default, dialog boxes appear in the centre of the table. If
147 this option is given, dialogs (apart from some popups) are posi‐
148 tioned below the table area. Please let me know which style you
149 prefer!
150 --dialogs-central
152 The default: dialog boxes appear in the middle of the table.
153 These options are also controllable via the Display Options
154 preference panel.
155 --gtk2-rcfile file
157 If xmj is compiled with GTK+2, this option specifies a GTK rc
158 file to be used instead of the program's compiled-in style file.
159 This may be used to change the appearance of the program. See
160 description under the Display Options... panel for more details.
161 The file should be an absolute filename; if it is relative, it
162 will be sought in the current directory (Unix) or the program
163 directory (Windows). This option is also controllable via the
164 Display Options preference panel.
165 --use-system-gtkrc
167 --no-use-system-gtkrc
168 When xmj is compiled with GTK+2, by default it ignores the sys‐
169 tem provided settings, to ensure a consistent behaviour across
170 systems. If you wish it to use your system settings, set this
171 option. This option is also controllable via the Display
172 Options preference panel.
173 --echo-server
175 If this option is given, xmj will echo to stdout all the pro‐
176 tocol messages received from the server. This option is for use
177 in debugging.
178 --pass-stdin
180 If this option is given, xmj will send any text given on stdin
181 to the server. This option is for use in debugging.
182 --monitor
184 If this option is given, xmj will send requests to the server
185 only in direct response to user actions; it will take no action
186 itself (and hence all auto-declaring and playing is also dis‐
187 abled). This option is for use in debugging.
188 mj-server
191 --timeout seconds
192 When a discard is made, there is a limit on the time players
193 have to claim it. This option sets the timeout; a value of zero
194 disables it. The default is 15 seconds.
195 This value can also be set via a GameOption request from a
196 player.
197 --pause deciseconds
199 This will make the server enforce a delay of deciseconds/10 sec‐
200 onds between each action in the game; the purpose is to slow
201 programmed players down to human speed (or, in a teaching situa‐
202 tion, to slow the game even more). The current server considers
203 that 50 (i.e. 5 seconds) is the maximum reasonable value for
204 this option. The option can also be requested by players, via a
205 PlayerOption protocol request.
206 --random-seats
208 By default, players are seated in order of connection to the
209 server. This option seats them randomly. It will become the
210 default later.
211 --id-order-seats
213 This option causes the players to be seated in numerical order
214 of their ids. It is used by the xmj program to make the New
215 local game.. work as expected.
216 --disconnect-penalties N1,N2,N3
218 This specifies the penalties applied by the following option for
219 players who disconnect before the end of a game. N1 is the
220 penalty for disconnecting in the middle of a hand; N2 at the end
221 of a hand but in the middle of a round; N3 at the end of a round
222 (other than end of game). They all default to 0 if not speci‐
223 fied.
224 --end-on-disconnect
226 If this option is given, a disconnection by one player will
227 gracefully terminate the game. Mid-hand, the hand is declared a
228 wash-out; after Mah-Jong has been declared, then if a losing
229 player disconnects, their tiles are shown, the hand is scored,
230 and then the game ends; if a winning player disconnects, the
231 hand is a wash-out. The disconnecting player may be assigned a
232 penalty, according to the --disconnect-penalties option, which
233 will be included in the scores printed out by the server. (The
234 penalties will not be visible to the other players.)
235 --exit-on-disconnect
237 If this option is given, the server will quit if any player dis‐
238 connects, rather than waiting indefinitely for reconnection.
239 --save-on-exit
241 If this option is given, the server will save the state of the
242 game if it quits as a result of a player disconnecting. (It will
243 not save the state if it quits as the result of an internal
244 error.)
245 --option-file file
247 This names a file of protocol commands which will be applied to
248 every game when it starts. Its main purpose is to set non-
249 default game options, via the GameOption protocol message (note
250 that this is a CMsg, not a PMsg). However, users will normally
251 set options and preferences via the xmj control panel, not by
252 this means.
253 --load-game file
255 This names a file containing a saved game (as a suitable
256 sequence of protocol commands). The server will load the game;
257 clients connecting will be treated as if they had disconnected
258 and rejoined the game.
259 --no-id-required
261 In the most common case of resuming a saved game, namely one
262 human playing against three robots, the robots will not have the
263 same names or ids as the robots in the original game. This
264 option tells the server that if it cannot match a reconnecting
265 player by id or name, it should anyway match it to one of the
266 previously disconnected players. (In this case, the human nor‐
267 mally connects first with the same name, so is correctly
268 matched.)
269 --no-manager
271 Usually, the first player to connect becomes the game manager,
272 and can change all the game settings. If this option is given,
273 no player will be allowed to change the game settings.
274 --auth-basic id:password
276 This provides basic (insecure, since the password is transmitted
277 in plaintext) authorization: the player with id id must give the
278 specified password to connect. Note that if this argument is
279 given, it must be given four times, once for each authorized
280 player - any player id not mentioned will not be allowed to con‐
281 nect. A player may be allowed to connect without a password by
282 making password empty.
283 --debug
285 This enables various debugging features. In particular, it
286 enables protocol commands that allow one to change the tiles in
287 a hand...
288 --logfile file
290 The server will write a complete record of the game to file;
291 this will be quite large, and is only useful for automatic com‐
292 parison of different computer players.
293 --no-special-scores
295 This option suppresses the scoring of points and doubles for
296 flowers and seasons. It is primarily intended for running tests
297 of different players; for human use, a game option will be pro‐
298 vided to eliminate the specials altogether.
299 --seed n
301 This option specifies the seed for the random number functions.
302 Used for repeatable tests.
303 --wallfile file
305 This names a file containing space separated tile codes giving
306 the wall; used for repeatable tests. (This is a testing option;
307 it is not robust.)
308 --hand-history
310 This is an option to facilitate certain automatic analyses; if
311 set, a history of each hand is dumped to the file hand-NN.mjs .
312 --nohist
314 Another option only used in automatic comparison: this saves
315 some CPU time by disabling the book-keeping required to allow
316 players to disconnect and reconnect.
317 mj-player
320 --password password
321 sets the password if basic authorization is in use.
322 strategy options
324 The player has some options which can be used to change its
325 "personality". The meanings are rather approximate, since they
326 actually change parameters which are used in a rather complex
327 way, but the idea is right. These options, each of which takes a
328 floating point value in the given range, are:
329 --chowness -1.0 .. 1.0
331 This affects how much the player likes chows: at 1.0, it will go
332 all out for the chicken hand, at -1.0 it will never chow. The
333 default is 0.0.
334 --hiddenness 0.0 .. 1.0
336 Increasing this makes the player reluctant to make exposed sets.
337 At 1.0, it will never claim (except possibly to go mah-jong).
338 The default is 0.0.
339 --majorness 0.0 .. 1.0
341 Increasing this biases the player towards collecting major
342 tiles. At 1.0, it will discard all minor tiles, if possible. The
343 default is 0.0.
344 --suitness 0.0 .. 1.0
346 Increasing this makes the player try to go for one-suit hands.
347 The default is 0.0
348 In practice, the --majorness option seems not to be very useful, but
350 the other options change the personality without completely destroying
351 the playing ability.
352 In fact, all these options take a comma-separated list of values, which
354 allows the specifications of a set of strategies, which the player will
355 switch between. In this case, the --hysteresis hhh option specifies how
356 much better a strategy should be to switch to it. However, use of this
357 option, and multiple strategies, is probably only useful if you first
358 read the code to see how it works.
359
362 The main window contains a menu-bar and a table area; the table is in a
363 tasteful shade of dark green. The table displays a stylized version of
364 the game: stylized in that there is no jazzy graphics or perspective,
365 and the tiles are not intended to be pictures of real objects, and so
366 on. Otherwise, the layout is as one would expect of a real game. How‐
367 ever, the wall may or may not be displayed, depending on option set‐
368 tings and screen size. (See above.)
369 Specifically, the four players are arranged around the four edges of
371 the table, with "us" at the bottom. For each player, the concealed
372 tiles are displayed nearest the edge of the table; our own tiles are
373 visible, the other players' tiles are face-down. In front of the con‐
374 cealed tiles are (to the player's left) any declared sets, and (to the
375 player's right) flowers and seasons, and the tong box if the player is
376 East. The tong box displays the wind of the round in a white circle. If
377 necessary, the flowers and seasons will overflow into the concealed
378 row.
379 The discards are displayed face-up in the middle of the board: they are
381 laid down in order by each player, in the natural orientation. TODO:
382 add options to display discards randomly, or face-down. If animation
383 (see --animate option) is not being used, then the most recent discard
384 will be highlighted in red.
385 The name of a face-up tile can be displayed by right-clicking in the
387 tile. Alternatively, the Tiletips display option can be set, in which
388 case the name of a tile is displayed whenever the mouse enters it.
389 Our tiles are displayed in sorted order, which happens to be Bamboos
391 (1-9), Characters (1-9), Circles (1-9), Winds (ESWN), Dragons (RWG),
392 Flowers, Seasons. We can also arrange the tiles ourselves - see the
393 "Sort tiles in hand" display preference described below.
394 Actions are generally carried out by clicking a button in a dialog box
398 that appears in the middle of the board. For many actions, a tile must
399 be selected. A tile is selected or unselected by single-clicking it;
400 when selected, it appears as a depressed button. The program will gen‐
401 erally pre-select a sensible tile: specifically:
402 during the initial declaration of special tiles, the rightmost special
403 is selected;
404 after we draw a tile from the wall, the drawn tile is selected;
405 when declaring concealed sets after going Mah Jong, the first unde‐
406 clared tile is selected.
407 To describe the possible actions, let us run through the course of a
409 game.
410 First select "New local game..." from the "Game" menu. A panel will
412 appear. The default options are to play a game against the computer, so
413 click "Start Game". After a second or two, a game will start. (NOTE:
414 this assumes correct installation. If this fails, start a server and
415 players manually, and use the "Join server..." menu item.)
416 The first thing that happens is a dialog box "Ready to start next
418 hand". The server will not start playing a hand until all players have
419 indicated their willingness to continue play.
420 Next, the tiles are dealt. Then each player in turn is expected to
422 declare flowers and seasons. When it is our turn, a dialog will appear
423 with the following buttons:
424 Declare
426 declare the selected flower or season. (Note: the program auto-
427 selects the rightmost special tile.) If no tile is selected,
428 this finishes declarations. This button will not appear if the
429 game is being played without flowers and seasons.
430 Kong If we have a concealed kong, we can declare it now with this
432 button.
433 Finish Finish declaring specials and kongs.
435 When all players have finished declaring specials and kongs, a dialog
437 box appears, asking (on East's behalf) permission to continue.
438 During play, when we draw a tile from the wall, it will be auto-
440 selected. We may also of course select a different tile. A dialog will
441 appear giving us the following possibilities:
442 Discard
444 discard the selected tile. This button also serves to declare a
445 flower or season, and the label changes to "Declare" when one is
446 selected.
447 &Calling
449 discard the selected tile and declare a calling hand. This but‐
450 ton is only shown when calling is allowed (by default, only
451 Original Call is allowed).
452 Kong declare a concealed kong of the selected tile, or add the
454 selected tile to an exposed pung, as appropriate
455 Mah Jong!
457 declare Mah Jong! (no selection needed)
458 If the wall is not being shown, the dialog will note the number of
460 tiles left in the live wall.
461 A tile can also be discarded simply by double-clicking it.
463 When another player discards, a dialog appears to allow us to claim it.
465 If the dialogs are in the middle of the table, the dialog displays the
466 tile in a position and orientation to indicate the player who dis‐
467 carded; if the dialogs are at the bottom, this is not done, to save
468 space. In any case the dialog displays the name of the tile, and but‐
469 tons for the possible claims. (Note: in the default case, it is possi‐
470 bly confusing that the discarded tile can be seen both on the table and
471 in the dialog box. Opinions are sought on this point.) If the wall is
472 not being shown, the dialog will note the number of tiles left in the
473 live wall. Note: there appear to be subtle bugs in GTK, which mean
474 that sometimes the name of the tile does not appear properly. I have
475 completely failed to track this down; if it happens, just iconify
476 (that's minimize in Windoze-speak) the window and open it again. There
477 is also a `progress bar' which shows how time is running out. The but‐
478 tons use one variant of traditional English terminology, viz:
479 No claim
481 we don't claim this tile. If there is no timeout in operation,
482 it is necessary to click this to indicate a "pass", and in any
483 case it is desirable to speed up play.
484 Chow claim for a sequence. If our claim is successful and there is
486 more than one possible sequence to be made, a dialog will appear
487 asking us to specify which one.
488 Pung claim for a triplet.
490 Kong claim for quadruplet.
492 Mah Jong!
494 claim for Mah Jong. If the claim succeeds, a dialog box will
495 appear asking whether we want the tile for "Eyes", "Chow",
496 "Pung", or a "Special Hand" (such as Thirteen Unique Wonders).
497 (The term "Eyes" is used instead of "Pair" so that when keyboard
498 accelerators are implemented, E is different from P! Is it bet‐
499 ter to stick to "Pair"?)
500 When a player (including us) claims, the word "Chow!" etc. will appear
502 (in big letters on a yellow background, if things are correctly set up;
503 please tell me if this doesn't happen) for a couple of seconds above
504 the player's tiles.
505 When all players have claimed, or timed out, the successful claim is
507 implemented; no additional announcement is made of this. (Should it
508 be?)
509 If a player adds a tile to an exposed pung, and that tile would give us
511 Mah Jong, then a dialog box pops up to ask whether we wish to rob the
512 kong.
513 After somebody goes Mah Jong, we are asked to declare our concealed
515 sets. A dialog appears with buttons for "Eyes", "Chow", "Pung". To
516 declare a set, select a tile, which must be the first tile in the set
517 for a chow, and click the appropriate button. (If we are going Mah
518 Jong, the first undeclared tile is auto-selected.) When finished, click
519 "Finished" to reveal the remaining tiles to the other players. If we
520 are the winner, there will be a button for "Special Hand": this is used
521 to declare hands of non-standard shape, such as Thirteen Unique Won‐
522 ders. (Note: the Seven Pairs hand, if in use, should be declared by
523 means of the "Eyes" button, not the "Special Hand" button.)
524 At this point, a new top-level window appears to display the scoring
526 information. The scoring is done entirely by the server, not by the
527 players; the server sends a text description of the score calculation,
528 and this is displayed for each player in the Scoring window. The
529 information in the Scoring window remains there until the next hand is
530 scored; the window can be brought up at any time via the "Show" menu.
531 Finally, the "continue with next hand" dialog appears. The hand just
533 completed will remain visible on the table until the next hand starts.
534 Keyboard Accelerators
537 There are keyboard accelerators for all the actions in the course of
538 play. For selecting tiles, the Left and Right arrow keys can be used to
539 move the selection left or right along the row of tiles. In all
540 dialogs, Space or Return will activate the shadowed button, which is
541 usually the commonest choice. Each button can also be activated by typ‐
542 ing the underlined letter. (In the Windows GTK1 build, use l (ell) and
543 r instead of Left and Right. The button accelerators do not work, for
544 reasons unknown to me.)
545 The menus are also accessible via accelerators. To open a menu, press
546 Meta-X (Alt-X on Windows), where X is the underlined letter in the menu
547 name. (Meta-X is often (confusingly) Alt-X on Linux systems.) Then
548 each entry has an underlined letter which if pressed will activate it.
549 An additional top-level window showing the state of the game can be
552 obtained by selecting "Game info" from the "Show" menu.
553 There is also a facility for sending text messages to the other play‐
555 ers. Select "Messages" from the "Show" menu, and a window will appear:
556 in the top is a display of all messages sent, and below is a single
557 line in which you can enter your message. It will be sent when you hit
558 Return. The message window pops up automatically whenever a message is
559 received, unless prevented by a display preference. If the "Display
560 status and messages in main window" display option is set, then this
561 window will instead appear in the main window, above the table. In that
562 case, there is a checkbox "Keep cursor here" next to the message entry
563 line. Checking this box will ensure that the keyboard focus stays in
564 the message entry field, even when you click on buttons in the game.
565 (Consequently, you will be unable to use keyboard accelerators while
566 this option is checked.)
567 Starting games and re-connecting
570 The "Game" menu has the "New local game..." item to start a new game on
571 your local computer, and the "Join server..." item to connect to an
572 existing game. The dialogs for both these have the following entries:
573 Checkboxes for Internet/Unix server
575 These specify whether the server is listening on an Internet
576 socket or a Unix socket. If an Internet (TCP) socket, the host
577 name ("Join Game..." only) and port number should be entered in
578 the appropriate boxes; if a Unix socket, the file name of the
579 socket should be entered. These fields are remembered from game
580 to game.
581 "Player ID" and "Name" fields
583 The "Player ID" should be left at 0, unless reconnecting to an
584 existing game, in which case it should be the ID assigned by the
585 server on first connecting to that game. The "Name" field can be
586 anything. When reconnecting to an existing game, if the ID is
587 given as 0, the server will try to use the "Name" to identify
588 the player. (This may not be true in future.) The "Name" field
589 is remembered from game to game.
590 The "Join server..." dialog then simply has a "Connect" button to
592 establish the connection. The "New local game..." has the following
593 fields:
594 For each of three further players,
596 A checkbox to say whether to start a computer player. (Some of)
597 these should be unchecked if you wish other humans to join the
598 games. If checked, there is a text entry to set the players'
599 names, and a text entry field in which options can be given to
600 the players; the latter should only be used if you understand
601 the options!
602 An "allow disconnection" checkbox
604 If this is checked, the server that is started will continue to
605 run even if players disconnect. If it is not checked, the server
606 will quit if any player disconnects. If you are playing one
607 against the computer, this should generally be left unchecked,
608 in order to avoid server processes accidentally being left lying
609 around. If playing against people, it should be checked, to
610 allow players to go away, or to guard against network outages.
611 As "save game state on exit" checkbox
613 If this is checked, the server will save the game state (see
614 below on on saving and resuming games) when a player disconnects
615 and causes it to quit.
616 A "seat players randomly" checkbox
618 If this is left unchecked, players will be initially seated as
619 East, South, West, North in order of connection. (We always con‐
620 nect first.) If it is checked, the seating will be random.
621 A numeric entry field
623 to specify the time limit for claiming discards. If set to 0,
624 there will be no time limit.
625 A button to start the game
627 Note that it takes a few seconds to start a game, during which
628 time the dialog stays up with the button pressed. (TODO: fix
629 this!)
630 Saving and resuming games
633 At any time during the play of a game, you can choose the "Save" entry
634 from the "Game" menu. This causes the server to save the current state
635 of the game in a file. The file will be named game-date.mjs by default;
636 if a name has previously been specified, or if the game was resumed
637 from a file, that name will be used. To specify a name, use the "Save
638 as..." entry in the "Game" menu. Note that for security, directories
639 cannot be specified (except by resuming a game), so the file will be
640 created in the working directory of the server.
641 To resume a saved game, use the "Resume game..." entry from the "Game"
643 menu. This is just like the "New local game..." panel, but it has a box
644 to specify the file containing the saved game. At present, you must
645 type the name of the file into this box. TODO find a file selector wid‐
646 get for this.
647 Setting display and game options
650 The "Options" menu of xmj brings up panels to set various options
651 related to the display and to the game rules. Most of these options
652 can be stored in the preferences file, which is .xmjrc in your home
653 directory on Unix, and xmj.ini in your home (whatever that means)
654 directory on Microsoft Windows.
655 Display Options
658 This panel controls options related to the local display. At the bot‐
659 tom are three buttons: "Save & Apply" applies changes and saves them in
660 the preferences file for future sessions; "Apply (no save)" applies any
661 changes, but does not save them; "Cancel" ignores changes. Note that
662 many display options can also be controlled by command-line arguments;
663 if an option is specified both in the preferences file and on the com‐
664 mand line, the command line takes priority.
665 Position of action dialogs.
667 This determines where the dialogs for user actions in the game
668 are popped up; see the description of the --dialogs-central etc.
669 options above. This option is stored in the preferences file as
670 Display DialogPosition posn
671 where posn is one of "central", "below" or "popup".
672 Animation
674 determines whether tile movements are animated (see the --ani‐
675 mate option above). This option is stored in the preferences
676 file as
677 Display Animate bool
678 where bool is "0" or "1".
679 Display status and messages in main window
681 puts the game status and message (chat) windows in the main win‐
682 dow, above the table, instead of having separate popup windows.
683 This option is stored in the preferences file as
684 Display InfoInMain bool
685 where bool is "0" or "1".
686 Don't popup scoring/message windows
688 will prevent the automatic popup of the scoring window at the
689 end of a hand, the message window on the arrival of a message,
690 and the game status window at the end of the game. This option
691 is stored in the preferences file as
692 Display NoPopups bool
693 where bool is "0" or "1".
694 Tiletips always shown
696 means that the name of a tile is displayed whenever the mouse
697 enters it, and the name of the selected tile is always shown.
698 (Otherwise, right-click to display the name.) This option is
699 stored in the preferences file as
700 Display Tiletips bool
701 where bool is "0" or "1".
702 Display size
704 This drop-down list specifies the size of the display. The size
705 should be thought of as the length of a tile rack. This is only
706 relevant if the wall is not being displayed. Values range from
707 14 to 19; if "(auto)" (the default) is specified, the client
708 tries to choose a size as big as will fit in the display. This
709 option can also be specified by the command line --size argu‐
710 ment. This option is stored in the preferences file as
711 Display Size n
712 Show the wall
714 "always" is equivalent to the --show-wall option; "never" is
715 equivalent to the --no-show-wall option; and "when room" is the
716 default. This option is stored in the preferences file as
717 Display ShowWall when
718 where when is one of "always", "when-room" or "never".
719 Sort tiles in hand
721 By default, the program maintains your own tiles in sorted
722 order. If you prefer to leave them unsorted (which is often
723 recommended in real life, to avoid giving information to your
724 opponents), or to arrange them yourself, you can set this option
725 to "never", or to "on deal" if you want them to be sorted at the
726 beginning, but then left alone. To rearrange tiles, use the
727 Shift-Left and Shift-Right (i.e. the left and right arrow keys
728 while holding Shift) - these move the selected tile left or
729 right in your hand. (In the Windows GTK1 build, use L (Shift-l)
730 and R (Shift-r) instead.) On GTK2 builds, you can also drag a
731 tile to its new position with the mouse. This option is stored
732 in the preferences file as
733 Display SortTiles when
734 where when is one of "always", "deal" or "never".
735 Iconify all windows with main
737 If this option is set (the default), then when the main xmj win‐
738 dow is iconified, (almost) all other open windows such as
739 dialogs will also be iconified; when the main window is uniconi‐
740 fied, the other windows will also be uniconified. If it is not
741 set, all windows are independent of one another. This option is
742 stored in the preferences file as
743 Display IconifyDialogs bool
744 This option is not currently supported under Microsoft Windows.
745 Tileset
747 this is the tile pixmap directory, also given by the --tileset
748 option. This option is stored in the preferences file as
749 Display Tileset dirname
750 Tileset Path
752 this is the search path for tileset directories, also given by
753 the --tileset-path option. This option is stored in the prefer‐
754 ences file as
755 Display TilesetPath search-path
756 Main font selection...
758 This button brings up a font selection dialog to choose the font
759 used in buttons, menus, etc. in the client. This option is
760 stored in the preferences file as
761 Display MainFont font-name
762 where font-name is a font name, which may be an X LFD in the
763 Unix GTK+1 version, or a Pango font name in the Windows and Unix
764 GTK+2 versions.
765 Text font selection...
767 This button brings up a font selection dialog to choose the font
768 used in text display (such as scoring info and chat) in the
769 client. This option is stored in the preferences file as
770 Display TextFont font-name
771 Table colour selection...
773 Unaccountably, not everybody likes my choice of dark green for
774 the table background. This button brings up a colour selection
775 box to allow the table colour to be changed.This option is
776 stored in the preferences file as
777 Display TableColour col
778 where col is a GTK colour specification. The format depends on
779 whether xmj is built with GTK+1 - in which case it is an X color
780 of the form rgb:RRRR/GGGG/BBBB - or GTK+2 - in which case it is
781 a GTK2 color of the form #RRRRGGGGBBBB. GTK+2 programs will con‐
782 vert an old GTK1 specification.
783 Gtk2 Rcfile:
785 In the GTK+2 build, xmj by default ignores completely the system
786 and user settings for look and feel, and uses its own built in
787 settings. These settings use the Clearlooks theme, if it is
788 available, to provide a simple but clean look with slightly
789 rounded tiles; and fall back to a plain theme, as compact as
790 possible with the standard engine. If you wish, you can use this
791 option to specify the name of a GTK rcfile which will be read
792 instead of the built in settings. A minimal set of settings
793 will be read before your file is read. Such a file can specify
794 many details of the appearance, provided that you know how to
795 write a GTK rcfile. You will need to know that xmj uses the fol‐
796 lowing styles and bindings:
797 gtk-font-name = fontname
798 can be used to change the overall font used by widgets. This
799 will overridden by the font specified by the Main Font option,
800 if set.
801 style "table"
802 is used to give the green (or whatever you set) colour to the
803 table. All widgets that should have this style are named "ta‐
804 ble", so the appropriate binding (already set in the minimal
805 set) is
806 widget "*.table" style "table"
807 style "playerlabel"
808 is used to give the white text colour to the player status
809 labels in the corners of the board (if shown). All widgets that
810 should have this style are named "playerlabel", so the appropri‐
811 ate binding (already set in the minimal set) is
812 widget "*.playerlabel" style "playerlabel"
813 style "tile"
814 is used in the default settings for all widgets named "tile",
815 which are all tiles except the tiles in your own concealed hand.
816 This style is not used in the minimal settings, but if set it
817 should be bound with
818 widget "*.tile" style "tile"
819 style "mytile"
820 is used in the default settings for the concealed tiles in your
821 hand, which are active buttons. These tiles are all named
822 "mytile". This style is not used in the minimal settings, but if
823 set it should be bound with
824 widget "*.mytile" style "mytile"
825 style "claim"
826 is used to set the yellow background and large font of the claim
827 announcement popups. These popups are named "claim", so the
828 appropriate binding (already set in the minimal set) is
829 widget "*.claim" style "claim"
830 style "text"
831 is used to change the font for the text widgets such as message
832 boxes and input fields. In the minimal settings, it is empty,
833 but is defined and bound to the relevant widgets. The binding
834 should not be changed, but the style itself can be redefined. If
835 the Text Font option is set, this style will be redefined in
836 order to implement it.
837 binding "topwindow"
838 is defined and bound to the top-level window to implement the
839 use of the left and right arrow keys to change the selected
840 tile. It is probably not helpful to change this.
841 The distribution contains three example gtkrc files, called
842 gtkrc-minimal, gtkrc-plain, and gtkrc-clearlooks, which contain
843 the program's compiled in settings.
844 This option is stored in the preferences files as
845 Display Gtk2Rcfile file-name
846 Note that if the file-name is relative, it will be interpreted
847 relative to the current directory in Unix, or the program direc‐
848 tory in Windows.
849 Use system gtkrc
851 As noted above, xmj does not normally load the system settings
852 in the GTK+2 build. If this option is checked, it will (after
853 the minimal settings, but before the default or user-specified
854 settings). This option is stored in the preferences files as
855 Display UseSystemGtkrc bool
856 where bool is 0 or 1.
857 Note for GTK+1 builds
859 Under a GTK+1 build, xmj does what any other application does.
860 This should allow the use of a .gtkrc file to change colours,
861 using the styles and bindings given above. However, this is not
862 a supported activity.
863 Playing Preferences
866 This panel controls what actions the client may take on your behalf.
867 The first (and currently only) section specifies when the client should
868 declare tiles and sets for you. It has the following checkboxes:
869 flowers and seasons
871 if checked, will be automatically declared as soon as drawn.
872 losing hands
874 if this is checked, then when somebody else goes out, the client
875 will declare your closed sets. It declares in the order pungs,
876 pairs, chows.
877 winning hands
879 this is the same for when you go out.
880 The panel has "Save & Apply", "Apply (no save)" and "Cancel" buttons,
882 as in the display options panel.
883 Game Option Preferences
886 This panel controls preferred game options which will be sent to the
887 server when a game starts. Preferences will only be applied if we are
888 the game manager, or the game has no manager. (Normally, the first
889 human player to connect to the server becomes the game manager.)
890 For details of options and their meanings, see the Game Options section
891 in the rules.
892 The panel has two action buttons, "Save Changes" and "Cancel", with the
893 obvious meanings. Note if a game is in progress, changed preferences
894 are NOT applied to it; however, there is a button in the Current Game
895 Options panel to apply preferences.
896 The main body of the panel is a scrollable window listing all the known
897 options. If no preference is stored for the FooBar option, then there
898 is an "Add pref" button next to a description of the FooBar option. If
899 this button is clicked, an entry for setting the option appears. The
900 format of this entry depends on the type of the option (see the Game
901 Options section of the rules for details of types):
902 Boolean (on/off) options
904 have a checkbox.
905 Integer options
907 have a spinbutton for numerical entry: the value can be typed
908 in, or the up and down arrows can be used to change it
909 Score options
911 have radio buttons for selecting Limit, Half-Limit, or other;
912 for other, the number of doubles and/or points is entered with
913 spinbuttons. (Note: the underlying protocol allows percentages
914 (possibly more than 100%) of limits to be specified for scores;
915 however, the current graphical interfaces allow only limits or
916 half-limits. Even half-limits are pretty strange, but some
917 bizarre sets of rules, such as those of the British Mah-Jong
918 Association (which plays a weird American/Western/Chinese mix),
919 allow other fractions of limits.)
920 String options
922 have a simple text entry field.
923 All option entries have a "Reset" button which returns the entry to its
925 previous state.
926 A preference is removed by clicking the "Remove pref" button.
927 Current Game Options
930 When there is a connected game, this panel allows its game options to
931 be modified (if we have permission to do so). The three action buttons
932 are "Apply changes", which applies the panel's settings to the current
933 game; "Apply prefs", which applies our preferences (as described above)
934 to the current game; and "Cancel".
935 The body of the panel contains entries for all the options of the cur‐
936 rent game, in the same format as the preferences panel (see above).
937
940 The latest release of the Unix Mah-Jong programs should be available at
941 http://mahjong.julianbradfield.org/
942
945 The game currently implemented is a version of the classical Chinese
946 game. The most convenient and comprehensive set of rules is that pro‐
947 vided by A. D. Millington, "The Complete Book of Mah-Jongg", Weiden‐
948 field & Nicolson (1993), ISBN 0 297 81340 4. In the following, M 103
949 denotes item 103 of the rules laid out in Chapter 3 of that book. I
950 here describe only the differences from these rules, some of which dif‐
951 ferences are consequences of using computers, and some of which are
952 points where my house rules differ from Millington's version. In due
953 course, all variations (of Chinese classical) will be accommodated, if
954 there is sufficient desire.
955 Classification of tiles (M 1-8): the tiles are a standard Chinese set.
957 The tiles do not have Arabic numerals, except for the flowers and sea‐
958 sons, where the identifying Chinese characters are too small to be leg‐
959 ible. A numbered set is included in the distribution and can be used
960 via the Tileset display preference.
961 The flowers and seasons may be removed from the tile set by unsetting
962 the Flowers game option.
963 Preliminary (M 9-10): nothing to say.
965 Duration of the game (M 11-14): standard rules. In particular, the
967 title of East does not pass after a wash-out.
968 Selection of seats (M 15): the players are seated in the order they
970 connect to the server, or randomly, according to the option given to
971 the server.
972 The deal etc. (M 16-27): There is no attempt to simulate the usual
974 dealing ritual (M 16-20, 23-26); the wall is built randomly by the
975 server. The dead wall is also maintained by the server.
976 The existence of a dead wall is controlled by the DeadWall game option;
977 normally there is a dead wall.
978 The deal wall is either 14 tiles and kept at 13 or 14 during play (as
979 in most authors), or is 16 tiles, not extended during play (per
980 Millington (M 22)), according to the DeadWall16 game option.
981 Replacement tiles for kongs are always taken from the loose tiles, but
982 replacements for bonus tiles may be drawn from the live wall (M 31), or
983 from the loose tiles, according to the FlowersLoose game option.
984 Object of game (M 28-31): all winning hands must comprise four sets and
986 a pair, with the exception of the Thirteen Unique Wonders. If the Sev‐
987 enPairs game option is set, then a hand of any seven pairs is also
988 allowed as a winning hand.
989 Bonus tiles (M 31): M requires that bonus tiles must be declared in the
991 turn in which they are drawn; otherwise the player may not exchange or
992 score them (and thus they cannot go out). We do not make this restric‐
993 tion, as it is (a) pointless (b) unenforceable in real life. Bonus
994 tiles may be declared at any time after drawing from the wall. (Obvi‐
995 ously, there is no reason not to declare them immediately.)
996 Commencement of the Game (M 32-33): standard.
998 Playing procedure (M 34-38): standard. In particular, the other play‐
1000 ers have to give permission for east to start playing (M 34). The dis‐
1001 play of discards cannot be controlled by the server; the current X
1002 client displays them in an organized fashion, rather than the random
1003 layout required by M 35.
1004 Chow (M 39-42): standard.
1006 Pung (M 43-45): standard.
1008 Kongs (M 46-52): M distinguishes three types of kong: concealed,
1010 claimed (by Kong), and annexed (formed by adding a discard to an
1011 exposed pung), and allows claimed kongs to be counted as concealed for
1012 the purposes of doubling combinations. I have not seen this anywhere
1013 else; normally, a claimed kong is treated as exposed for all purposes.
1014 We follow the normal convention; however, the game option KongHas3Types
1015 can be set to implement M's rules. In this case, the xmj program will
1016 distinguish claimed kongs by displaying them with the last tile face
1017 down, whereas annexed kongs are all face up.
1018 Players may declare a concealed kong, or add to a pung, only when they
1019 have just drawn a tile from the wall (live or dead); not just after a
1020 claiming a discard. (A silly restriction in my view, but one that all
1021 rule sets seem to have (M 51).)
1022 Calling and Mah Jong (M 53-54): standard. (I.e. there is no "Calling"
1024 declaration.)
1025 NOTE: M permits players to change their mind about making a claim (M
1027 69); we do not, and all claims are irrevocable. Question: should we
1028 allow revocation?
1029 Original Call (M 55): the Original Call declaration must be made simul‐
1031 taneously with the first discard, rather than afterwards. NOTE: the
1032 server does *not* check that the declarer does indeed have a calling
1033 hand, as a mistaken original call does not damage the other players or
1034 the progress of the game. The server does, however, thereafter prevent
1035 the declarer from changing their hand; therefore a mistaken original
1036 call will make it impossible to go out. (Note: in M, an Original Caller
1037 may change their hand, but will thereby lose the ability to go out (M
1038 55(b)); is this a better way to treat it?) Note also: as per M, an
1039 original call can be made even if another player has claimed a discard
1040 before, unlike the Japanese version.
1041 Robbing a Kong (M 57-60): Robbing a kong is implemented. However, as
1043 with discards, we require that kongs are robbed before anything else
1044 happens, and in particular before the konger draws a replacement tile.
1045 Therefore, after a kong, all other players must either claim Mah Jong
1046 or pass. (The provided programs will pass automatically if robbing is
1047 not possible.) As for discards, there is a time limit.
1048 Precedence of claims for discard (M 61-65): Many rules allow a discard
1050 to be claimed up until the time the next discard is made. M does this,
1051 with elaborate rules for the precise specification. For ease of imple‐
1052 mentation, we do not allow this: instead, all players are required to
1053 make a claim or pass, and once all players have claimed, the successful
1054 claim is implemented irrevocably. The server imposes a time limit;
1055 players that do not claim within the limit are deemed to have passed.
1056 This defaults to 15 seconds, but can be changed or disabled by the
1057 Timeout game option.
1058 Irregularities in Play (M 66-81): the server does not permit unlawful
1060 moves, and so no irregularities can arise.
1061 False Declaration of Mah Jong (M 82-83): such declarations are not per‐
1063 mitted by the server.
1064 False Naming of Discards (M 84-88): this also cannot happen.
1066 Incorrect Hands (M 89): cannot happen.
1068 Letting Off a Cannon (M 90-96): as in M. However, if a player makes a
1070 dangerous discard, but has no choice, the server will determine this;
1071 it is not necessary to plead "no choice" explicitly, and neither is the
1072 player's hand revealed to the other players.
1073 Wash-Out (M 97-99): standard.
1075 Points of Etiquette (M 100-102): not applicable.
1077 Displaying the Hand (M 103-106): The format of display is a matter for
1079 the client program, and cannot be controlled by the server.
1080 After Mah Jong, the players are responsible for declaring concealed
1081 sets in whatever way they wish. The winner, of course, is required to
1082 declare a complete hand; but the losers may declare as they wish. Once
1083 a set is declared, it cannot be revoked. Note that the losers may
1084 declare multiple scoring pairs.
1085 Procedure in Settlement (M 107-111): The settlement is classical: that
1087 is, the winner gets the value of their hand from all players; the
1088 losers pay one another the differences between their scores; except all
1089 payments to or from East are doubled; and if players let off a cannon,
1090 they pay everybody's debt. Unlike normal play (M 110), all hands are
1091 scored by the server, rather than by the players. Settlement is also
1092 computed by the server. Some variations in settlement are provided: if
1093 the LosersSettle game option is set to false, there are no payments
1094 between losers; if the EastDoubles game option is set to false, pay‐
1095 ments to or from East are not doubled; if the DiscDoubles game option
1096 is set to true, then the discarder of the tile that gave Mah-Jong will
1097 pay double to the winner, and a self-draw is paid double by everybody.
1098 Method of Scoring (M 112-122): The method is standard (M 112), viz cal‐
1100 culate points obtained from sets and bonuses, and then apply doubles.
1101 The following points are given for tiles:
1103 Bonus tiles:
1105 4 each (M 114(a))
1106 Pungs: 2 for exposed minor tiles; 4 for exposed major or concealed
1108 minor; 8 for concealed major. (M 114(b))
1109 Kongs: 8 for exposed minor; 16 for exposed major or concealed minor; 32
1111 for concealed major. (M 114(c))
1112 Chows: no score. (M 114(d))
1114 Pair: 2 for a pair of Dragons, Own Wind, or Prevailing Wind. A pair
1116 that is both Own and Prevailing Wind scores 4. (M 114(e)) Non-
1117 winning hands may score more than one pair.
1118 Basic points:
1120 the winner gets 20 points for going Mah Jong. This can be
1121 changed by the MahJongScore game option (M 115(a) has 10
1122 points).
1123 Seven Pairs hand:
1125 If Seven Pairs hands are allowed, they receive an additional
1126 score of 20 points, changed by the SevenPairsVal game option.
1127 Winning from wall:
1129 if the final tile is drawn from the wall, 2 points are added (M
1130 115(b)).
1131 Filling the only place:
1133 if the final tile is the only denomination that could have com‐
1134 pleted the hand, 2 points are added (M 115(c)). NOTE: As in M,
1135 if all four copies of a tile are exposed on the table, it does
1136 not count as available for completing the hand.
1137 Fishing the eyes:
1139 a player who completes by obtaining a pair gets 2 points if the
1140 pair is minor, or 4 if major (M 115(d)). Note: to obtain these
1141 points for a discard, the player must actually claim the discard
1142 for a pair: e.g. if waiting on 5677, and 7 is discarded, the
1143 player must claim for the pair, not the chow.
1144 The following doubles apply to all hands. All possible clauses apply
1146 unless stated otherwise.
1147 Having own flower or own season.
1149 No extra score. Changed by the FlowersOwnEach game option.
1150 Having own flower AND own season,
1152 1 double. (M 116(a)). Changed by the FlowersOwnBoth game option.
1153 Having all four flowers,
1155 1 double. (M 116(b)). Changed by the FlowersBouquet game option.
1156 Having all four seasons,
1158 1 double. (M 116(b)). Changed by the FlowersBouquet game option.
1159 Each set of dragons,
1162 1 double. (M 116(d))
1163 A set of the player's own wind,
1165 1 double. (M 116(e))
1166 A set of the prevailing wind,
1168 1 double. (M 116(f))
1169 "Little Three Dragons": two sets and a pair of dragons.
1171 1 double. (M 116(g))
1172 "Big Three Dragons": three sets of dragons.
1174 2 doubles. (M 116(h))
1175 "Little Four Winds": three sets and a pair of winds.
1177 1 double. (M 116(i))
1178 "Big Four Winds": four sets of winds.
1180 2 doubles. (M 116(j))
1181 (Note: the definitions of these last four doubles when applied
1183 to non-winning hands are subject to wide variations. Possibly
1184 there should be options to allow other possibilities.)
1185 Three concealed pungs:
1187 1 double. (M 116(k)) (Note: if the KongHas3Types game option is
1188 set, a claimed kong counts as concealed for this hand; see the
1189 note above under "Kongs".)
1190 The following doubles apply to the winning hand only:
1192 No score hand: four chows and a non-scoring pair.
1194 1 double. (M 117(a)) (Note: like M, we allow any of the extra
1195 points (Fishing the Eyes, etc) to go with this double. Some
1196 rules say that the extra points invalidate this hand. Possibly
1197 there should be an option for this.)
1198 No chows:
1200 1 double. (M 117(b))
1201 Concealed hand:
1203 1 double (M 117(c)), changeable with the ConcealedFully game
1204 option. (Note: this means a hand that is fully concealed after
1205 going out. Another common value for this is 3 doubles, in which
1206 case 1 double is usually given for a semi-concealed hand (see
1207 below).) (Note: if the KongHas3Types game option is set, a
1208 claimed kong counts as concealed for this hand; see the note
1209 above under "Kongs".)
1210 The following doubles normally apply to the winning hand only; however,
1212 the LosersPurity game option can be set to allow losing hands to score
1213 them (this is a highly deprecated American feature, but has been
1214 requested by a user).
1215 Semi-concealed hand:
1217 no doubles, changeable with the ConcealedAlmost game option.
1218 (Not in M) (Note: this means a winning hand that is concealed up
1219 to the point of going out, or, if enabled, a concealed losing
1220 hand. According to a discussion on rec.games.mahjong, a winning
1221 semi-concealed hand is classically awarded one double (with
1222 three given for fully concealed). One book in my possession
1223 (U.S.A., early 1920s) awards this double only to a hand that is
1224 concealed except for the pair.) (Note: if the KongHas3Types
1225 game option is set, a claimed kong counts as concealed for this
1226 hand; see the note above under "Kongs".)
1227 One suit with honours:
1229 1 double. (M 117(d))
1230 One suit only:
1232 3 doubles. (M 117(e))
1233 All majors:
1235 1 double. (M 117(f))
1236 All honours (in an unlimited game):
1238 2 doubles. (M 117(g)) (Note: such a hand will also score the
1239 double for all majors.)
1240 All terminals (in an unlimited game):
1242 2 doubles. (Not in M) (Note: such a hand will also score the
1243 double for all majors.)
1244 The following doubles apply only to the winning hand:
1246 Winning with loose tile:
1248 1 double. (M 117(h)) (Note: with the default settings, replace‐
1249 ments for bonus tiles come from the live wall. Hence this double
1250 applies only to winning after Kong.)
1251 Winning from the bottom of the sea (winning with last tile),
1253 1 double. (M 117(i))
1254 Catching a fish from the bottom of the sea (winning with last discard),
1256 1 double. (M 117(j))
1257 Robbing a kong,
1259 1 double. (M 117(k))
1260 Completing Original Call,
1262 1 double. (M 117(l))
1263 Limit (M 118-120): the limit is 1000 by default, and can be changed by
1265 the ScoreLimit game option. The NoLimit game option can be used to play
1266 a game "with the roof off".
1267 The following hands are limit hands:
1270 Heaven's Blessing: East wins with dealt hand. (M 122(a))
1272 Earth's Blessing: player wins with East's first discard. (M 122(b))
1274 Gathering Plum Blossom from the Roof: winning with 5 Circles from the
1276 loose wall. (M 122(c))
1277 Catching the Moon from the Bottom of the Sea: winning with 1 Circle as
1279 the last tile. (M 122(d)) (Note: M says that the tile must be
1280 drawn. It seems more reasonable also to allow it to be the last
1281 discard, which is what we do. Objections?)
1282 Scratching a Carrying Pole: robbing a kong of 2 Bamboos. (M 122(e))
1284 (Note: these last three limits are rather arbitrary, but of the
1286 arbitrary limits they are apparently the most common. There
1287 should be options to disable them.)
1288 Kong upon Kong: making a Kong, making another Kong with the loose
1290 tile, and with the second loose tile obtaining Mah Jong. (Also,
1291 of course, with three or four successive kongs.) (M 122(f))
1292 Four Kongs. (M 122(g))
1294 Buried Treasure: all concealed and no chows. (M 122(h))
1296 The Three Great Scholars: three sets of dragons and no chows. (M
1298 122(i))
1299 (Note: in most rules I have seen, there is no restriction to a
1300 no chow hand. Since in M's rules, three sets and a chow scores
1301 at least (10 (M has 10 for Mah Jong) + 12 (at least 3 pungs))
1302 times 8 (2 for each set of dragons) times 4 (for Big Three Drag‐
1303 ons) = 704, this is significant with the default limit. For us,
1304 with 20 for going out, Big Three Dragons is over the default
1305 limit anyway.)
1306 Four Blessings o'er the Door: four sets of winds and a pair. (M 122(j))
1308 All Honours. (M 122(k))
1310 Heads and Tails: all terminals. (M 122(l))
1312 Imperial Jade: contains only Green Dragon and 2,3,4,6,8 Bamboo. (M
1314 122(m))
1315 (Note: another rather arbitrary hand, but widely adopted.)
1316 Nine Gates: calling on 1-1-1-2-3-4-5-6-7-8-9-9-9 of one suit. (M
1318 122(n)).
1319 Wriggling Snake: 1-1-1-2-3-4-5-6-7-8-9-9-9 plus 2, 5 or 8 of
1321 one suit (M 122(o)). (Note: another rather arbitrary hand.)
1322 Concealed Clear Suit: one suit only and all concealed. (M 122(p))
1324 Thirteen Unique Wonders: one of each major tile, and a match to any of
1326 them. (M 122(q))
1327 East's 13th consecutive Mah-Jong. (M 122(r))
1329 General note: there are many other doubles and limits kicking around. I
1331 welcome opinions on which should be possible options; and also on which
1332 of the above I should eject from the default set. I dislike Imperial
1333 Jade, Wriggling Snake, and the ones depending on a specific tile (Gath‐
1334 ering Plum Blossom, Catching the Moon, Scratching a Carrying Pole):
1335 which of these are so commonly adopted that they should be in even a
1336 fairly minimalist default set?
1337
1340 This section describes the options that can be set in the game. Whether
1341 an option can be used, depends on the version of the programs. This is
1342 described by a "protocol version number"; this is not strictly speaking
1343 a version just of the communication protocol, but a version number
1344 reflecting the combination of protocol and programs. When playing by
1345 oneself, this does not matter, but in the case of a networked game,
1346 players might have different versions of the software, in which case
1347 the game is played according to the lowest version of any player.
1348 Game options can be controlled in two ways: the --option-file argument
1350 to the mj-server program gives options to be applied to the game, or
1351 options can be set by the players, using the interface described in the
1352 manual section for xmj.
1353 In the user interface, the options are referred to by a one line
1355 description, but each option also has a short name, given here.
1356 Options are of several types:
1358 bool boolean, or on/off, options.
1360 int integer options
1362 nat non-negative integer options
1364 string is a miscellaneous type, whose values are strings of at most 127
1366 characters which must not contain white space
1367 score is the type used for options that give the score of some combi‐
1369 nation or feature in a hand. A score is either a limit (or a
1370 half-limit; the underlying protocol supports percentages of lim‐
1371 its, but the current user programs only support limits and half
1372 limits); or a number of doubles to be awarded; or a number of
1373 points to be added. It is possible (though never needed) to have
1374 both points and doubles. If points/doubles are specified as well
1375 as a limit, they will be used in a no-limit game. (The server
1376 implements a hard limit of 100000000 on all scores to avoid
1377 arithmetic overflow, but that's unlikely to worry anybody.)
1378 Currently supported options
1381 The following options are implemented in the versions of the program
1382 with which this document is distributed. If playing against people with
1383 older versions of the software, some options may not be available. The
1384 list gives for each option the short name, type, and short description,
1385 followed by a detailed explanation.
1386 Timeout (nat) time limit for claims
1389 This is the time in seconds allowed to claim a discard, or to
1390 rob a kong. If set to zero, there is no timeout. The default is
1391 15 seconds.
1392 TimeoutGrace (nat) grace period when clients handle timeouts
1395 This period (in seconds) is added to the Timeout above before
1396 the server actually forces a timeout. This is for when clients
1397 handle timeouts locally, and allows for network lags. If this
1398 option is zero, clients are not permitted to handle timeouts
1399 locally. The current server also only allows players to handle
1400 timeouts locally if all of them wish to do so.
1401 ScoreLimit (nat) limit on hand score
1404 This is the limit for the score of a hand. In a no-limit game,
1405 it is the notional value of a "limit" hand. The default is 1000.
1406 NoLimit (bool) no-limit game
1409 If this option is set, the game has no limit on hand scores. The
1410 default is unset.
1411 MahJongScore (score) base score for going out
1414 This is the number of points for obtaining Mah-Jong. The
1415 default is 20.
1416 SevenPairs (bool) seven pairs hand allowed
1419 If this option is set, then Mah-Jong hands of seven pairs (any
1420 seven pairs) are allowed. The default is unset.
1421 SevenPairsVal (score) score for a seven pair hand
1424 This gives the score (in addition to the base Mah-Jong score)
1425 for a seven pairs hand. The default is 20.
1426 Flowers (bool) play using flowers and seasons
1429 If this option is set, the deal includes four flowers and four
1430 seasons in the Chinese Classical style. If unset, only the 136
1431 standard tiles are used. The default is set.
1432 FlowersLoose (bool) flowers replaced by loose tiles
1435 If playing with flowers, this option determines whether flowers
1436 and seasons are replaced from the live wall (unset), or by loose
1437 tiles (set). The default is unset.
1438 FlowersOwnEach (score) score for each own flower or season
1441 This option gives the score for having one's own flower or sea‐
1442 son. If one has both, this score will be given twice. The
1443 default is no score.
1444 FlowersOwnBoth (score) score for own flower and own season
1447 This is the score for having both one's own flower and one's own
1448 season. Note that this is awarded in addition to twice the pre‐
1449 vious score. The default is 1 double.
1450 FlowersBouquet (score) score for all four flowers or all four seasons
1453 This is the score for having all four flowers or all four sea‐
1454 sons. The default is 1 double.
1455 DeadWall (bool) there is a dead wall
1458 This determines whether there is a dead wall, so that play ends
1459 when it is reached (set), or whether all tiles may be drawn
1460 (unset). The default is set.
1461 DeadWall16 (bool) dead wall is 16 tiles, unreplenished
1464 If this option is set, then the dead wall initially has 16
1465 tiles, and does not have any more tiles added to it (this is the
1466 set-up described by Millington). If the option is unset, then
1467 the dead wall initially has 14 tiles, and after two loose tiles
1468 have been taken, two tiles are moved from the live wall to the
1469 dead wall (this is the set-up described by almost everyone
1470 else). The default is unset in versions 1.1 onwards, and set
1471 previously. (To be precise, the protocol level default is set,
1472 but all servers from 1.1 onwards will change this to unset.)
1473 ConcealedFully (score) score for fully concealed hand
1476 This is the score for a winning hand with no open sets. The
1477 default is 1 double.
1478 ConcealedAlmost (score) score for almost concealed hand
1481 This is the score for a hand that is concealed up to the point
1482 of going out. The default is no additional score.
1483 LosersPurity (bool) losing hands score doubles for pure, concealed etc.
1486 If this option is set, losing hands will score various doubles
1487 for one suit, almost concealed, etc. See the rules for details.
1488 This option is an (Anglo-)Americanism alien to Chinese Classical
1489 (see Foster for a spirited but faulty argument in its favour,
1490 and Millington for the rejoinder). The default is unset.
1491 KongHas3Types (bool) claimed kongs count as concealed for doubling
1494 If this option is set, claimed kongs count as concealed for var‐
1495 ious doubling combinations, although they score as exposed for
1496 basic points. See the note above under "Kongs". The default is
1497 unset.
1498 LosersSettle (bool) losers pay each other
1501 If this option is set, the losers pay each other the difference
1502 between their scores. If it unset, they pay only the winner.
1503 The default is set.
1504 EastDoubles (bool) east pays and receives double
1507 If this option is set, payments to and from East Wind are dou‐
1508 bled, as in the Chinese Classical game. The default is set.
1509 DiscDoubles (bool) the discarder pays double
1512 If this option is set, the settlement procedure is changed to a
1513 style common in Singapore. That is, if the winning player wins
1514 off a discard, the discarder pays double the hand value, and the
1515 other players pay the hand value. If the winner wins from the
1516 wall, then all other players pay double the hand value. The
1517 default is unset. Note: EastDoubles and DiscDoubles can be set
1518 together, but nobody plays such a rule.
1519 ShowOnWashout (bool) reveal tiles on washout
1522 If this option is set, the players' hands will be revealed in
1523 the event of a washout.
1524 NumRounds (nat) number of rounds to play
1527 This option says how many rounds to play in the game. For aes‐
1528 thetic reasons, the possible values are 1, 2, or a multiple of
1529 4. In the 2 round case, the East and South rounds will be
1530 played. It defaults to the usual 4 rounds.
1531 Option file format
1534 Both in the option file and in the .xmjrc file, options are recorded in
1535 the format used by the server protocol. This is a line of the form
1536 GameOption 0 name type minprot enabled value desc
1538 The meanings of the elements are:
1540 GameOption 0
1542 identifies this as a game option line (the 0 is an irrelevant
1543 field from the protocol).
1544 name is the name of the option.
1546 type is the type of the option.
1548 minprot
1550 is the minimum protocol version with which the option can be
1551 used (which is not necessarily the version at which it was
1552 introduced).
1553 enabled
1555 will always be 1.
1556 value is the value: a decimal (signed) integer for nat and int; 0 or 1
1558 for bool; the string for string; and for score, if the score is
1559 c centi-limits, d doubles and p points, the value is c*1000000 +
1560 d*10000 + p.
1561 desc is a short description of the option, which is not required but
1563 is usually copied in from the server.
1564J.C.Bradfield Mah-Jong XMJ(1)