xmj.man

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

flowers and seasons.
.TP
Kong
If we have a concealed kong, we can declare it now with
this button.
.TP
Finish
Finish declaring specials and kongs.
.PP
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:
.TP
Discard
discard the selected tile. This button also serves
to declare a flower or season.
.TP
&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).
.TP
Kong
declare a concealed kong of the selected tile
.TP
Add to Pung
add the selected tile to an exposed pung
.TP
Mah Jong!
declare Mah Jong! (no selection needed)
.PP
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:
.TP
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.
.TP
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.
.TP
Pung
claim for a triplet.
.TP
Kong
claim for quadruplet.
.TP
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"?)
.PP
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 \fBfirst\fR 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.

.PP
\fBKeyboard Accelerators\fP
.br
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.)
.br
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.

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

.SS 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:
.TP
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.
.TP
"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 "Name" field is remembered from game
to game.
.PP
The "Join server..." dialog then simply has a "Connect" button
to establish the connection. The "New local game..." has the following
fields:
.TP
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 to set the players' names, and a
text entry field in which options can be given to the players; the
latter should only be used if you understand the options! 
.TP
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.
.TP
As "save game state on exit" checkbox
If this is checked, the server will save the game state (see below on
on saving and resuming games) when a player disconnects and causes it
to quit.
.TP
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.
.TP
A numeric entry field
to specify the time limit for claiming discards.
If set to 0, there will be no time limit.
.TP
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!)

.SS Saving and resuming games
At any time during the play of a game, you can choose the "Save" entry
from the "Game" menu. This causes the server to save the current state
of the game in a file. The file will be named \fBgame-\fP\fIdate\fP\fB.mjs\fP by
default; if a name has previously been specified, or if the game was
resumed from a file, that name will be used. To specify a name, use
the "Save as..." entry in the "Game" menu. Note that for security,
directories cannot be specified (except by resuming a game), so the
file will be created in the working directory of the server.

To resume a saved game, use the "Resume game..." entry from the "Game"
menu. This is just like the "New local game..." panel, but it has a box to
specify the file containing the saved game. At present, you must type
the name of the file into this box. TODO find a file selector widget
for this.

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

.SS Display Options
This panel controls options related to the local display.
At the bottom are three buttons: "Save & Apply" applies changes and
saves them in the preferences file for future sessions; "Apply (no
save)" applies any changes, but does not save them; "Cancel" ignores changes.
Note that many display options can also be controlled by command-line
arguments; if an option is specified both in the preferences file and
on the command line, the command line takes priority.
.TP
Position of action dialogs.
This determines where the dialogs for user actions in the game are
popped up; see the description of the \fB--dialogs-central\fP etc.
options above. This option is stored in the preferences file as
.br
Display DialogPosition \fIposn\fP
.br
where \fIposn\fP is one of "central", "below" or "popup".
.TP
Animation
determines whether tile movements are animated (see the \fB--animate\fP
option above). This option is stored in the preferences file as
.br
Display Animate \fIbool\fP
.br
where \fIbool\fP is "0" or "1".
.TP
Display status and messages in main window
puts the game status and message (chat) windows in the main window,
above the table, instead of having separate popup windows. This option
is stored in the preferences file as 
.br
Display InfoInMain \fIbool\fP
.br
where \fIbool\fP is "0" or "1".
.TP
Don't popup scoring/message windows
will prevent the automatic popup of the scoring window at the end of
a hand, the message window on the arrival of a message, and the game
status window at the end of the game. This option is stored in the preferences file as
.br
Display NoPopups \fIbool\fP
.br
where \fIbool\fP is "0" or "1".
.TP
Tiletips always shown
means that the name of a tile is displayed whenever the mouse enters
it, and the name of the selected tile is always shown. (Otherwise,
right-click to display the name.) This option is stored in the
preferences file as
.br
Display Tiletips \fIbool\fP
.br
where \fIbool\fP is "0" or "1".
.TP
Display size
This drop-down list specifies the size of the display. The size should
be thought of as the length of a tile rack. This is only relevant if
the wall is not being displayed. Values range from 14 to 19; if
"(auto)" (the default) is specified, the client tries to choose a size
as big as will fit in the display. This option can also be specified
by the command line \fB--size\fP argument. This option is stored in the
preferences file as 
.br
Display Size \fIn\fP
.TP
Show the wall
"always" is equivalent to the \fB--show-wall\fP option; "never" is
equivalent to the \fB--no-show-wall\fP option; and "when room" is the
default. This option is stored in the preferences file as
.br
Display ShowWall \fIwhen\fP
.br
where \fIwhen\fP is one of "always", "when-room" or "never".
.TP
Iconify all windows with main
If this option is set (the default), then when the main xmj window is
iconified, (almost) all other open windows such as dialogs will also
be iconified; when the main window is uniconified, the other windows
will also be uniconified. If it is not set, all windows are
independent of one another. This option is stored in the preferences file as 
.br
Display IconifyDialogs \fIbool\fP
.br
This option is not currently supported under Microsoft Windows.
.TP
Tileset
this is the tile pixmap directory, also given by the \fB--tileset\fP
option. This option is stored in the preferences file as
.br
Display Tileset \fIdirname\fP
.TP
Tileset Path
this is the search path for tileset directories, also given by the
\fB--tileset-path\fP option. This option is stored in the preferences
file as 
.br
Display TilesetPath \fIsearch-path\fP
.TP
Main font selection...
This button brings up a font selection dialog to choose the font
used in buttons, menus, etc. in the client. This option is stored in
the preferences file as 
.br
Display MainFont \fIlfd\fP
.br
where \fIlfd\fP is an X logical font descriptor as used by GTK.
.TP
Text font selection...
This button brings up a font selection dialog to choose the font
used in text display (such as scoring info and chat) in the
client. This option is stored in the preferences file as 
.br
Display TextFont \fIlfd\fP
.br
where \fIlfd\fP is an X logical font descriptor as used by GTK.
.TP
Table colour selection...
Unaccountably, not everybody likes my choice of dark green for the
table background. This button brings up a colour selection box to