mm \- simple Mastermind game
.SH SYNOPSIS
.B mm
-.RB [ \-CHS ]
+.RB [ \-CHSa ]
.RI [ holes " " colours ]
.RI [ code ...]
.SH DESCRIPTION
.B mm
program plays the game of Mastermind.
.SS "About the game"
-In the original game, there are a collection of coloured code pegs, and
-a board. The board has a number of rows of holes. There are two
-players. One player \(en the code setter \(en chooses a `code' \(en a
-sequence of coloured pegs \(en and enters it at his end of the board,
-concealed by a small screen from the other player. The other player
-\(en the code guesser \(en attempts to guess the code.
+In the original game,
+there are a collection of coloured code pegs,
+and a board.
+The board has a number of rows of holes.
+There are two players.
+One player
+\(en the code setter \(en
+chooses a
+.I code
+\en a sequence of coloured pegs \(en and
+enters it at their end of the board,
+concealed by a small screen from the other player.
+The other player
+\(en the code guesser \(en
+attempts to guess the code.
.PP
-In each turn, the guesser makes a guess by filling in a row of holes
-with coloured pegs. The setter then
+In each turn,
+the guesser makes a guess
+by filling in a row of holes with coloured pegs.
+The setter then
.I scores
-the guess. He awards a black scoring peg for each peg in the guess
-which matches the corresponding peg in the code, i.e., the right colour
-in the right place. He awards a white scoring peg for each guess peg
-which matches a code peg in colour but not in position, i.e., the right
-colour in the wrong place. Each guess peg can be scored at most once.
+the guess.
+They award a black scoring peg
+for each peg in the guess which matches
+the corresponding peg in the code,
+i.e., the right colour in the right place.
+They award a white scoring peg
+for each guess peg which matches a code peg in colour
+but not in position,
+i.e., the right colour in the wrong place.
+Each guess peg can be scored at most once.
+Only the number of black or white scoring pegs matters;
+the order in which they're placed on the board is irrelevant.
.PP
-The game ends either if the guesser guesses the code correctly, or if he
-runs out of guessing rows on the board.
-.SS "
\ No newline at end of file
+The game ends either if the guesser guesses the code correctly,
+or if they run out of guessing rows on the board.
+.SS "User interface"
+Since this is a computer game,
+there is no physical board on which to run out of space.
+The game can therefore continue until either
+the guesser successfully guesses the code,
+or they give up.
+.PP
+Since this is a very simple program,
+intended mostly to be a substrate for the computer player,
+it doesn't have coloured pegs.
+Instead, it uses numbers,
+between zero and some upper limit specified on the command line
+(see later).
+The default number of `colours' is 6,
+and so the numbers should be between 0 and 5 inclusive.
+.PP
+When a human is expected to
+.I guess
+a code,
+they should type in a sequence of numbers
+representing the desired colours, separated by whitespace,
+and followed by a newline.
+.PP
+When a human is expected to
+.I rate
+a guess,
+they should type the number of black scoring pegs awarded
+(correct colour, correct place)
+and by the number of white scoring pegs awarded
+(correct colour, but wrong place),
+separated by whitespace and followed by a newline.
+.SS "Command-line options"
+The following command-line options are recognized.
+.TP
+.B "\-C"
+Computer guesser.
+A human chooses the code,
+and the computer attempts to guess.
+This is the default mode.
+If a code is provided on the command line,
+then the computer will automatically rate its own guesses against it
+(but promises not to cheat);
+otherwise the human user is expected to rate the guesses.
+.TP
+.B "\-H"
+Human guesser.
+The computer chooses the code
+unless one was provided on the command line
+(presumably by a
+.I different
+human),
+and the human tries to guess it.
+.TP
+.B "\-S"
+Solver mode.
+This mode can be used to cheat at some other Mastermind-ish game.
+Initially, the user is expected to enter
+their guesses in that other game,
+and the ratings which their guesses received.
+After the user has finished entering their guesses,
+they should type
+.RB ` . '\&
+followed by a newline in place of the guess,
+and the computer will start offering its own sensible guesses.
+The human should relay these to the other game,
+and enter the rating.
+.TP
+.B "\-a"
+Tournament mode.
+This mode simply runs the computer guesser
+against every possible input code
+and (eventually) reports some statistics about how well it did.
+This is used to compare computer-guesser algorithms.
+.SS "Command-line arguments"
+Following the options, if any,
+game parameters may be specified,
+as a pair of numbers
+.I holes
+and
+.IR colours .
+The
+.I holes
+is the number of pegs in a code, and defaults to 4;
+the
+.I colours
+is the number of differently coloured pegs, and defaults to 6.
+.PP
+Following the parameters, a code may be given,
+as a sequence of small integers.
+This is ignored in tournament and solver modes;
+in the computer and human guesser modes,
+it gets the computer to rate guesses against the provided code,
+rather than asking the human to rate (which is surprisingly error-prone)
+or getting the computer to rate against a secret, random code.
+.SH BUGS
+The user interface is terrible.
+.SH SEE ALSO
+.BR guess (6)
+(in Simon Tatham's portable puzzle collection).
+.SH AUTHOR
+Mark Wooding,
+<mdw@distorted.org.uk>
~mdw / mm / commitdiff