Move MODULE files out of individual project directories into a

[sgt/puzzles] / puzzles.but

\title Simon Tatham's Portable Puzzle Collection

\cfg{winhelp-filename}{puzzles.hlp}
\cfg{winhelp-contents-titlepage}{Contents}

\cfg{text-filename}{puzzles.txt}

\cfg{xhtml-contents-filename}{index.html}
\cfg{xhtml-leaf-level}{1}
\cfg{xhtml-contents-depth-0}{1}
\cfg{xhtml-contents-depth-1}{2}
\cfg{xhtml-leaf-contains-contents}{true}

\cfg{info-filename}{puzzles.info}

\cfg{ps-filename}{puzzles.ps}
\cfg{pdf-filename}{puzzles.pdf}

This is a collection of small one-player puzzle games.

\copyright This manual is copyright 2004 Simon Tatham. All rights
reserved. You may distribute this documentation under the MIT licence.
See \k{licence} for the licence text in full.

\versionid $Id: puzzles.but,v 1.3 2004/08/16 13:17:40 simon Exp $


\C{intro} Introduction

I wrote this collection because I thought there should be more small
desktop toys available: little games you can pop up in a window and
play for two or three minutes while you take a break from whatever
else you were doing. And I was also annoyed that every time I found a
good game on (say) \i{Unix}, it wasn't available the next time I was
sitting at a \i{Windows} machine, or vice versa; so I arranged that
everything in my personal puzzle collection will happily run on both.
When I find (or perhaps invent) further puzzle games that I like,
they'll be added to this collection and will immediately be available
on both platforms. And if anyone feels like writing any other front
ends - Mac OS, PocketPC, or whatever it might be - then all the games
in this framework will immediately become available on another
platform as well.

The actual games in this collection were mostly not my invention; I
saw them elsewhere, and rewrote them in a form that was more
convenient for me. I do not claim credit, in general, for inventing
the rules of any of these puzzles; all I claim is authorship of the
code (or at least those parts of the code that weren't contributed
by other people!).

This collection is distributed under the \i{MIT licence} (see
\k{licence}). This means that you can do pretty much anything you like
with the game binaries or the code, except pretending you wrote them
yourself, or suing me if anything goes wrong. 

The most recent versions, and \i{source code}, can be found at
\I{website}\W{http://www.chiark.greenend.org.uk/~sgtatham/puzzles/}\cw{http://www.chiark.greenend.org.uk/~sgtatham/puzzles/}.

Please report \I{feedback}\i{bugs} to
\W{mailto:anakin@pobox.com}\cw{anakin@pobox.com}.
You might find it helpful to read this article before reporting a bug:

\W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}

\ii{Patches} are welcome. Especially if they provide a new front end
(to make all these games run on another platform), or a new game.


\C{common} \ii{Common features}

This chapter describes features that are common to all the games.

\H{common-actions} \I{controls}Common actions

These actions are all available from the \I{Game menu}\q{Game} menu
and via \I{keys}keyboard shortcuts, in addition to any game-specific
actions.

\dt \ii\e{New game} (\q{N}, Ctrl+\q{N})

\dd Starts a new game, with a random initial state.

\dt \ii\e{Restart game} (\q{R})

\dd Resets the current game to its initial state. Undo is lost.

\dt \ii\e{Undo} (\q{U}, Ctrl+\q{Z}, Ctrl+\q{_})

\dd Undoes a single move. (You can undo moves back to the start of the
game.)

\dt \ii\e{Redo} (Ctrl+\q{R})

\dd Redoes a previous undone move.

\dt \I{exit}\ii\e{Quit} (\q{Q}, Ctrl+\q{Q})

\dd Closes the application entirely.

\H{common-id} Recreating games with the \ii{game ID}

The \q{\i{Specific...}} option from the \I{Game menu}\q{Game} menu
lets you see a short string (the \q{game ID}) that captures the
initial state of the current game.

The precise \I{ID format}format of the ID is specific to each game.
It consists of two parts delimited by a colon (e.g., \c{c4x4:4F01,0});
the first part encodes \i\e{parameters} (such as grid size), while the
second part encodes a \i\e{seed}, which determines the \i{initial
state} of the game within those parameters.

You can specify a new ID (or just a seed) here. Pressing \q{OK} starts
a new game with the specified ID (whether you changed it or not).
Pressing \q{Cancel} returns to the current game.

You can also use the game ID (or just the encoded parameters) as a
\i{command line} argument; see \k{common-cmdline} for more detail.

Game IDs are portable across platforms; you can use a game ID
generated by the Windows version of a game on the Unix version, etc.

\H{common-type} The \q{Type} menu

The \I{Type menu}\q{Type} menu, if present, may contain a list of
\i{preset} game settings. Selecting one of these will start a new
random game with the parameters specified.

The \q{Type} menu may also contain a \q{\i{Custom...}} option which
allows you to fine-tune game \i{parameters}. The parameters available
are specific to each game and are described in the following sections.

\H{common-cmdline} Specifying game parameters on the \i{command line}

The games in this collection deliberately do not ever save
information on to the computer they run on: they have no high score
tables and no saved preferences. (This is because I expect at least
some people to play them at work, and those people will probably
appreciate leaving as little evidence as possible!)

However, if you do want to arrange for one of these games to default
to a particular set of parameters, you can specify them on the
command line.

The easiest way to do this is to set up the parameters you want
using the \q{Type} menu (see \k{common-type}), and then to select
\q{Specific} from the \q{Game} menu (see \k{common-id}). The text in
the \q{Game ID} box will be composed of two parts, separated by a
colon. The first of these parts represents the game parameters (the
size of the playing area, for example, and anything else you set
using the \q{Type} menu).

If you run the game with just that parameter text on the command
line, it will start up with the settings you specified.

For example: if you run Cube (see \k{cube}), select \q{Octahedron}
from the \q{Type} menu, and then go to the game ID selection, you
will see a string of the form \cq{o2x2:911A81,10}. Take only the
part before the colon (\cq{o2x2}), and start Cube with that text on
the command line: \cq{cube o2x2}.

If you copy the \e{entire} game ID on to the command line, the game
will start up in the specific game that was described. This is
occasionally a more convenient way to start a particular game ID
than by pasting it into the game ID selection box.

\C{net} \i{Net}

\cfg{winhelp-topic}{games.net}

(\e{Note:} the \i{Windows} version of this game is called
\i\cw{NETGAME.EXE} to avoid clashing with Windows's own \cw{NET.EXE}.)

I originally saw this in the form of a Flash game called \i{FreeNet}
\k{FreeNet}, written by Pavils Jurjans. The computer prepares a
network by connecting up the centres of squares in a grid, and then
shuffles the network by rotating every tile randomly. Your job is to
rotate it all back into place. The successful solution will be an
entirely connected network, with no closed loops. \#{Is it also true
that a correct solution will not contain any cycles?} As a visual aid,
all tiles which are connected to the one in the middle are
highlighted. 

\B{FreeNet} \W{http://www.jurjans.lv/stuff/net/FreeNet.htm}\cw{http://www.jurjans.lv/stuff/net/FreeNet.htm}

\H{net-controls} \i{Net controls}

\IM{Net controls} controls, for Net
\IM{Net controls} keys, for Net
\IM{Net controls} shortcuts (keyboard), for Net

This game can be played with either the keyboard or the mouse. The
controls are:

\dt \e{Select tile}: mouse pointer, arrow keys

\dt \e{Rotate tile anticlockwise}: left mouse button, \q{A} key

\dt \e{Rotate tile clockwise}: right mouse button, \q{D} key

\dt \e{Lock (or unlock) tile}: middle mouse button, shift-click, \q{S} key

\dd You can lock a tile once you're sure of its orientation. You can
also unlock it again, but while it's locked you can't accidentally
turn it.

(All the actions described in \k{common-actions} are also available.)

\H{net-params} \I{parameters, for Net}Net parameters

These parameters are available from the \q{Custom...} option on the
\q{Type} menu.

\dt \e{Width}, \e{Height}

\dd Size of grid in tiles.

\dt \e{Walls wrap around}

\dd If checked, flow can pass from the left edge to the right edge,
and from top to bottom, and vice versa.

\dt \e{Barrier probability}

\dd A number between 0.0 and 1.0 controlling whether an immovable
barrier is placed between two tiles to prevent flow between them (a
higher number gives more barriers). Since barriers are immovable, they
act as constraints on the solution (i.e., hints).

\lcont{

The grid generation in Net has been carefully arranged so that the
barriers are independent of the rest of the grid. This means that if
you change the \e{Barrier probability} parameter, and then re-enter
the same game ID you were playing before (see \k{common-id}), you
should see exactly the same starting grid, with the only change
being the number of barriers. So if you're stuck on a particular
grid and need a hint, you could start up another instance of Net,
set up the same parameters but a higher barrier probability, and
enter the game seed from the original Net window.

}

\C{cube} \i{Cube}

\cfg{winhelp-topic}{games.cube}

This is another one I originally saw as a web game. This one was a
Java game \k{cube-java-game}, by Paul Scott. You have a grid of 16
squares, six of which are blue; on one square rests a cube. Your move
is to use the arrow keys to roll the cube through 90 degrees so that
it moves to an adjacent square. If you roll the cube on to a blue
square, the blue square is picked up on one face of the cube; if you
roll a blue face of the cube on to a non-blue square, the blueness is
put down again. (In general, whenever you roll the cube, the two faces
that come into contact swap colours.) Your job is to get all six blue
squares on to the six faces of the cube at the same time. Count your
moves and try to do it in as few as possible. 

Unlike the original Java game, my version has an additional feature:
once you've mastered the game with a cube rolling on a square grid,
you can change to a triangular grid and roll any of a tetrahedron, an
octahedron or an icosahedron. 

\B{cube-java-game} \W{http://www3.sympatico.ca/paulscott/cube/cube.htm}\cw{http://www3.sympatico.ca/paulscott/cube/cube.htm}

\H{cube-controls} \i{Cube controls}

\IM{Cube controls} controls, for Cube
\IM{Cube controls} keys, for Cube
\IM{Cube controls} shortcuts (keyboard), for Cube

This game is played with the keyboard. The arrow keys are used to roll the
cube (or other solid).

On the triangular grids, the mapping of arrow keys to directions is
more approximate. Vertical movement is disallowed where it doesn't
make sense. The four keys surrounding the arrow keys on the numeric
keypad (\q{7}, \q{9}, \q{1}, \q{3}) can be used for diagonal movement.

(All the actions described in \k{common-actions} are also available.)

\H{cube-params} \I{parameters, for Cube}Cube parameters

These parameters are available from the \q{Custom...} option on the
\q{Type} menu.

\dt \e{Type of solid}

\dd Selects the solid to roll (and hence the shape of the grid):
tetrahedron, cube, octahedron, or icosahedron.

\dt \e{Width / top}, \e{Height / bottom}

\dd On a square grid, horizontal and vertical dimensions. On a
triangular grid, the number of triangles on the top and bottom rows
respectively.


\C{fifteen} \i{Fifteen}

\cfg{winhelp-topic}{games.fifteen}

The old ones are the best: this is the good old \q{\i{15-puzzle}} with
sliding tiles. You have a 4x4 square grid; 15 squares contain numbered
tiles, and the sixteenth is empty. Your move is to choose a tile next
to the empty space, and slide it into the space. The aim is to end up
with the tiles in numerical order, with the space in the bottom right
(so that the top row reads 1,2,3,4 and the bottom row reads
13,14,15,\e{space}).

\H{fifteen-controls} \i{Fifteen controls}

\IM{Fifteen controls} controls, for Fifteen
\IM{Fifteen controls} keys, for Fifteen
\IM{Fifteen controls} shortcuts (keyboard), for Fifteen

This game can be controlled with the mouse or the keyboard.

A left-click with the mouse in the row or column containing the empty
space will move as many tiles as necessary to move the space to the
mouse pointer.

The arrow keys will move a tile adjacent to the space in the direction
indicated (moving the space in the \e{opposite} direction).

(All the actions described in \k{common-actions} are also available.)

\H{fifteen-params} \I{parameters, for Fifteen}Fifteen parameters

The only options available from the \q{Custom...} option on the \q{Type}
menu are \e{Width} and \e{Height}, which are self-explanatory. (Once
you've changed these, it's not a \q{15-puzzle} any more, of course!)


\C{sixteen} \i{Sixteen}

\cfg{winhelp-topic}{games.sixteen}

Another sliding tile puzzle, visually similar to Fifteen (see
\k{fifteen}) but with a different type of move. This time, there is no
hole: all 16 squares on the grid contain numbered squares. Your move
is to shift an entire row left or right, or shift an entire column up
or down; every time you do that, the tile you shift off the grid
re-appears at the other end of the same row, in the space you just
vacated. To win, arrange the tiles into numerical order (1,2,3,4 on
the top row, 13,14,15,16 on the bottom). When you've done that, try
playing on different sizes of grid. 

I \e{might} have invented this game myself, though only by accident if
so (and I'm sure other people have independently invented it). I
thought I was imitating a screensaver I'd seen, but I have a feeling
that the screensaver might actually have been a Fifteen-type puzzle
rather than this slightly different kind. So this might be the one
thing in my puzzle collection which represents creativity on my part
rather than just engineering.

\H{sixteen-controls} \I{controls, for Sixteen}Sixteen controls

This game is played with the mouse. Left-clicking on an arrow will
move the appropriate row or column in the direction indicated.
Right-clicking will move it in the opposite direction.

(All the actions described in \k{common-actions} are also available.)

\H{sixteen-params} \I{parameters, for Sixteen}Sixteen parameters

The only parameters available from the \q{Custom...} option on the
\q{Type} menu are \e{Width} and \e{Height}, which are
self-explanatory.


\C{rectangles} \i{Rectangles}

\cfg{winhelp-topic}{games.rectangles}

You have a grid of squares, with numbers written in some (but not all)
of the squares. Your task is to subdivide the grid into rectangles of
various sizes, such that (a) every rectangle contains exactly one
numbered square, and (b) the area of each rectangle is equal to the
number written in its numbered square.

Credit for this game goes to the Japanese puzzle magazine \i{Nikoli}
\k{nikoli}; I've also seen a Palm implementation at \i{Puzzle Palace}
\k{puzzle-palace}. Unlike Puzzle Palace's implementation, my version
automatically generates random grids of any size you like. The quality
of puzzle design is therefore not quite as good as hand-crafted
puzzles would be (in particular, a unique solution cannot be
guaranteed), but on the plus side you get an inexhaustible supply of
puzzles tailored to your own specification.

\B{nikoli} \W{http://www.nikoli.co.jp/puzzles/7/index_text-e.htm}\cw{http://www.nikoli.co.jp/puzzles/7/index_text-e.htm}

\B{puzzle-palace} \W{http://www.puzzle.gr.jp/puzzle/sikaku/palm/index.html.en}\cw{http://www.puzzle.gr.jp/puzzle/sikaku/palm/index.html.en}

\H{rectangles-controls} \I{controls, for Rectangles}Rectangles controls

This game is played with the mouse.

Left-click any edge to toggle it on or off, or click and drag to draw
an entire rectangle (or line) on the grid in one go (removing any
existing edges within that rectangle).

When a rectangle of the correct size is completed, it will be shaded.

(All the actions described in \k{common-actions} are also available.)

\H{rectangles-params} \I{parameters, for Rectangles}Rectangles parameters

The \q{Custom...} option on the \q{Type} menu offers you \e{Width}
and \e{Height} parameters, which are self-explanatory.

\q{Expansion factor} is a mechanism for changing the type of grids
generated by the program. Some people prefer a grid containing a few
large rectangles to one containing many small ones. So you can ask
Rectangles to essentially generate a \e{smaller} grid than the size
you specified, and then to expand it by adding rows and columns.

The default expansion factor of zero means that Rectangles will
simply generate a grid of the size you ask for, and do nothing
further. If you set an expansion factor of (say) 0.5, it means that
each dimension of the grid will be expanded to half again as big
after generation. In other words, the initial grid will be 2/3 the
size in each dimension, and will be expanded to its full size
without adding any more rectangles.

Setting an expansion factor of around 0.5 tends to make the game
more difficult, and also (in my experience) rewards a less deductive
and more intuitive playing style. If you set it \e{too} high,
though, the game simply cannot generate more than a few rectangles
to cover the entire grid, and the game becomes trivial.

\H{rectangles-cmdline} \I{command line, for Rectangles}Additional
command-line configuration

The expansion factor parameter, described in \k{rectangles-params},
is not mentioned by default in the game ID (see \k{common-id}). So
if you set your expansion factor to (say) 0.75, and then you
generate an 11x11 grid, then the game ID will simply say
\c{11x11:}\e{numbers}. This means that if you send the game ID to
another player and they paste it into their copy of Rectangles,
their game will not be automatically configured to use the same
expansion factor in any subsequent grids it generates. (I don't
think the average person examining a single grid sent to them by
another player would want their configuration modified to that
extent.)

If you are specifying a game ID or game parameters on the command
line (see \k{common-cmdline}) and you do want to configure the
expansion factor, you can do it by suffixing the letter \cq{e} to
the parameters, followed by the expansion factor as a decimal
number. For example:

\b \cq{rect 11x11e0.75} starts Rectangles with a grid size of
11\u00d7{x}11 and an expansion factor of 0.75.

\b \cq{rect 11x11e0.75:g11c6e5e4a2_4e9c3b3d3b5g2b6c4k4g30a8n3j1g6a2}
starts Rectangles with a grid size of 11\u00d7{x}11, an expansion
factor of 0.75, \e{and} a specific game selected.

\C{netslide} \i{Netslide}

\cfg{winhelp-topic}{games.netslide}

This game was submitted by Richard Boulton. It combines the grid
generation of Net (see \k{net}) with the movement of Sixteen (see
\k{sixteen}): you have a Net grid, but instead of rotating tiles back
into place you have to slide them into place by moving a whole row at
a time. 


As in Sixteen, \I{controls, for Netslide}control is with the mouse.
See \k{sixteen-controls}.

\I{parameters, for Netslide}Game parameters are the same as for Net
(see \k{net-params}).


\A{licence} \I{MIT licence}\ii{Licence}

This software is \i{copyright} 2004 Simon Tatham.

Portions copyright Richard Boulton.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
(the "Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software,
and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

\IM{specific...} Specific..., menu option
\IM{custom...} Custom..., menu option

\IM{game ID} game ID
\IM{game ID} ID, game
\IM{ID format} ID format
\IM{ID format} format, ID
\IM{ID format} game ID, format

\IM{keys} keys
\IM{keys} shortcuts (keyboard)

\IM{initial state} initial state
\IM{initial state} state, initial

\IM{MIT licence} MIT licence
\IM{MIT licence} licence, MIT