.TH mm 6 "Mark Wooding"
.SH NAME
mm \- simple Mastermind game
.SH SYNOPSIS
.B mm
.RB [ \-CHSa ]
.RI [ holes " " colours ]
.RI [ code ...]
.SH DESCRIPTION
The
.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
.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
.I scores
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 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>