From: jacob Date: Thu, 26 May 2005 16:57:19 +0000 (+0000) Subject: Since the split into random and descriptive IDs, the section on game seeds has X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/commitdiff_plain/713e4ddec31717b4f136720d3e387dbd286c0bf6 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 --- 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. -\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. @@ -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. +\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