xmj, mj-server, mj-player - programs for playing Mah-Jong SYNOPSIS -------- xmj [ --id IDNUMBER] [ --server ADDRESS] [ --name PLAYERNAME] [ --connect ] [ --show-wall | --no-show-wall ] [ --size N ] [ --animate ] [ --tile-pixmap-dir DIRECTORY] [ --dialogs-popup | --dialogs-below | --dialogs-central ] [ --echo-server ] [ --pass-stdin ] mj-server [ --server ADDRESS] [ --timeout SECONDS] [ --pause DECISECONDS] [ --random-seats ] [ --exit-on-disconnect ] [ --debug ] [ --logfile FILE] [ --no-special-scores ] [ --seed N ] [ --nohist ] mj-player [ --id IDNUMBER] [ --server ADDRESS] [UNDOCUMENTED OPTIONS] DESCRIPTION ----------- A set of three programs to play Mah-Jong on Unix systems, against people or programs, over the Internet. mj-server is the program that handles communications and control of the game; the rules and scoring are enforced there. Players, human or computer, connect to a server via the network. mj-player is a computer player. At present, it is fairly simplistic, having only offensive tactics with no knowledge of defensive play. xmj is the X client for human players. QUICK START ----------- If you don't want to read this long document: to start a game against three computer players, start xmj , select "New Game..." from the "Connect" menu, and click "Start Game". (Wait about ten seconds for everything to start up.) 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 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 (which is currently just 1 to 4 in order of connection) to each player. 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. --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. --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 is 19, or 18 if on an 800x600 display. The smallest usable value is 14. This is not yet changeable while the program is running, but since the programs correctly handle dis- and re-connecting in the middle of a game, this is not a major drawback. If the --show-wall option is given, a --size smaller than 19 will have no effect. --animate This option switches on some animation. Not all tile movements are animated: only those that involve moving tiles to or from a hand from outside. I'm not very keen on this; its main purpose is to draw attention to the tile being discarded or whatever. I welcome comments on whether it is liked, and whether it should be extended. --tile-pixmap-dir 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. --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. --echo-server If this option is given, xmj will echo to stdout all the protocol messages received from the server. --pass-stdin If this option is given, xmj will send any text given on stdin to the server. 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. --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 Player Option 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. --exit-on-disconnect If this option is given, the server will quit if any player disconnects, rather than waiting indefinitely for reconnection. --debug This enables various debugging features. In particular, it enables protocol commands that allow one to change the tiles in a hand... --logfile FILE The server will write a complete record of the game to FILE; this will be quite large, and is only useful for automatic comparison of different computer players. --no-special-scores This option suppresses the scoring of points and doubles for flowers and seasons. It is primarily intended for running tests of different players; for human use, a game option will be provided to eliminate the specials altogether. --seed N This option specifies the seed for the random number functions. Used for repeatable tests. --nohist Another option only used in automatic comparison: this saves some CPU time by disabling the book-keeping required to allow players to disconnect and reconnect. mj-player --------- has numerous options affecting its strategy, but these are not yet documented as they are not at all stable. Just as an example, and a way to get some variation in the play, mj-player --pungerweight 2.0 will start a player that tries quite hard to avoid chows, and consequently tends to win less often with higher scores. 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 displays a stylized version of the game: stylized in that there is no jazzy graphics or perspective, and the tiles are not intended to be pictures of real objects, and so on. Otherwise, the layout is as one would 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, the other players' tiles are face-down. 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 are 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. In principle, every face-up tile can display its name when the mouse is moved over it ("tile-tips":-), but this is not yet implemented. 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. 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 Game..." from the "Connect" menu. A panel will appear. The default options are to play a game against the computer, so click "Start Game". After a few seconds, a game will start. (NOTE: this assumes correct installation. If this fails, start a server and players manually, and use the "Connect to 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 is 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. Kong If we have a concealed kong, we can declare it now with this button. Finish Finish declaring specials. When all players have finished declaring specials, 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. &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 Add to Pung add the selected tile to an exposed pung Mah Jong! declare Mah Jong! (no selection needed) Hitting Return within the dialog is equivalent to pressing Discard. TODO: keyboard accelerators for the other actions, working everywhere. 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. (Note: in the default case, it is possibly confusing that the discarded tile can be seen both on the table and in the dialog box. Opinions are sought on this point.) Note: there appear to be subtle bugs in GTK, which mean that sometimes the name of the tile does not appear properly. I have completely failed to track this down; if it happens, just close (that's minimize in Windoze-speak) the window and open it again. 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 we don't claim this tile. If there is no timeout in operation, it is necessary to click this to indicate a "pass", and in any case it is desirable to speed up play. Chow claim for a sequence. If our claim is successful and there is more than one possible sequence to be made, a dialog will appear asking us to specify which one. Pung claim for a triplet. Kong claim for quadruplet. Mah Jong! claim for Mah Jong. If the claim succeeds, a dialog box will appear asking whether we want the tile for "Eyes", "Chow", "Pung", or a "Special Hand" (such as Thirteen Unique Wonders). (The term "Eyes" is used instead of "Pair" so that when keyboard accelerators are implemented, E is different from P! Is it better to stick to "Pair"?) When a player (including us) claims, the word "Chow!" etc. will appear (in big letters on a yellow background, if things are correctly set up; please tell me if this doesn't happen) for a couple of seconds above the player's tiles. When all players have claimed, or timed out, the successful claim is implemented; no additional announcement is made of this. (Should it be?) If a player adds a tile to an exposed pung, and that tile would give us Mah Jong, then a dialog box pops up to ask whether we wish to rob the kong. After somebody goes Mah Jong, we are asked to declare our concealed sets. A dialog appears with buttons for "Eyes", "Chow", "Pung". To declare a set, select a tile, which must be the first tile in the set for a chow, and click the appropriate button. (If we are going Mah Jong, the first undeclared tile is auto-selected.) When finished, click "Done" to reveal the remaining tiles to the other players. If we are the winner, there will be a button for "Special Hand": this is used to declare hands of non-standard shape, such as Thirteen Unique Wonders. At this point, a new top-level window appears to display the scoring information. The scoring is done entirely by the server, not by the players; the server sends a text description of the score calculation, and this is displayed for each player in the Scoring window. The information in the Scoring window remains there until the next hand is scored; the window can be brought up at any time via the "Show" menu. Finally, the "continue with next hand" dialog appears. The hand just completed will remain visible on the table until the next hand starts. An additional top-level window showing the state of the game can be obtained by selecting "Game info" from the "Show" menu. There is also a facility for sending text messages to the other players. Select "Messages" from the "Show" menu, and a window will appear: in the top is a display of all messages sent, and below is a single line in which you can enter your message. It will be send when you hit Return. The message window pops up automatically whenever a message is received. Starting games and re-connecting -------------------------------- The "Connect" menu has the "New Game..." item to start a completely new game, and the "Connect to server..." item to connect to an existing game. The dialogs for both these have the following entries: Checkboxes for Internet/Unix server These specify whether the server is listening on an Internet socket or a Unix socket. If an Internet (TCP) socket, the host name and port number should be entered in the appropriate boxes; if a Unix socket, the file name of the socket should be entered. "Player ID" and "Name" fields The "Player ID" should be left at 0, unless reconnecting to an existing game, in which case it should be the ID assigned by the server on first connecting to that game. The "Name" field can be 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 "Connect to server..." dialog then simply has a "Connect" button to establish the connection. The "New Game..." has the following fields: For each of three further players, A checkbox to say whether to start a computer player. (Some of) these should be unchecked if you wish other humans to join the games. If checked, there is a text entry field in which options can be given to the players; this should only be used if you understand the options! An "allow disconnection" checkbox If this is checked, the server that is started will continue to run even if players disconnect. If it is not checked, the server will quit if any player disconnects. If you are playing one against the computer, this should generally be left unchecked, in order to avoid server processes accidentally being left lying around. If playing against people, it should be checked, to allow players to go away, or to guard against network outages. A "seat players randomly" checkbox If this is left unchecked, players will be initially seated as East, South, West, North in order of connection. (We always connect first.) If it is checked, the seating will be random. A numeric entry field to specify the time limit for claiming discards. If set to 0, there will be 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!) UPDATES ------- The latest release of the Unix Mah-Jong programs should be available at http://www.stevens-bradfield.com/MahJong/ http://www.dcs.ed.ac.uk/home/jcb/MahJong/