Add HACKING to main doc build.
[sgt/puzzles] / puzzles.but
index a8dcf3a..4fc471c 100644 (file)
@@ -94,6 +94,22 @@ menu}\q{Edit} menus instead.)
 
 \dd Resets the current game to its initial state. (This can be undone.)
 
+\dt \ii\e{Load}
+
+\dd Loads a saved game from a file on disk.
+
+\dt \ii\e{Save}
+
+\dd Saves the current state of your game to a file on disk.
+
+\lcont{
+
+The Load and Save operations should preserve your entire game
+history (so you can save, reload, and still Undo and Redo things you
+had done before saving).
+
+}
+
 \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
@@ -930,26 +946,32 @@ other implementations, you can switch off this option.
 \cfg{winhelp-topic}{games.samegame}
 
 You have a grid of coloured squares, which you have to clear by 
-highlighting contiguous regions of more that one coloured square;
+highlighting contiguous regions of more than one coloured square;
 the larger the region you highlight, the more points you get (and
 the faster you clear the arena).
 
 If you clear the grid you win. If you end up with nothing but 
-single squares (i.e. there are no more clickable regions left) you
+single squares (i.e., there are no more clickable regions left) you
 lose.
 
 Removing a region causes the rest of the grid to shuffle up:
 blocks that are suspended will fall down (first), and then empty
 columns are filled from the right. 
 
-The game generator does not try and guarantee to generate soluble grids;
+The game generator does not try to guarantee soluble grids;
 it will, however, ensure that there are at least 2 squares of each 
 colour on the grid at the start (and will forbid custom grids for which
 that would be impossible).
 
 Same Game was contributed to this collection by James Harvey.
 
-\H{samegame-controls} \I{controls, for Same Game}Same Game controls
+\H{samegame-controls} \i{Same Game controls}
+
+\IM{Same Game controls} controls, for Same Game
+\IM{Same Game controls} keys, for Same Game
+\IM{Same Game controls} shortcuts (keyboard), for Same Game
+
+This game can be played with either the keyboard or the mouse.
 
 If you left-click an unselected region, it becomes selected (possibly
 clearing the current selection). 
@@ -959,8 +981,15 @@ rest of the grid shuffled immediately).
 
 If you right-click the selected region, it will be unselected. 
 
+The cursor keys move a cursor around the grid. Pressing the Space or
+Enter keys while the cursor is in an unselected region selects it;
+pressing Space or Enter again removes it as above.
+
 \H{samegame-parameters} \I{parameters, for Same Game}Same Game 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 squares.
@@ -968,8 +997,199 @@ If you right-click the selected region, it will be unselected.
 \dt \e{No. of colours}
 
 \dd Number of different colours used to fill the grid; the more colours,
-the fewer large regions of colour and thus the more difficult to clear
-successfully. 
+the fewer large regions of colour and thus the more difficult it is to
+successfully clear the grid.
+
+\dt \e{Scoring system}
+
+\dd Controls the precise mechanism used for scoring. With the default
+system, \q{(n-2)^2}, only regions of three squares or more will score
+any points at all. With the alternative \q{(n-1)^2} system, regions of
+two squares score a point each, and larger regions score relatively
+more points.
+
+
+\C{flip} \i{Flip}
+
+\cfg{winhelp-topic}{games.flip}
+
+You have a grid of squares, some light and some dark. Your aim is to
+light all the squares up at the same time. You can choose any square
+and flip its state from light to dark or dark to light, but when you
+do so, other squares around it change state as well.
+
+Each square contains a small diagram showing which other squares
+change when you flip it.
+
+\H{flip-controls} \i{Flip controls}
+
+\IM{Flip controls} controls, for Flip
+\IM{Flip controls} keys, for Flip
+\IM{Flip controls} shortcuts (keyboard), for Flip
+
+This game can be played with either the keyboard or the mouse.
+
+Left-click in a square to flip it and its associated squares, or
+use the cursor keys to choose a square and the space bar or Enter
+key to flip.
+
+If you use the \q{Solve} function on this game, it will mark some of
+the squares in red. If you click once in every square with a red
+mark, the game should be solved. (If you click in a square
+\e{without} a red mark, a red mark will appear in it to indicate
+that you will need to reverse that operation to reach the solution.)
+
+\H{flip-parameters} \I{parameters, for flip}Flip 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 squares.
+
+\dt \e{Shape type}
+
+\dd This control determines the shape of the region which is flipped
+by clicking in any given square. The default setting, \q{Crosses},
+causes every square to flip itself and its four immediate neighbours
+(or three or two if it's at an edge or corner). The other setting,
+\q{Random}, causes a random shape to be chosen for every square, so
+the game is different every time.
+
+
+\C{guess} \i{Guess}
+
+\cfg{winhelp-topic}{games.guess}
+
+You have a set of coloured pegs, and have to reproduce a
+predetermined sequence of them (chosen by the computer) within a
+certain number of guesses. 
+
+Each guess gets marked with the number of correctly-coloured pegs
+in the correct places (in black), and also the number of
+correctly-coloured pegs in the wrong places (in white). 
+
+This game is also known (and marketed, by Hasbro, mainly) as
+a board game \q{Mastermind}, with 6 colours, 4 pegs per row, and 10 guesses.
+However, this version allows custom settings of number of colours
+(up to 10), number of pegs per row, and number of guesses. 
+
+Guess was contributed to this collection by James Harvey.
+
+\H{guess-controls} \i{Guess controls}
+
+\IM{Guess controls} controls, for Guess
+\IM{Guess controls} keys, for Guess
+\IM{Guess controls} shortcuts (keyboard), for Guess
+
+This game can be played with either the keyboard or the mouse.
+
+With the mouse, drag a coloured peg from the tray on the left-hand
+side to its required position in the current guess; pegs may also be
+dragged from current and past guesses to copy them elsewhere. To
+remove a peg, drag it off its current position to somewhere invalid.
+
+Right-clicking in the current guess adds a \q{hold} marker; pegs
+that have hold markers will be automatically added to the next guess
+after marking.
+
+Alternatively, with the keyboard, the up and down cursor keys can be
+used to select a peg colour, the left and right keys to select a
+peg position, and the space bar or Enter key to place a peg of the
+selected colour in the chosen position. \q{D} or Backspace removes a
+peg, and \q{H} adds a hold marker.
+
+When the guess is complete, the smaller feedback pegs will be highlighted;
+clicking on these (or moving the peg cursor to them with the arrow keys
+and pressing the space bar or Enter key) will mark the current guess,
+copy any held pegs to the next guess, and move the \q{current guess}
+marker.
+
+If you correctly position all the pegs the solution will be displayed
+below; if you run out of guesses (or select \q{Solve...}) the solution
+will also be revealed.
+
+\H{guess-parameters} \I{parameters, for Guess}Guess parameters
+
+These parameters are available from the \q{Custom...} option on the
+\q{Type} menu. The default game matches the parameters for the 
+board game \q{Mastermind}. 
+
+\dt \e{Colours}
+
+\dd Number of colours the solution is chosen from; from 2 to 10
+(more is harder).
+
+\dt \e{Pegs per guess}
+
+\dd Number of pegs per guess (more is harder).
+
+\dt \e{Guesses}
+
+\dd Number of guesses you have to find the solution in (fewer is harder).
+
+\dt \e{Allow blanks}
+
+\dd Allows blank pegs to be given as part of a guess (makes it easier, because
+you know that those will never be counted as part of the solution). This
+is turned off by default. 
+
+Note that this doesn't allow blank pegs in the solution; if you really wanted
+that, use one extra colour.
+
+\dt \e{Allow duplicates}
+
+\dd Allows the solution (and the guesses) to contain colours more than once;
+this increases the search space (making things harder), and is turned on by
+default.
+
+
+\C{pegs} \i{Pegs}
+
+\cfg{winhelp-topic}{games.pegs}
+
+A number of pegs are placed in holes on a board. You can remove a
+peg by jumping an adjacent peg over it (horizontally or vertically)
+to a vacant hole on the other side. Your aim is to remove all but one
+of the pegs initially present.
+
+This game, best known as \q{Peg Solitaire}, is possibly one of the
+oldest puzzle games still commonly known.
+
+\H{pegs-controls} \i{Pegs controls}
+
+\IM{Pegs controls} controls, for Pegs
+
+To move a peg, drag it with the mouse from its current position to
+its final position. If the final position is exactly two holes away
+from the initial position, is currently unoccupied by a peg, and
+there is a peg in the intervening square, the move will be permitted
+and the intervening peg will be removed.
+
+Vacant spaces which you can move a peg into are marked with holes. A
+space with no peg and no hole is not available for moving at all: it
+is an obstacle which you must work around.
+
+
+\H{pegs-parameters} \I{parameters, for Pegs}Pegs 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 holes.
+
+\dt \e{Board type}
+
+\dd Controls whether you are given a board of a standard shape or a
+randomly generated shape. The two standard shapes currently
+supported are \q{Cross} and \q{Octagon} (also commonly known as the
+English and European traditional board layouts respectively).
+Selecting \q{Random} will give you a different board shape every
+time (but always one that is known to have a solution).
+
 
 \A{licence} \I{MIT licence}\ii{Licence}