xmj.man

一个网络和单机的麻将游戏源码

.\" $Header: /home/jcb/newmj/RCS/xmj.man,v 11.22 2003/04/20 14:46:26 jcb Rel $
.\" Copyright (c) 2000 J. C. Bradfield
.de TQ
.br
.ns
.TP \\$1
..
.de GO
.br
.TP
\fB\\$1\fP (\fB\\$2\fP) \\$3
..
.TH XMJ 1 "Mah-Jong" "J.C.Bradfield"
.SH NAME
xmj, mj\-server, mj\-player \- programs for playing Mah\-Jong
.SH SYNOPSIS
.TP
\fBxmj\fP [\fB\-\-id \fIidnumber\fP]
  [\fB\-\-server \fIaddress\fP]
  [\fB\-\-name \fIplayername\fP]
  [\fB\-\-connect\fP]
  [\fB\-\-show\-wall\fP | \fB\-\-no\-show\-wall\fP]
  [\fB\-\-size N\fP]
  [\fB\-\-animate\fP]
  [\fB\-\-tileset \fIdirectory\fP]
  [\fB\-\-tileset\-path \fIdirectory-path\fP]
  [\fB\-\-dialogs\-popup\fP | \fB\-\-dialogs\-below\fP | \fB\-\-dialogs\-central\fP]
  [\fB\-\-echo\-server\fP]
  [\fB\-\-pass\-stdin\fP]
.TP 
\fBmj\-server\fP [\fB\-\-server \fIaddress\fP]  [\fB\-\-timeout \fIseconds\fP]
  [\fB\-\-pause \fIdeciseconds\fP]
  [\fB\-\-random\-seats\fP]
  [\fB\-\-disconnect\-penalties \fIN1,N2,N3\fP]
  [\fB\-\-end-on-disconnect\fP]
  [\fB\-\-exit-on-disconnect\fP]
  [\fB\-\-save-on-exit\fP]
  [\fB\-\-option-file \fIfile\fP]
  [\fB\-\-debug\fP]
  [\fB\-\-logfile \fIfile\fP]
  [\fB\-\-no-manager\fP]
  [\fB\-\-no-special-scores\fP]
  [\fB\-\-seed N\fP]
  [\fB\-\-wallfile \fIfilefP]
  [\fB\-\-nohist\fP]
.TP 
\fBmj\-player\fP [\fB\-\-id \fIidnumber\fP] [\fB\-\-name \fIplayername\fP]
  [\fB\-\-server \fIaddress\fP]
  [\fIundocumented options\fP]

.SH DESCRIPTION
A set of three programs to play Mah-Jong on Unix systems, against
people or programs, over the Internet.
.TP
.B 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.
.TP
.B mj\-player
is a computer player. At present, it is fairly simplistic, 
having only offensive tactics with no knowledge of defensive play.
.TP
.B xmj
is the X client for human players.

.SH QUICK START
If you don't want to read this long document: to start a game against
three computer players, start \fBxmj\fR, select "New local game..." from the 
"Game" menu, and click "Start Game". (Wait about ten seconds for
everything to start up.)

.SH OPTIONS

.SS All Programs
.TP
.BI --server " address"
specifies the network address to listen on (for \fBmj-server\fR) or to
connect to (for \fBmj-player\fR and \fBxmj\fR).
If \fIaddress\fR contains a colon, it specifies an Internet socket, and
should have the form \fIhost:port\fR . If \fIaddress\fR does not contain a colon, it 
is interpreted as a Unix file name and a Unix socket is used.
The default value for \fIaddress\fR is  localhost:5000 .
\fIaddress\fR can also be set in a dialog box in \fBxmj\fR.

.SS xmj and mj-player
.TP
.BI \-\-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 \fBxmj\fR). The default ID
is 0, which denotes no pre-assigned ID. 
.TP 
.BI \-\-name " name"
Players can give themselves names which will be used by client
programs. This option specifies the name. For \fBxmj\fR, the default
is the value of the environment variable LOGNAME, or failing that the
username of the logged in user. For \fBmj-player\fR, the default is
"Robot(\fIPID\fR)" where \fIPID\fR is the process id.

.SS xmj
.TP
.B \-\-connect
By default, \fBxmj\fR does not automatically connect to a server,
but waits for the user to connect via a menu. If this option is
specified, \fBxmj\fR immediately connects.
.TP
.B \-\-show\-wall
.TQ
.B \-\-no\-show\-wall
Tells \fBxmj\fR (not) to display the wall. By default, the wall is shown
only if running on a big enough screen. This option is also
controllable via the Display Options preference panel.
.TP
.BI \-\-size " number"
This option adjusts the size of the main window. It should be thought
of as the length of a tile rack, measured in tiles. The default, and
the largest value accepted, is 19, or 18 if on an 800x600 display. The
smallest usable value is 14. This 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.
.br
If the \fB\-\-show\-wall\fR option is given, a \fB\-\-size\fR smaller than 19 will
have no effect.
.TP
.B \-\-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. This option is also controllable via the 
Display Options preference panel.
.br
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.
.TP
.BI \-\-tileset " directory"
\fBxmj\fR 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.
.TP
.BI \-\-tileset\-path " directory-path"
This gives a colon-separated (or semicolon-separated under Microsoft
Windows) list of directories in which to look for the directory named
by the \fB\-\-tileset\fP option.
.TP
.B \-\-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.
.TP
.B \-\-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!
.TP
.B \-\-dialogs\-central
The default: dialog boxes appear in the middle of the table.
These options are also controllable via the Display Options
preference panel.
.TP
.B \-\-echo\-server
If this option is given, \fBxmj\fR will echo to  stdout  all the
protocol messages received from the server.
.TP
.B \-\-pass\-stdin
If this option is given, \fBxmj\fR will send any text given on stdin
to the server.

.SS mj-server
.TP
.BI --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.
.TP
.BI --pause " deciseconds"
This will make the server enforce a delay of \fIdeciseconds\fR/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.
.br
The option can also be requested by players, via a PlayerOption
protocol request.
.TP
.B --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.
.TP
.B --disconnect-penalties \fIN1,N2,N3\fP
This specifies the penalties applied by the following option for
players who disconnect before the end of a game. \fIN1\fP is the
penalty for disconnecting in the middle of a hand; \fIN2\fP at the end
of a hand but in the middle of a round; \fIN3\fP at the end of a round
(other than end of game). They all default to 0 if not specified.
.TP
.B --end-on-disconnect
If this option is given, a disconnection by one player will gracefully
terminate the game. Mid-hand, the hand is declared a wash-out; after
Mah-Jong has been declared, then if a losing player disconnects, their
tiles are shown, the hand is scored, and then the game ends; if a
winning player disconnects, the hand is a wash-out. The disconnecting
player may be assigned a penalty, according to the
\fB--disconnect-penalties\fP option, which will be included in the
scores printed out by the server. (The penalties will not be visible
to the other players.)
.TP
.B --exit-on-disconnect
If this option is given, the server will quit if any player
disconnects, rather than waiting indefinitely for reconnection.
.TP
.B --save-on-exit
If this option is given, the server will save the state of the game
if it quits as a result of a player disconnecting. (It will not save
the state if it quits as the result of an internal error.)
.TP
.BI --option-file " file"
This names a file of protocol commands which will be applied to every
game when it starts. Its main purpose is to set non-default game
options, via the GameOption protocol message (note that this is a
CMsg, not a PMsg). However, users will normally set options and
preferences via the \fBxmj\fP control panel, not by this means.
.TP
.BI --load-game " file"
This names a file containing a saved game (as a suitable sequence of
protocol commands). The server will load the game; clients connecting
will be treated as if they had disconnected and rejoined the game.
.TP
.B --no-id-required
In the most common case of resuming a saved game, namely one human
playing against three robots, the robots will not have the same names
or ids as the robots in the original game. This option tells the
server that if it cannot match a reconnecting player by id or name,
it should anyway match it to one of the previously disconnected
players. (In this case, the human normally connects first with the
same name, so is correctly matched.)
.TP
.B --no-manager
Usually, the first player to connect becomes the game manager, and
can change all the game settings. If this option is given, no player
will be allowed to change the game settings.
.TP
.B --debug
This enables various debugging features. In particular, it
enables protocol commands that allow one to change the tiles
in a hand...
.TP
.BI --logfile " file"
The server will write a complete record of the game to \fIfile\fR;
this will be quite large, and is only useful for automatic comparison of
different computer players.
.TP
.B --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.
.TP
.BI --seed " n"
This option specifies the seed for the random number functions.
Used for repeatable tests.
.TP
.BI --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.)
.TP
.B --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.

.SS mj-player
has numerous options affecting its strategy, but these are
not yet documented as they are not at all stable.

.SH 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 \fB--animate\fR 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:
.br
during the initial declaration of special tiles, the rightmost
special is selected;
.br
after we draw a tile from the wall, the drawn tile is selected;
.br
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:
.TP
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