Since the split into random and descriptive IDs, the section on game seeds has

been mostly covered by the main documentation or otherwise moot.

git-svn-id: svn://svn.tartarus.org/sgt/puzzles@5845 cda61777-01e9-0310-a592-d414129be87e

diff --git a/HACKING.but b/HACKING.but
index e1abf75..6bf9785 100644 (file)
--- a/HACKING.but
+++ b/HACKING.but
@@ -70,34 +70,26 @@ to have \c{game_drawstate} contain a description of the last tile
 you drew at every position, so that you can compare it to the new
 tile and avoid redrawing tiles that haven't changed.
 
 you drew at every position, so that you can compare it to the new
 tile and avoid redrawing tiles that haven't changed.
 

-\H{newpuz-seed} Designing a game seed
-
-The game seed is the part of the game ID (what you type in when you
-select \q{Game -> Specific}) which comes \e{after} the colon. It
-should uniquely specify the starting state of a game, given a set of
-game parameters (which are encoded separately, before the colon).
-
-Try to imagine all the things a user might want to use the game seed
-for, and build as much capability into it as possible.
-
-For a start, if it's feasible for the game seed to \e{directly}
-encode the starting position, it should simply do so. This is a
-better approach than encoding a random number seed which is used to
-randomly generate the game in \cw{new_game()}, because it allows the
-user to make up their own game seeds. This property is particularly
-useful if the puzzle is an implementation of a well-known game, in
-which case existing instances of the puzzle might be available which
-a user might want to transcribe into game seeds in order to play
-them conveniently. I recommend this technique wherever you can
-sensibly use it: \cw{new_game_seed()} should do all the real
-thinking about creating a game seed, and \cw{new_game()} should
-restrict itself to simply parsing the text description it returns.
-
-However, sometimes this is genuinely not feasible; Net, for example,
-uses the random-number seed approach, because I decided the full
-state of even a moderately large Net game is just too big to be
-sensibly cut-and-pasted by users. However, even the Net seeds have a
-useful property. The order of grid generation in Net is:
+\H{newpuz-params} Notes on parameters
+
+You need to define a textual format for the game parameters (the part
+before the \q{:} or \q{#} in descriptive and random IDs respectively).
+
+The per-game parameter encoding function \cw{encode_params()} is
+passed an argument \c{full}. This serves two purposes:
+
+\b You can suppress inclusion of parameters that only affect game
+generation, and thus would have no effect in a descriptive ID, in the
+ID displayed by \q{Game -> Specific} if \c{full} is \cw{FALSE}.
+
+\b You can ensure that a particular parameter entered as part of a
+game ID does not persist when a new puzzle is generated, for instance
+if you think that a player would not want it to persist beyond a
+single game. An example is the \q{expansion factor} in Rectangles.
+
+When generating a new puzzle instance, give some thought to the order
+in which parameters are processed. For example, the order of grid
+generation in Net is:

 
 \b First the game sets up a valid completed Net grid.
 
 
 \b First the game sets up a valid completed Net grid.
 


@@ -121,6 +113,23 @@ the version with more barriers will contain every barrier from the
 one with fewer), so that selecting 10 barriers and then 20 barriers
 will not give a user 30 pieces of information, only 20.
 
 one with fewer), so that selecting 10 barriers and then 20 barriers
 will not give a user 30 pieces of information, only 20.
 

+\H{newpuz-descid} Notes on descriptive IDs
+
+The descriptive game ID is the part that comes after the colon in the
+ID accessed through \q{Game -> Specific}. It does not need to be
+especially concise, but it should be designed to remain compatible
+with new versions of the puzzle.
+
+Try to imagine all the things a user might want to use the descriptive
+ID for, and build as much capability into it as possible. At a minimum,
+you need to be able to generate one of these given a random number
+source; however, if auto-generation capability is limited, give some
+thought to the possibility of a user making up their own descriptive
+IDs. This property is particularly useful if the puzzle is an
+implementation of a well-known game, in which case existing instances
+of the puzzle might be available which a user might want to transcribe
+into game seeds in order to play them conveniently.
+

 \H{newpuz-redraw} Designing a drawing routine
 
 Front end implementations are required to remember all data drawn by
 \H{newpuz-redraw} Designing a drawing routine
 
 Front end implementations are required to remember all data drawn by