use.txt

支持网络和单机的麻将游戏

  --seed  N
    This option specifies the seed for the random number functions.
    Used for repeatable tests.

  --wallfile  FILE
    This names a file containing space separated tile codes giving the
    wall; used for repeatable tests. (This is a testing option; it is
    not robust.)

  --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.


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.

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.

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 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.
    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.

  &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)

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. (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.) 
If the wall is not being shown, the dialog will note the number
of tiles left in the live wall.
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 iconify
(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 "Finished" 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. (Note: the Seven Pairs hand, if in use, should be declared
by means of the "Eyes" button, not the "Special Hand" button.)

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.


Keyboard Accelerators 
There are keyboard accelerators for all the actions in the course of
play. For selecting tiles, the Left and Right arrow keys can be used
to move the selection left or right along the row of tiles. In all
dialogs, Space or Return will activate the shadowed button, which is
usually the commonest choice. Each button can also be activated by
typing the underlined letter. (Note: at present, the Left and Right
arrow accelerators do not work under Windows.)
The menus are also accessible via accelerators. 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 which if pressed will activate it.


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
sent when you hit Return. The message window pops up automatically 
whenever a message is received, unless prevented by a display
preference. If the "Display status and messages in main window"
display option is set, then this window will instead appear in the
main window, above the table. In that case, there is a checkbox 
"Keep cursor here" next to the message entry line. Checking this box
will ensure that the keyboard focus stays in the message entry field,
even when you click on buttons in the game. (Consequently, you will be
unable to use keyboard accelerators while this option is checked.)

Starting games and re-connecting
--------------------------------
The "Game" menu has the "New local game..." item to start a new game
on your local computer, and the "Join 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 ("Join
    Game..." only) and port number should be entered in the appropriate
    boxes; if a Unix socket, the file name of the socket should be entered.
    These fields are remembered from game to game.

  "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