Work around a couple of minor display issues with max bridges set to 4:
[sgt/puzzles] / devel.but
CommitLineData
69491f1e 1\cfg{text-indent}{0}
2\cfg{text-width}{72}
3\cfg{text-title-align}{left}
4\cfg{text-chapter-align}{left}
5\cfg{text-chapter-numeric}{true}
6\cfg{text-chapter-suffix}{. }
7\cfg{text-chapter-underline}{-}
8\cfg{text-section-align}{0}{left}
9\cfg{text-section-numeric}{0}{true}
10\cfg{text-section-suffix}{0}{. }
11\cfg{text-section-underline}{0}{-}
12\cfg{text-section-align}{1}{left}
13\cfg{text-section-numeric}{1}{true}
14\cfg{text-section-suffix}{1}{. }
15\cfg{text-section-underline}{1}{-}
16\cfg{text-versionid}{0}
17
18\cfg{html-contents-filename}{index.html}
19\cfg{html-template-filename}{%k.html}
20\cfg{html-index-filename}{docindex.html}
21\cfg{html-leaf-level}{1}
22\cfg{html-contents-depth-0}{1}
23\cfg{html-contents-depth-1}{3}
24\cfg{html-leaf-contains-contents}{true}
25
26\define{dash} \u2013{-}
27
28\title Developer documentation for Simon Tatham's puzzle collection
29
30This is a guide to the internal structure of Simon Tatham's Portable
31Puzzle Collection (henceforth referred to simply as \q{Puzzles}),
32for use by anyone attempting to implement a new puzzle or port to a
33new platform.
34
dafd6cf6 35This guide is believed correct as of r6190. Hopefully it will be
69491f1e 36updated along with the code in future, but if not, I've at least
37left this version number in here so you can figure out what's
38changed by tracking commit comments from there onwards.
39
40\C{intro} Introduction
41
42The Puzzles code base is divided into four parts: a set of
43interchangeable front ends, a set of interchangeable back ends, a
44universal \q{middle end} which acts as a buffer between the two, and
45a bunch of miscellaneous utility functions. In the following
46sections I give some general discussion of each of these parts.
47
48\H{intro-frontend} Front end
49
50The front end is the non-portable part of the code: it's the bit
51that you replace completely when you port to a different platform.
52So it's responsible for all system calls, all GUI interaction, and
53anything else platform-specific.
54
55The current front ends in the main code base are for Windows, GTK
56and MacOS X; I also know of a third-party front end for PalmOS.
57
58The front end contains \cw{main()} or the local platform's
59equivalent. Top-level control over the application's execution flow
60belongs to the front end (it isn't, for example, a set of functions
61called by a universal \cw{main()} somewhere else).
62
63The front end has complete freedom to design the GUI for any given
64port of Puzzles. There is no centralised mechanism for maintaining
65the menu layout, for example. This has a cost in consistency (when I
66\e{do} want the same menu layout on more than one platform, I have
67to edit two pieces of code in parallel every time I make a change),
68but the advantage is that local GUI conventions can be conformed to
69and local constraints adapted to. For example, MacOS X has strict
70human interface guidelines which specify a different menu layout
71from the one I've used on Windows and GTK; there's nothing stopping
72the OS X front end from providing a menu layout consistent with
73those guidelines.
74
75Although the front end is mostly caller rather than the callee in
76its interactions with other parts of the code, it is required to
77implement a small API for other modules to call, mostly of drawing
78functions for games to use when drawing their graphics. The drawing
79API is documented in \k{drawing}; the other miscellaneous front end
80API functions are documented in \k{frontend-api}.
81
82\H{intro-backend} Back end
83
84A \q{back end}, in this collection, is synonymous with a \q{puzzle}.
85Each back end implements a different game.
86
87At the top level, a back end is simply a data structure, containing
88a few constants (flag words, preferred pixel size) and a large
89number of function pointers. Back ends are almost invariably callee
90rather than caller, which means there's a limitation on what a back
91end can do on its own initiative.
92
93The persistent state in a back end is divided into a number of data
94structures, which are used for different purposes and therefore
95likely to be switched around, changed without notice, and otherwise
96updated by the rest of the code. It is important when designing a
97back end to put the right pieces of data into the right structures,
98or standard midend-provided features (such as Undo) may fail to
99work.
100
101The functions and variables provided in the back end data structure
102are documented in \k{backend}.
103
104\H{intro-midend} Middle end
105
106Puzzles has a single and universal \q{middle end}. This code is
107common to all platforms and all games; it sits in between the front
108end and the back end and provides standard functionality everywhere.
109
110People adding new back ends or new front ends should generally not
111need to edit the middle end. On rare occasions there might be a
112change that can be made to the middle end to permit a new game to do
113something not currently anticipated by the middle end's present
114design; however, this is terribly easy to get wrong and should
115probably not be undertaken without consulting the primary maintainer
116(me). Patch submissions containing unannounced mid-end changes will
117be treated on their merits like any other patch; this is just a
118friendly warning that mid-end changes will need quite a lot of
119merits to make them acceptable.
120
121Functionality provided by the mid-end includes:
122
123\b Maintaining a list of game state structures and moving back and
124forth along that list to provide Undo and Redo.
125
126\b Handling timers (for move animations, flashes on completion, and
127in some cases actually timing the game).
128
129\b Handling the container format of game IDs: receiving them,
130picking them apart into parameters, description and/or random seed,
131and so on. The game back end need only handle the individual parts
132of a game ID (encoded parameters and encoded game description);
133everything else is handled centrally by the mid-end.
134
135\b Handling standard keystrokes and menu commands, such as \q{New
136Game}, \q{Restart Game} and \q{Quit}.
137
138\b Pre-processing mouse events so that the game back ends can rely
139on them arriving in a sensible order (no missing button-release
140events, no sudden changes of which button is currently pressed,
141etc).
142
143\b Handling the dialog boxes which ask the user for a game ID.
144
145\b Handling serialisation of entire games (for loading and saving a
146half-finished game to a disk file, or for handling application
147shutdown and restart on platforms such as PalmOS where state is
148expected to be saved).
149
150Thus, there's a lot of work done once by the mid-end so that
151individual back ends don't have to worry about it. All the back end
152has to do is cooperate in ensuring the mid-end can do its work
153properly.
154
155The API of functions provided by the mid-end to be called by the
156front end is documented in \k{midend}.
157
158\H{intro-utils} Miscellaneous utilities
159
160In addition to these three major structural components, the Puzzles
161code also contains a variety of utility modules usable by all of the
162above components. There is a set of functions to provide
163platform-independent random number generation; functions to make
164memory allocation easier; functions which implement a balanced tree
165structure to be used as necessary in complex algorithms; and a few
166other miscellaneous functions. All of these are documented in
167\k{utils}.
168
169\H{intro-structure} Structure of this guide
170
171There are a number of function call interfaces within Puzzles, and
172this guide will discuss each one in a chapter of its own. After
173that, there will be a section about how to design new games, with
174some general design thoughts and tips.
175
176\C{backend} Interface to the back end
177
178This chapter gives a detailed discussion of the interface that each
179back end must implement.
180
181At the top level, each back end source file exports a single global
182symbol, which is a \c{const struct game} containing a large number
183of function pointers and a small amount of constant data. This
184structure is called by different names depending on what kind of
185platform the puzzle set is being compiled on:
186
187\b On platforms such as Windows and GTK, which build a separate
188binary for each puzzle, the game structure in every back end has the
189same name, \cq{thegame}; the front end refers directly to this name,
190so that compiling the same front end module against a different back
191end module builds a different puzzle.
192
193\b On platforms such as MacOS X and PalmOS, which build all the
194puzzles into a single monolithic binary, the game structure in each
195back end must have a different name, and there's a helper module
196\c{list.c} which contains a complete list of those game structures.
197
198On the latter type of platform, source files may assume that the
199preprocessor symbol \c{COMBINED} has been defined. Thus, the usual
200code to declare the game structure looks something like this:
201
202\c #ifdef COMBINED
203\c #define thegame net /* or whatever this game is called */
204\e iii iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
205\c #endif
206\c
207\c const struct game thegame = {
208\c /* lots of structure initialisation in here */
209\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
210\c };
211
212Game back ends must also internally define a number of data
213structures, for storing their various persistent state. This chapter
214will first discuss the nature and use of those structures, and then
215go on to give details of every element of the game structure.
216
217\H{backend-structs} Data structures
218
219Each game is required to define four separate data structures. This
220section discusses each one and suggests what sorts of things need to
221be put in it.
222
223\S{backend-game-params} \c{game_params}
224
225The \c{game_params} structure contains anything which affects the
226automatic generation of new puzzles. So if puzzle generation is
227parametrised in any way, those parameters need to be stored in
228\c{game_params}.
229
230Most puzzles currently in this collection are played on a grid of
231squares, meaning that the most obvious parameter is the grid size.
232Many puzzles have additional parameters; for example, Mines allows
233you to control the number of mines in the grid independently of its
234size, Net can be wrapping or non-wrapping, Solo has difficulty
235levels and symmetry settings, and so on.
236
237A simple rule for deciding whether a data item needs to go in
238\c{game_params} is: would the user expect to be able to control this
239data item from either the preset-game-types menu or the \q{Custom}
240game type configuration? If so, it's part of \c{game_params}.
241
242\c{game_params} structures are permitted to contain pointers to
243subsidiary data if they need to. The back end is required to provide
244functions to create and destroy \c{game_params}, and those functions
245can allocate and free additional memory if necessary. (It has not
246yet been necessary to do this in any puzzle so far, but the
247capability is there just in case.)
248
249\c{game_params} is also the only structure which the game's
250\cw{compute_size()} function may refer to; this means that any
251aspect of the game which affects the size of the window it needs to
252be drawn in must be stored in \c{game_params}. In particular, this
253imposes the fundamental limitation that random game generation may
254not have a random effect on the window size: game generation
255algorithms are constrained to work by starting from the grid size
256rather than generating it as an emergent phenomenon. (Although this
257is a restriction in theory, it has not yet seemed to be a problem.)
258
259\S{backend-game-state} \c{game_state}
260
261While the user is actually playing a puzzle, the \c{game_state}
262structure stores all the data corresponding to the current state of
263play.
264
265The mid-end keeps \c{game_state}s in a list, and adds to the list
266every time the player makes a move; the Undo and Redo functions step
267back and forth through that list.
268
269Therefore, a good means of deciding whether a data item needs to go
270in \c{game_state} is: would a player expect that data item to be
271restored on undo? If so, put it in \c{game_state}, and this will
272automatically happen without you having to lift a finger. If not
273\dash for example, the deaths counter in Mines is precisely
274something that does \e{not} want to be reset to its previous state
275on an undo \dash then you might have found a data item that needs to
276go in \c{game_ui} instead.
277
278During play, \c{game_state}s are often passed around without an
279accompanying \c{game_params} structure. Therefore, any information
280in \c{game_params} which is important during play (such as the grid
281size) must be duplicated within the \c{game_state}. One simple
282method of doing this is to have the \c{game_state} structure
283\e{contain} a \c{game_params} structure as one of its members,
284although this isn't obligatory if you prefer to do it another way.
285
286\S{backend-game-drawstate} \c{game_drawstate}
287
288\c{game_drawstate} carries persistent state relating to the current
289graphical contents of the puzzle window. The same \c{game_drawstate}
290is passed to every call to the game redraw function, so that it can
291remember what it has already drawn and what needs redrawing.
292
293A typical use for a \c{game_drawstate} is to have an array mirroring
294the array of grid squares in the \c{game_state}; then every time the
295redraw function was passed a \c{game_state}, it would loop over all
296the squares, and physically redraw any whose description in the
297\c{game_state} (i.e. what the square needs to look like when the
298redraw is completed) did not match its description in the
299\c{game_drawstate} (i.e. what the square currently looks like).
300
301\c{game_drawstate} is occasionally completely torn down and
302reconstructed by the mid-end, if the user somehow forces a full
303redraw. Therefore, no data should be stored in \c{game_drawstate}
304which is \e{not} related to the state of the puzzle window, because
305it might be unexpectedly destroyed.
306
307The back end provides functions to create and destroy
308\c{game_drawstate}, which means it can contain pointers to
309subsidiary allocated data if it needs to. A common thing to want to
310allocate in a \c{game_drawstate} is a \c{blitter}; see
311\k{drawing-blitter} for more on this subject.
312
313\S{backend-game-ui} \c{game_ui}
314
315\c{game_ui} contains whatever doesn't fit into the above three
316structures!
317
318A new \c{game_ui} is created when the user begins playing a new
319instance of a puzzle (i.e. during \q{New Game} or after entering a
320game ID etc). It persists until the user finishes playing that game
321and begins another one (or closes the window); in particular,
322\q{Restart Game} does \e{not} destroy the \c{game_ui}.
323
324\c{game_ui} is useful for implementing user-interface state which is
325not part of \c{game_state}. Common examples are keyboard control
326(you wouldn't want to have to separately Undo through every cursor
327motion) and mouse dragging. See \k{writing-keyboard-cursor} and
328\k{writing-howto-dragging}, respectively, for more details.
329
330Another use for \c{game_ui} is to store highly persistent data such
331as the Mines death counter. This is conceptually rather different:
332where the Net cursor position was \e{not important enough} to
333preserve for the player to restore by Undo, the Mines death counter
334is \e{too important} to permit the player to revert by Undo!
335
336A final use for \c{game_ui} is to pass information to the redraw
337function about recent changes to the game state. This is used in
338Mines, for example, to indicate whether a requested \q{flash} should
339be a white flash for victory or a red flash for defeat; see
340\k{writing-flash-types}.
341
342\H{backend-simple} Simple data in the back end
343
344In this section I begin to discuss each individual element in the
345back end structure. To begin with, here are some simple
346self-contained data elements.
347
348\S{backend-name} \c{name}
349
350\c const char *name;
351
352This is a simple ASCII string giving the name of the puzzle. This
353name will be used in window titles, in game selection menus on
354monolithic platforms, and anywhere else that the front end needs to
355know the name of a game.
356
357\S{backend-winhelp} \c{winhelp_topic}
358
359\c const char *winhelp_topic;
360
361This member is used on Windows only, to provide online help.
362Although the Windows front end provides a separate binary for each
363puzzle, it has a single monolithic help file; so when a user selects
364\q{Help} from the menu, the program needs to open the help file and
365jump to the chapter describing that particular puzzle.
366
367Therefore, each chapter in \c{puzzles.but} is labelled with a
368\e{help topic} name, similar to this:
369
370\c \cfg{winhelp-topic}{games.net}
371
372And then the corresponding game back end encodes the topic string
373(here \cq{games.net}) in the \c{winhelp_topic} element of the game
374structure.
375
376\H{backend-params} Handling game parameter sets
377
378In this section I present the various functions which handle the
379\c{game_params} structure.
380
381\S{backend-default-params} \cw{default_params()}
382
383\c game_params *(*default_params)(void);
384
385This function allocates a new \c{game_params} structure, fills it
386with the default values, and returns a pointer to it.
387
388\S{backend-fetch-preset} \cw{fetch_preset()}
389
390\c int (*fetch_preset)(int i, char **name, game_params **params);
391
392This function is used to populate the \q{Type} menu, which provides
393a list of conveniently accessible preset parameters for most games.
394
395The function is called with \c{i} equal to the index of the preset
396required (numbering from zero). It returns \cw{FALSE} if that preset
397does not exist (if \c{i} is less than zero or greater than the
398largest preset index). Otherwise, it sets \c{*params} to point at a
399newly allocated \c{game_params} structure containing the preset
400information, sets \c{*name} to point at a newly allocated C string
401containing the preset title (to go on the \q{Type} menu), and
402returns \cw{TRUE}.
403
404If the game does not wish to support any presets at all, this
405function is permitted to return \cw{FALSE} always.
406
407\S{backend-encode-params} \cw{encode_params()}
408
409\c char *(*encode_params)(game_params *params, int full);
410
411The job of this function is to take a \c{game_params}, and encode it
412in a string form for use in game IDs. The return value must be a
413newly allocated C string, and \e{must} not contain a colon or a hash
414(since those characters are used to mark the end of the parameter
415section in a game ID).
416
417Ideally, it should also not contain any other potentially
418controversial punctuation; bear in mind when designing a string
419parameter format that it will probably be used on both Windows and
420Unix command lines under a variety of exciting shell quoting and
421metacharacter rules. Sticking entirely to alphanumerics is the
422safest thing; if you really need punctuation, you can probably get
423away with commas, periods or underscores without causing anybody any
424major inconvenience. If you venture far beyond that, you're likely
425to irritate \e{somebody}.
426
427(At the time of writing this, all existing games have purely
428alphanumeric string parameter formats. Usually these involve a
429letter denoting a parameter, followed optionally by a number giving
430the value of that parameter, with a few mandatory parts at the
431beginning such as numeric width and height separated by \cq{x}.)
432
433If the \c{full} parameter is \cw{TRUE}, this function should encode
434absolutely everything in the \c{game_params}, such that a subsequent
435call to \cw{decode_params()} (\k{backend-decode-params}) will yield
436an identical structure. If \c{full} is \cw{FALSE}, however, you
437should leave out anything which is not necessary to describe a
438\e{specific puzzle instance}, i.e. anything which only takes effect
439when a new puzzle is \e{generated}. For example, the Solo
440\c{game_params} includes a difficulty rating used when constructing
441new puzzles; but a Solo game ID need not explicitly include the
442difficulty, since to describe a puzzle once generated it's
443sufficient to give the grid dimensions and the location and contents
444of the clue squares. (Indeed, one might very easily type in a puzzle
445out of a newspaper without \e{knowing} what its difficulty level is
446in Solo's terminology.) Therefore. Solo's \cw{encode_params()} only
447encodes the difficulty level if \c{full} is set.
448
449\S{backend-decode-params} \cw{decode_params()}
450
451\c void (*decode_params)(game_params *params, char const *string);
452
453This function is the inverse of \cw{encode_params()}
454(\k{backend-encode-params}). It parses the supplied string and fills
455in the supplied \c{game_params} structure. Note that the structure
456will \e{already} have been allocated: this function is not expected
457to create a \e{new} \c{game_params}, but to modify an existing one.
458
459This function can receive a string which only encodes a subset of
460the parameters. The most obvious way in which this can happen is if
461the string was constructed by \cw{encode_params()} with its \c{full}
462parameter set to \cw{FALSE}; however, it could also happen if the
463user typed in a parameter set manually and missed something out. Be
464prepared to deal with a wide range of possibilities.
465
466When dealing with a parameter which is not specified in the input
467string, what to do requires a judgment call on the part of the
468programmer. Sometimes it makes sense to adjust other parameters to
469bring them into line with the new ones. In Mines, for example, you
470would probably not want to keep the same mine count if the user
471dropped the grid size and didn't specify one, since you might easily
472end up with more mines than would actually fit in the grid! On the
473other hand, sometimes it makes sense to leave the parameter alone: a
474Solo player might reasonably expect to be able to configure size and
475difficulty independently of one another.
476
477This function currently has no direct means of returning an error if
478the string cannot be parsed at all. However, the returned
479\c{game_params} is almost always subsequently passed to
480\cw{validate_params()} (\k{backend-validate-params}), so if you
481really want to signal parse errors, you could always have a \c{char
482*} in your parameters structure which stored an error message, and
483have \cw{validate_params()} return it if it is non-\cw{NULL}.
484
485\S{backend-free-params} \cw{free_params()}
486
487\c void (*free_params)(game_params *params);
488
489This function frees a \c{game_params} structure, and any subsidiary
490allocations contained within it.
491
492\S{backend-dup-params} \cw{dup_params()}
493
494\c game_params *(*dup_params)(game_params *params);
495
496This function allocates a new \c{game_params} structure and
497initialises it with an exact copy of the information in the one
498provided as input. It returns a pointer to the new duplicate.
499
500\S{backend-can-configure} \c{can_configure}
501
502\c int can_configure;
503
504This boolean data element is set to \cw{TRUE} if the back end
505supports custom parameter configuration via a dialog box. If it is
506\cw{TRUE}, then the functions \cw{configure()} and
507\cw{custom_params()} are expected to work. See \k{backend-configure}
508and \k{backend-custom-params} for more details.
509
510\S{backend-configure} \cw{configure()}
511
512\c config_item *(*configure)(game_params *params);
513
514This function is called when the user requests a dialog box for
515custom parameter configuration. It returns a newly allocated array
516of \cw{config_item} structures, describing the GUI elements required
e9f8a17f 517in the dialog box. The array should have one more element than the
518number of controls, since it is terminated with a \cw{C_END} marker
519(see below). Each array element describes the control together with
520its initial value; the front end will modify the value fields and
521return the updated array to \cw{custom_params()} (see
522\k{backend-custom-params}).
69491f1e 523
524The \cw{config_item} structure contains the following elements:
525
526\c char *name;
527\c int type;
528\c char *sval;
529\c int ival;
530
531\c{name} is an ASCII string giving the textual label for a GUI
532control. It is \e{not} expected to be dynamically allocated.
533
534\c{type} contains one of a small number of \c{enum} values defining
535what type of control is being described. The meaning of the \c{sval}
536and \c{ival} fields depends on the value in \c{type}. The valid
537values are:
538
539\dt \c{C_STRING}
540
541\dd Describes a text input box. (This is also used for numeric
542input. The back end does not bother informing the front end that the
543box is numeric rather than textual; some front ends do have the
544capacity to take this into account, but I decided it wasn't worth
545the extra complexity in the interface.) For this type, \c{ival} is
546unused, and \c{sval} contains a dynamically allocated string
547representing the contents of the input box.
548
549\dt \c{C_BOOLEAN}
550
551\dd Describes a simple checkbox. For this type, \c{sval} is unused,
552and \c{ival} is \cw{TRUE} or \cw{FALSE}.
553
554\dt \c{C_CHOICES}
555
556\dd Describes a drop-down list presenting one of a small number of
557fixed choices. For this type, \c{sval} contains a list of strings
558describing the choices; the very first character of \c{sval} is used
559as a delimiter when processing the rest (so that the strings
560\cq{:zero:one:two}, \cq{!zero!one!two} and \cq{xzeroxonextwo} all
561define a three-element list containing \cq{zero}, \cq{one} and
562\cq{two}). \c{ival} contains the index of the currently selected
563element, numbering from zero (so that in the above example, 0 would
564mean \cq{zero} and 2 would mean \cq{two}).
565
566\lcont{
567
568Note that for this control type, \c{sval} is \e{not} dynamically
569allocated, whereas it was for \c{C_STRING}.
570
571}
572
573\dt \c{C_END}
574
575\dd Marks the end of the array of \c{config_item}s. All other fields
576are unused.
577
578The array returned from this function is expected to have filled in
579the initial values of all the controls according to the input
580\c{game_params} structure.
581
582If the game's \c{can_configure} flag is set to \cw{FALSE}, this
583function is never called and need not do anything at all.
584
585\S{backend-custom-params} \cw{custom_params()}
586
587\c game_params *(*custom_params)(config_item *cfg);
588
589This function is the counterpart to \cw{configure()}
590(\k{backend-configure}). It receives as input an array of
591\c{config_item}s which was originally created by \cw{configure()},
592but in which the control values have since been changed in
593accordance with user input. Its function is to read the new values
594out of the controls and return a newly allocated \c{game_params}
595structure representing the user's chosen parameter set.
596
597(The front end will have modified the controls' \e{values}, but
598there will still always be the same set of controls, in the same
599order, as provided by \cw{configure()}. It is not necessary to check
600the \c{name} and \c{type} fields, although you could use
601\cw{assert()} if you were feeling energetic.)
602
603This function is not expected to (and indeed \e{must not}) free the
604input \c{config_item} array. (If the parameters fail to validate,
605the dialog box will stay open.)
606
607If the game's \c{can_configure} flag is set to \cw{FALSE}, this
608function is never called and need not do anything at all.
609
610\S{backend-validate-params} \cw{validate_params()}
611
612\c char *(*validate_params)(game_params *params, int full);
613
614This function takes a \c{game_params} structure as input, and checks
615that the parameters described in it fall within sensible limits. (At
616the very least, grid dimensions should almost certainly be strictly
617positive, for example.)
618
619Return value is \cw{NULL} if no problems were found, or
620alternatively a (non-dynamically-allocated) ASCII string describing
621the error in human-readable form.
622
623If the \c{full} parameter is set, full validation should be
624performed: any set of parameters which would not permit generation
625of a sensible puzzle should be faulted. If \c{full} is \e{not} set,
626the implication is that these parameters are not going to be used
627for \e{generating} a puzzle; so parameters which can't even sensibly
628\e{describe} a valid puzzle should still be faulted, but parameters
629which only affect puzzle generation should not be.
630
631(The \c{full} option makes a difference when parameter combinations
632are non-orthogonal. For example, Net has a boolean option
633controlling whether it enforces a unique solution; it turns out that
634it's impossible to generate a uniquely soluble puzzle with wrapping
635walls and width 2, so \cw{validate_params()} will complain if you
636ask for one. However, if the user had just been playing a unique
637wrapping puzzle of a more sensible width, and then pastes in a game
638ID acquired from somebody else which happens to describe a
639\e{non}-unique wrapping width-2 puzzle, then \cw{validate_params()}
640will be passed a \c{game_params} containing the width and wrapping
641settings from the new game ID and the uniqueness setting from the
642old one. This would be faulted, if it weren't for the fact that
643\c{full} is not set during this call, so Net ignores the
644inconsistency. The resulting \c{game_params} is never subsequently
645used to generate a puzzle; this is a promise made by the mid-end
646when it asks for a non-full validation.)
647
648\H{backend-descs} Handling game descriptions
649
650In this section I present the functions that deal with a textual
651description of a puzzle, i.e. the part that comes after the colon in
652a descriptive-format game ID.
653
654\S{backend-new-desc} \cw{new_desc()}
655
656\c char *(*new_desc)(game_params *params, random_state *rs,
657\c char **aux, int interactive);
658
659This function is where all the really hard work gets done. This is
660the function whose job is to randomly generate a new puzzle,
661ensuring solubility and uniqueness as appropriate.
662
663As input it is given a \c{game_params} structure and a random state
664(see \k{utils-random} for the random number API). It must invent a
665puzzle instance, encode it in string form, and return a dynamically
666allocated C string containing that encoding.
667
668Additionally, it may return a second dynamically allocated string in
669\c{*aux}. (If it doesn't want to, then it can leave that parameter
670completely alone; it isn't required to set it to \cw{NULL}, although
671doing so is harmless.) That string, if present, will be passed to
672\cw{solve()} (\k{backend-solve}) later on; so if the puzzle is
673generated in such a way that a solution is known, then information
674about that solution can be saved in \c{*aux} for \cw{solve()} to
675use.
676
677The \c{interactive} parameter should be ignored by almost all
678puzzles. Its purpose is to distinguish between generating a puzzle
679within a GUI context for immediate play, and generating a puzzle in
680a command-line context for saving to be played later. The only
681puzzle that currently uses this distinction (and, I fervently hope,
682the only one which will \e{ever} need to use it) is Mines, which
683chooses a random first-click location when generating puzzles
684non-interactively, but which waits for the user to place the first
685click when interactive. If you think you have come up with another
686puzzle which needs to make use of this parameter, please think for
687at least ten minutes about whether there is \e{any} alternative!
688
689Note that game description strings are not required to contain an
690encoding of parameters such as grid size; a game description is
691never separated from the \c{game_params} it was generated with, so
692any information contained in that structure need not be encoded
693again in the game description.
694
695\S{backend-validate-desc} \cw{validate_desc()}
696
697\c char *(*validate_desc)(game_params *params, char *desc);
698
699This function is given a game description, and its job is to
700validate that it describes a puzzle which makes sense.
701
702To some extent it's up to the user exactly how far they take the
703phrase \q{makes sense}; there are no particularly strict rules about
704how hard the user is permitted to shoot themself in the foot when
705typing in a bogus game description by hand. (For example, Rectangles
706will not verify that the sum of all the numbers in the grid equals
707the grid's area. So a user could enter a puzzle which was provably
708not soluble, and the program wouldn't complain; there just wouldn't
709happen to be any sequence of moves which solved it.)
710
711The one non-negotiable criterion is that any game description which
712makes it through \cw{validate_desc()} \e{must not} subsequently
713cause a crash or an assertion failure when fed to \cw{new_game()}
714and thence to the rest of the back end.
715
716The return value is \cw{NULL} on success, or a
717non-dynamically-allocated C string containing an error message.
718
719\S{backend-new-game} \cw{new_game()}
720
dafd6cf6 721\c game_state *(*new_game)(midend *me, game_params *params,
69491f1e 722\c char *desc);
723
724This function takes a game description as input, together with its
725accompanying \c{game_params}, and constructs a \c{game_state}
726describing the initial state of the puzzle. It returns a newly
727allocated \c{game_state} structure.
728
729Almost all puzzles should ignore the \c{me} parameter. It is
730required by Mines, which needs it for later passing to
731\cw{midend_supersede_game_desc()} (see \k{backend-supersede}) once
732the user has placed the first click. I fervently hope that no other
733puzzle will be awkward enough to require it, so everybody else
734should ignore it. As with the \c{interactive} parameter in
735\cw{new_desc()} (\k{backend-new-desc}), if you think you have a
736reason to need this parameter, please try very hard to think of an
737alternative approach!
738
739\H{backend-states} Handling game states
740
741This section describes the functions which create and destroy
742\c{game_state} structures.
743
744(Well, except \cw{new_game()}, which is in \k{backend-new-game}
745instead of under here; but it deals with game descriptions \e{and}
746game states and it had to go in one section or the other.)
747
748\S{backend-dup-game} \cw{dup_game()}
749
750\c game_state *(*dup_game)(game_state *state);
751
752This function allocates a new \c{game_state} structure and
753initialises it with an exact copy of the information in the one
754provided as input. It returns a pointer to the new duplicate.
755
756\S{backend-free-game} \cw{free_game()}
757
758\c void (*free_game)(game_state *state);
759
760This function frees a \c{game_state} structure, and any subsidiary
761allocations contained within it.
762
763\H{backend-ui} Handling \c{game_ui}
764
765\S{backend-new-ui} \cw{new_ui()}
766
767\c game_ui *(*new_ui)(game_state *state);
768
769This function allocates and returns a new \c{game_ui} structure for
770playing a particular puzzle. It is passed a pointer to the initial
771\c{game_state}, in case it needs to refer to that when setting up
772the initial values for the new game.
773
774\S{backend-free-ui} \cw{free_ui()}
775
776\c void (*free_ui)(game_ui *ui);
777
778This function frees a \c{game_ui} structure, and any subsidiary
779allocations contained within it.
780
781\S{backend-encode-ui} \cw{encode_ui()}
782
783\c char *(*encode_ui)(game_ui *ui);
784
785This function encodes any \e{important} data in a \c{game_ui}
786structure in string form. It is only called when saving a
787half-finished game to a file.
788
789It should be used sparingly. Almost all data in a \c{game_ui} is not
790important enough to save. The location of the keyboard-controlled
791cursor, for example, can be reset to a default position on reloading
792the game without impacting the user experience. If the user should
793somehow manage to save a game while a mouse drag was in progress,
794then discarding that mouse drag would be an outright \e{feature},
795
796A typical thing that \e{would} be worth encoding in this function is
797the Mines death counter: it's in the \c{game_ui} rather than the
798\c{game_state} because it's too important to allow the user to
799revert it by using Undo, and therefore it's also too important to
800allow the user to revert it by saving and reloading. (Of course, the
801user could edit the save file by hand... But if the user is \e{that}
802determined to cheat, they could just as easily modify the game's
803source.)
804
805\S{backend-decode-ui} \cw{decode_ui()}
806
807\c void (*decode_ui)(game_ui *ui, char *encoding);
808
809This function parses a string previously output by \cw{encode_ui()},
810and writes the decoded data back into the provided \c{game_ui}
811structure.
812
813\S{backend-changed-state} \cw{changed_state()}
814
815\c void (*changed_state)(game_ui *ui, game_state *oldstate,
816\c game_state *newstate);
817
818This function is called by the mid-end whenever the current game
819state changes, for any reason. Those reasons include:
820
821\b a fresh move being made by \cw{interpret_move()} and
822\cw{execute_move()}
823
824\b a solve operation being performed by \cw{solve()} and
825\cw{execute_move()}
826
827\b the user moving back and forth along the undo list by means of
828the Undo and Redo operations
829
830\b the user selecting Restart to go back to the initial game state.
831
832The job of \cw{changed_state()} is to update the \c{game_ui} for
833consistency with the new game state, if any update is necessary. For
834example, Same Game stores data about the currently selected tile
835group in its \c{game_ui}, and this data is intrinsically related to
836the game state it was derived from. So it's very likely to become
837invalid when the game state changes; thus, Same Game's
838\cw{changed_state()} function clears the current selection whenever
839it is called.
840
19937f86 841When \cw{anim_length()} or \cw{flash_length()} are called, you can
842be sure that there has been a previous call to \cw{changed_state()}.
843So \cw{changed_state()} can set up data in the \c{game_ui} which will
844be read by \cw{anim_length()} and \cw{flash_length()}, and those
845functions will not have to worry about being called without the data
846having been initialised.
69491f1e 847
848\H{backend-moves} Making moves
849
850This section describes the functions which actually make moves in
851the game: that is, the functions which process user input and end up
852producing new \c{game_state}s.
853
854\S{backend-interpret-move} \cw{interpret_move()}
855
856\c char *(*interpret_move)(game_state *state, game_ui *ui,
857\c game_drawstate *ds,
858\c int x, int y, int button);
859
860This function receives user input and processes it. Its input
861parameters are the current \c{game_state}, the current \c{game_ui}
862and the current \c{game_drawstate}, plus details of the input event.
863\c{button} is either an ASCII value or a special code (listed below)
864indicating an arrow or function key or a mouse event; when
865\c{button} is a mouse event, \c{x} and \c{y} contain the pixel
866coordinates of the mouse pointer relative to the top left of the
867puzzle's drawing area.
868
869\cw{interpret_move()} may return in three different ways:
870
871\b Returning \cw{NULL} indicates that no action whatsoever occurred
872in response to the input event; the puzzle was not interested in it
873at all.
874
875\b Returning the empty string (\cw{""}) indicates that the input
876event has resulted in a change being made to the \c{game_ui} which
877will require a redraw of the game window, but that no actual
878\e{move} was made (i.e. no new \c{game_state} needs to be created).
879
880\b Returning anything else indicates that a move was made and that a
881new \c{game_state} must be created. However, instead of actually
882constructing a new \c{game_state} itself, this function is required
883to return a string description of the details of the move. This
884string will be passed to \cw{execute_move()}
885(\k{backend-execute-move}) to actually create the new
886\c{game_state}. (Encoding moves as strings in this way means that
887the mid-end can keep the strings as well as the game states, and the
888strings can be written to disk when saving the game and fed to
889\cw{execute_move()} again on reloading.)
890
891The return value from \cw{interpret_move()} is expected to be
892dynamically allocated if and only if it is not either \cw{NULL}
893\e{or} the empty string.
894
895After this function is called, the back end is permitted to rely on
896some subsequent operations happening in sequence:
897
898\b \cw{execute_move()} will be called to convert this move
899description into a new \c{game_state}
900
901\b \cw{changed_state()} will be called with the new \c{game_state}.
902
903This means that if \cw{interpret_move()} needs to do updates to the
904\c{game_ui} which are easier to perform by referring to the new
905\c{game_state}, it can safely leave them to be done in
906\cw{changed_state()} and not worry about them failing to happen.
907
908(Note, however, that \cw{execute_move()} may \e{also} be called in
909other circumstances. It is only \cw{interpret_move()} which can rely
910on a subsequent call to \cw{changed_state()}.)
911
912The special key codes supported by this function are:
913
914\dt \cw{LEFT_BUTTON}, \cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}
915
916\dd Indicate that one of the mouse buttons was pressed down.
917
918\dt \cw{LEFT_DRAG}, \cw{MIDDLE_DRAG}, \cw{RIGHT_DRAG}
919
920\dd Indicate that the mouse was moved while one of the mouse buttons
921was still down. The mid-end guarantees that when one of these events
922is received, it will always have been preceded by a button-down
923event (and possibly other drag events) for the same mouse button,
924and no event involving another mouse button will have appeared in
925between.
926
927\dt \cw{LEFT_RELEASE}, \cw{MIDDLE_RELEASE}, \cw{RIGHT_RELEASE}
928
929\dd Indicate that a mouse button was released. The mid-end
930guarantees that when one of these events is received, it will always
931have been preceded by a button-down event (and possibly some drag
932events) for the same mouse button, and no event involving another
933mouse button will have appeared in between.
934
935\dt \cw{CURSOR_UP}, \cw{CURSOR_DOWN}, \cw{CURSOR_LEFT},
936\cw{CURSOR_RIGHT}
937
938\dd Indicate that an arrow key was pressed.
939
940\dt \cw{CURSOR_SELECT}
941
942\dd On platforms which have a prominent \q{select} button alongside
943their cursor keys, indicates that that button was pressed.
944
945In addition, there are some modifiers which can be bitwise-ORed into
946the \c{button} parameter:
947
948\dt \cw{MOD_CTRL}, \cw{MOD_SHFT}
949
950\dd These indicate that the Control or Shift key was pressed
951alongside the key. They only apply to the cursor keys, not to mouse
952buttons or anything else.
953
954\dt \cw{MOD_NUM_KEYPAD}
955
956\dd This applies to some ASCII values, and indicates that the key
957code was input via the numeric keypad rather than the main keyboard.
958Some puzzles may wish to treat this differently (for example, a
959puzzle might want to use the numeric keypad as an eight-way
960directional pad), whereas others might not (a game involving numeric
961input probably just wants to treat the numeric keypad as numbers).
962
963\dt \cw{MOD_MASK}
964
965\dd This mask is the bitwise OR of all the available modifiers; you
966can bitwise-AND with \cw{~MOD_MASK} to strip all the modifiers off
967any input value.
968
969\S{backend-execute-move} \cw{execute_move()}
970
971\c game_state *(*execute_move)(game_state *state, char *move);
972
973This function takes an input \c{game_state} and a move string as
974output from \cw{interpret_move()}. It returns a newly allocated
975\c{game_state} which contains the result of applying the specified
976move to the input game state.
977
978This function may return \cw{NULL} if it cannot parse the move
979string (and this is definitely preferable to crashing or failing an
980assertion, since one way this can happen is if loading a corrupt
981save file). However, it must not return \cw{NULL} for any move
982string that really was output from \cw{interpret_move()}: this is
983punishable by assertion failure in the mid-end.
984
985\S{backend-can-solve} \c{can_solve}
986
987\c int can_solve;
988
989This boolean field is set to \cw{TRUE} if the game's \cw{solve()}
990function does something. If it's set to \cw{FALSE}, the game will
991not even offer the \q{Solve} menu option.
992
993\S{backend-solve} \cw{solve()}
994
995\c char *(*solve)(game_state *orig, game_state *curr,
996\c char *aux, char **error);
997
998This function is called when the user selects the \q{Solve} option
999from the menu.
1000
1001It is passed two input game states: \c{orig} is the game state from
1002the very start of the puzzle, and \c{curr} is the current one.
1003(Different games find one or other or both of these convenient.) It
1004is also passed the \c{aux} string saved by \cw{new_desc()}
1005(\k{backend-new-desc}), in case that encodes important information
1006needed to provide the solution.
1007
1008If this function is unable to produce a solution (perhaps, for
1009example, the game has no in-built solver so it can only solve
1010puzzles it invented internally and has an \c{aux} string for) then
1011it may return \cw{NULL}. If it does this, it must also set
1012\c{*error} to an error message to be presented to the user (such as
1013\q{Solution not known for this puzzle}); that error message is not
1014expected to be dynamically allocated.
1015
1016If this function \e{does} produce a solution, it returns a move
1017string suitable for feeding to \cw{execute_move()}
1018(\k{backend-execute-move}).
1019
1020\H{backend-drawing} Drawing the game graphics
1021
1022This section discusses the back end functions that deal with
1023drawing.
1024
1025\S{backend-new-drawstate} \cw{new_drawstate()}
1026
dafd6cf6 1027\c game_drawstate *(*new_drawstate)(drawing *dr, game_state *state);
69491f1e 1028
1029This function allocates and returns a new \c{game_drawstate}
1030structure for drawing a particular puzzle. It is passed a pointer to
1031a \c{game_state}, in case it needs to refer to that when setting up
1032any initial data.
1033
1034This function may not rely on the puzzle having been newly started;
1035a new draw state can be constructed at any time if the front end
1036requests a forced redraw. For games like Pattern, in which initial
1037game states are much simpler than general ones, this might be
1038important to keep in mind.
1039
dafd6cf6 1040The parameter \c{dr} is a drawing object (see \k{drawing}) which the
1041function might need to use to allocate blitters. (However, this
1042isn't recommended; it's usually more sensible to wait to allocate a
1043blitter until \cw{set_size()} is called, because that way you can
1044tailor it to the scale at which the puzzle is being drawn.)
1045
69491f1e 1046\S{backend-free-drawstate} \cw{free_drawstate()}
1047
dafd6cf6 1048\c void (*free_drawstate)(drawing *dr, game_drawstate *ds);
69491f1e 1049
1050This function frees a \c{game_drawstate} structure, and any
1051subsidiary allocations contained within it.
1052
dafd6cf6 1053The parameter \c{dr} is a drawing object (see \k{drawing}), which
1054might be required if you are freeing a blitter.
1055
69491f1e 1056\S{backend-preferred-tilesize} \c{preferred_tilesize}
1057
1058\c int preferred_tilesize;
1059
1060Each game is required to define a single integer parameter which
1061expresses, in some sense, the scale at which it is drawn. This is
1062described in the APIs as \cq{tilesize}, since most puzzles are on a
1063square (or possibly triangular or hexagonal) grid and hence a
1064sensible interpretation of this parameter is to define it as the
1065size of one grid tile in pixels; however, there's no actual
1066requirement that the \q{tile size} be proportional to the game
1067window size. Window size is required to increase monotonically with
1068\q{tile size}, however.
1069
1070The data element \c{preferred_tilesize} indicates the tile size
1071which should be used in the absence of a good reason to do otherwise
1072(such as the screen being too small, or the user explicitly
1073requesting a resize if that ever gets implemented).
1074
1075\S{backend-compute-size} \cw{compute_size()}
1076
1077\c void (*compute_size)(game_params *params, int tilesize,
1078\c int *x, int *y);
1079
1080This function is passed a \c{game_params} structure and a tile size.
1081It returns, in \c{*x} and \c{*y}, the size in pixels of the drawing
1082area that would be required to render a puzzle with those parameters
1083at that tile size.
1084
1085\S{backend-set-size} \cw{set_size()}
1086
dafd6cf6 1087\c void (*set_size)(drawing *dr, game_drawstate *ds,
1088\c game_params *params, int tilesize);
69491f1e 1089
1090This function is responsible for setting up a \c{game_drawstate} to
1091draw at a given tile size. Typically this will simply involve
1092copying the supplied \c{tilesize} parameter into a \c{tilesize}
1093field inside the draw state; for some more complex games it might
1094also involve setting up other dimension fields, or possibly
1095allocating a blitter (see \k{drawing-blitter}).
1096
dafd6cf6 1097The parameter \c{dr} is a drawing object (see \k{drawing}), which is
1098required if a blitter needs to be allocated.
1099
05e50a96 1100Back ends may assume (and may enforce by assertion) that this
1101function will be called at most once for any \c{game_drawstate}. If
1102a puzzle needs to be redrawn at a different size, the mid-end will
1103create a fresh drawstate.
1104
69491f1e 1105\S{backend-colours} \cw{colours()}
1106
8266f3fc 1107\c float *(*colours)(frontend *fe, int *ncolours);
69491f1e 1108
1109This function is responsible for telling the front end what colours
1110the puzzle will need to draw itself.
1111
1112It returns the number of colours required in \c{*ncolours}, and the
1113return value from the function itself is a dynamically allocated
1114array of three times that many \c{float}s, containing the red, green
1115and blue components of each colour respectively as numbers in the
1116range [0,1].
1117
8266f3fc 1118The second parameter passed to this function is a front end handle.
e9f8a17f 1119The only things it is permitted to do with this handle are to call
1120the front-end function called \cw{frontend_default_colour()} (see
1121\k{frontend-default-colour}) or the utility function called
1122\cw{game_mkhighlight()} (see \k{utils-game-mkhighlight}). (The
1123latter is a wrapper on the former, so front end implementors only
1124need to provide \cw{frontend_default_colour()}.) This allows
1125\cw{colours()} to take local configuration into account when
1126deciding on its own colour allocations. Most games use the front
1127end's default colour as their background, apart from a few which
1128depend on drawing relief highlights so they adjust the background
1129colour if it's too light for highlights to show up against it.
69491f1e 1130
dafd6cf6 1131Note that the colours returned from this function are for
1132\e{drawing}, not for printing. Printing has an entirely different
1133colour allocation policy.
1134
69491f1e 1135\S{backend-anim-length} \cw{anim_length()}
1136
1137\c float (*anim_length)(game_state *oldstate, game_state *newstate,
1138\c int dir, game_ui *ui);
1139
1140This function is called when a move is made, undone or redone. It is
1141given the old and the new \c{game_state}, and its job is to decide
1142whether the transition between the two needs to be animated or can
1143be instant.
1144
1145\c{oldstate} is the state that was current until this call;
1146\c{newstate} is the state that will be current after it. \c{dir}
1147specifies the chronological order of those states: if it is
1148positive, then the transition is the result of a move or a redo (and
1149so \c{newstate} is the later of the two moves), whereas if it is
1150negative then the transition is the result of an undo (so that
1151\c{newstate} is the \e{earlier} move).
1152
1153If this function decides the transition should be animated, it
1154returns the desired length of the animation in seconds. If not, it
1155returns zero.
1156
1157State changes as a result of a Restart operation are never animated;
1158the mid-end will handle them internally and never consult this
1159function at all. State changes as a result of Solve operations are
1160also not animated by default, although you can change this for a
2705d374 1161particular game by setting a flag in \c{flags} (\k{backend-flags}).
69491f1e 1162
1163The function is also passed a pointer to the local \c{game_ui}. It
1164may refer to information in here to help with its decision (see
1165\k{writing-conditional-anim} for an example of this), and/or it may
1166\e{write} information about the nature of the animation which will
1167be read later by \cw{redraw()}.
1168
1169When this function is called, it may rely on \cw{changed_state()}
1170having been called previously, so if \cw{anim_length()} needs to
1171refer to information in the \c{game_ui}, then \cw{changed_state()}
1172is a reliable place to have set that information up.
1173
1174Move animations do not inhibit further input events. If the user
1175continues playing before a move animation is complete, the animation
1176will be abandoned and the display will jump straight to the final
1177state.
1178
1179\S{backend-flash-length} \cw{flash_length()}
1180
1181\c float (*flash_length)(game_state *oldstate, game_state *newstate,
1182\c int dir, game_ui *ui);
1183
1184This function is called when a move is completed. (\q{Completed}
1185means that not only has the move been made, but any animation which
1186accompanied it has finished.) It decides whether the transition from
1187\c{oldstate} to \c{newstate} merits a \q{flash}.
1188
1189A flash is much like a move animation, but it is \e{not} interrupted
1190by further user interface activity; it runs to completion in
1191parallel with whatever else might be going on on the display. The
1192only thing which will rush a flash to completion is another flash.
1193
1194The purpose of flashes is to indicate that the game has been
1195completed. They were introduced as a separate concept from move
1196animations because of Net: the habit of most Net players (and
1197certainly me) is to rotate a tile into place and immediately lock
1198it, then move on to another tile. When you make your last move, at
1199the instant the final tile is rotated into place the screen starts
1200to flash to indicate victory \dash but if you then press the lock
1201button out of habit, then the move animation is cancelled, and the
1202victory flash does not complete. (And if you \e{don't} press the
1203lock button, the completed grid will look untidy because there will
1204be one unlocked square.) Therefore, I introduced a specific concept
1205of a \q{flash} which is separate from a move animation and can
1206proceed in parallel with move animations and any other display
1207activity, so that the victory flash in Net is not cancelled by that
1208final locking move.
1209
1210The input parameters to \cw{flash_length()} are exactly the same as
1211the ones to \cw{anim_length()}.
1212
1213Just like \cw{anim_length()}, when this function is called, it may
1214rely on \cw{changed_state()} having been called previously, so if it
1215needs to refer to information in the \c{game_ui} then
1216\cw{changed_state()} is a reliable place to have set that
1217information up.
1218
1219(Some games use flashes to indicate defeat as well as victory;
1220Mines, for example, flashes in a different colour when you tread on
1221a mine from the colour it uses when you complete the game. In order
1222to achieve this, its \cw{flash_length()} function has to store a
1223flag in the \c{game_ui} to indicate which flash type is required.)
1224
1225\S{backend-redraw} \cw{redraw()}
1226
dafd6cf6 1227\c void (*redraw)(drawing *dr, game_drawstate *ds,
69491f1e 1228\c game_state *oldstate, game_state *newstate, int dir,
1229\c game_ui *ui, float anim_time, float flash_time);
1230
1231This function is responsible for actually drawing the contents of
1232the game window, and for redrawing every time the game state or the
1233\c{game_ui} changes.
1234
dafd6cf6 1235The parameter \c{dr} is a drawing object which may be passed to the
1236drawing API functions (see \k{drawing} for documentation of the
1237drawing API). This function may not save \c{dr} and use it
69491f1e 1238elsewhere; it must only use it for calling back to the drawing API
1239functions within its own lifetime.
1240
1241\c{ds} is the local \c{game_drawstate}, of course, and \c{ui} is the
1242local \c{game_ui}.
1243
1244\c{newstate} is the semantically-current game state, and is always
1245non-\cw{NULL}. If \c{oldstate} is also non-\cw{NULL}, it means that
1246a move has recently been made and the game is still in the process
1247of displaying an animation linking the old and new states; in this
1248situation, \c{anim_time} will give the length of time (in seconds)
1249that the animation has already been running. If \c{oldstate} is
1250\cw{NULL}, then \c{anim_time} is unused (and will hopefully be set
1251to zero to avoid confusion).
1252
1253\c{flash_time}, if it is is non-zero, denotes that the game is in
1254the middle of a flash, and gives the time since the start of the
1255flash. See \k{backend-flash-length} for general discussion of
1256flashes.
1257
1258The very first time this function is called for a new
1259\c{game_drawstate}, it is expected to redraw the \e{entire} drawing
1260area. Since this often involves drawing visual furniture which is
1261never subsequently altered, it is often simplest to arrange this by
1262having a special \q{first time} flag in the draw state, and
1263resetting it after the first redraw.
1264
dafd6cf6 1265When this function (or any subfunction) calls the drawing API, it is
1266expected to pass colour indices which were previously defined by the
1267\cw{colours()} function.
1268
1269\H{backend-printing} Printing functions
1270
1271This section discusses the back end functions that deal with
1272printing puzzles out on paper.
1273
1274\S{backend-can-print} \c{can_print}
1275
1276\c int can_print;
1277
1278This flag is set to \cw{TRUE} if the puzzle is capable of printing
1279itself on paper. (This makes sense for some puzzles, such as Solo,
1280which can be filled in with a pencil. Other puzzles, such as
1281Twiddle, inherently involve moving things around and so would not
1282make sense to print.)
1283
1284If this flag is \cw{FALSE}, then the functions \cw{print_size()}
1285and \cw{print()} will never be called.
1286
1287\S{backend-can-print-in-colour} \c{can_print_in_colour}
1288
1289\c int can_print_in_colour;
1290
1291This flag is set to \cw{TRUE} if the puzzle is capable of printing
1292itself differently when colour is available. For example, Map can
1293actually print coloured regions in different \e{colours} rather than
1294resorting to cross-hatching.
1295
1296If the \c{can_print} flag is \cw{FALSE}, then this flag will be
1297ignored.
1298
1299\S{backend-print-size} \cw{print_size()}
1300
1301\c void (*print_size)(game_params *params, float *x, float *y);
1302
1303This function is passed a \c{game_params} structure and a tile size.
1304It returns, in \c{*x} and \c{*y}, the preferred size in
1305\e{millimetres} of that puzzle if it were to be printed out on paper.
1306
1307If the \c{can_print} flag is \cw{FALSE}, this function will never be
1308called.
1309
1310\S{backend-print} \cw{print()}
1311
1312\c void (*print)(drawing *dr, game_state *state, int tilesize);
1313
1314This function is called when a puzzle is to be printed out on paper.
1315It should use the drawing API functions (see \k{drawing}) to print
1316itself.
1317
1318This function is separate from \cw{redraw()} because it is often
1319very different:
1320
1321\b The printing function may not depend on pixel accuracy, since
1322printer resolution is variable. Draw as if your canvas had infinite
1323resolution.
1324
1325\b The printing function sometimes needs to display things in a
1326completely different style. Net, for example, is very different as
1327an on-screen puzzle and as a printed one.
1328
1329\b The printing function is often much simpler since it has no need
1330to deal with repeated partial redraws.
1331
1332However, there's no reason the printing and redraw functions can't
1333share some code if they want to.
1334
1335When this function (or any subfunction) calls the drawing API, the
1336colour indices it passes should be colours which have been allocated
1337by the \cw{print_*_colour()} functions within this execution of
1338\cw{print()}. This is very different from the fixed small number of
1339colours used in \cw{redraw()}, because printers do not have a
1340limitation on the total number of colours that may be used. Some
1341puzzles' printing functions might wish to allocate only one \q{ink}
1342colour and use it for all drawing; others might wish to allocate
1343\e{more} colours than are used on screen.
1344
1345One possible colour policy worth mentioning specifically is that a
1346puzzle's printing function might want to allocate the \e{same}
1347colour indices as are used by the redraw function, so that code
1348shared between drawing and printing does not have to keep switching
1349its colour indices. In order to do this, the simplest thing is to
1350make use of the fact that colour indices returned from
1351\cw{print_*_colour()} are guaranteed to be in increasing order from
1352zero. So if you have declared an \c{enum} defining three colours
1353\cw{COL_BACKGROUND}, \cw{COL_THIS} and \cw{COL_THAT}, you might then
1354write
1355
1356\c int c;
1357\c c = print_mono_colour(dr, 1); assert(c == COL_BACKGROUND);
1358\c c = print_mono_colour(dr, 0); assert(c == COL_THIS);
1359\c c = print_mono_colour(dr, 0); assert(c == COL_THAT);
1360
1361If the \c{can_print} flag is \cw{FALSE}, this function will never be
1362called.
1363
69491f1e 1364\H{backend-misc} Miscellaneous
1365
1366\S{backend-can-format-as-text} \c{can_format_as_text}
1367
1368\c int can_format_as_text;
1369
1370This boolean field is \cw{TRUE} if the game supports formatting a
1371game state as ASCII text (typically ASCII art) for copying to the
1372clipboard and pasting into other applications. If it is \cw{FALSE},
1373front ends will not offer the \q{Copy} command at all.
1374
1375If this field is \cw{FALSE}, the function \cw{text_format()}
1376(\k{backend-text-format}) is not expected to do anything at all.
1377
1378\S{backend-text-format} \cw{text_format()}
1379
1380\c char *(*text_format)(game_state *state);
1381
1382This function is passed a \c{game_state}, and returns a newly
1383allocated C string containing an ASCII representation of that game
1384state. It is used to implement the \q{Copy} operation in many front
1385ends.
1386
1387This function should only be called if the back end field
1388\c{can_format_as_text} (\k{backend-can-format-as-text}) is
1389\cw{TRUE}.
1390
1391The returned string may contain line endings (and will probably want
1392to), using the normal C internal \cq{\\n} convention. For
1393consistency between puzzles, all multi-line textual puzzle
1394representations should \e{end} with a newline as well as containing
1395them internally. (There are currently no puzzles which have a
1396one-line ASCII representation, so there's no precedent yet for
1397whether that should come with a newline or not.)
1398
1399\S{backend-wants-statusbar} \cw{wants_statusbar()}
1400
9680576d 1401\c int wants_statusbar;
69491f1e 1402
9680576d 1403This boolean field is set to \cw{TRUE} if the puzzle has a use for a
69491f1e 1404textual status line (to display score, completion status, currently
1405active tiles, etc).
1406
69491f1e 1407\S{backend-is-timed} \c{is_timed}
1408
1409\c int is_timed;
1410
1411This boolean field is \cw{TRUE} if the puzzle is time-critical. If
1412so, the mid-end will maintain a game timer while the user plays.
1413
1414If this field is \cw{FALSE}, then \cw{timing_state()} will never be
1415called and need not do anything.
1416
1417\S{backend-timing-state} \cw{timing_state()}
1418
1419\c int (*timing_state)(game_state *state, game_ui *ui);
1420
1421This function is passed the current \c{game_state} and the local
1422\c{game_ui}; it returns \cw{TRUE} if the game timer should currently
1423be running.
1424
1425A typical use for the \c{game_ui} in this function is to note when
1426the game was first completed (by setting a flag in
1427\cw{changed_state()} \dash see \k{backend-changed-state}), and
1428freeze the timer thereafter so that the user can undo back through
1429their solution process without altering their time.
1430
2705d374 1431\S{backend-flags} \c{flags}
69491f1e 1432
2705d374 1433\c int flags;
69491f1e 1434
2705d374 1435This field contains miscellaneous per-backend flags. It consists of
1436the bitwise OR of some combination of the following:
69491f1e 1437
1438\dt \cw{BUTTON_BEATS(x,y)}
1439
1440\dd Given any \cw{x} and \cw{y} from the set (\cw{LEFT_BUTTON},
1441\cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}), this macro evaluates to a
1442bit flag which indicates that when buttons \cw{x} and \cw{y} are
1443both pressed simultaneously, the mid-end should consider \cw{x} to
1444have priority. (In the absence of any such flags, the mid-end will
1445always consider the most recently pressed button to have priority.)
1446
1447\dt \cw{SOLVE_ANIMATES}
1448
1449\dd This flag indicates that moves generated by \cw{solve()}
1450(\k{backend-solve}) are candidates for animation just like any other
1451move. For most games, solve moves should not be animated, so the
1452mid-end doesn't even bother calling \cw{anim_length()}
1453(\k{backend-anim-length}), thus saving some special-case code in
1454each game. On the rare occasion that animated solve moves are
1455actually required, you can set this flag.
1456
1457\H{backend-initiative} Things a back end may do on its own initiative
1458
1459This section describes a couple of things that a back end may choose
1460to do by calling functions elsewhere in the program, which would not
1461otherwise be obvious.
1462
1463\S{backend-newrs} Create a random state
1464
1465If a back end needs random numbers at some point during normal play,
1466it can create a fresh \c{random_state} by first calling
1467\c{get_random_seed} (\k{frontend-get-random-seed}) and then passing
1fbb0680 1468the returned seed data to \cw{random_new()}.
69491f1e 1469
1470This is likely not to be what you want. If a puzzle needs randomness
1471in the middle of play, it's likely to be more sensible to store some
1472sort of random state within the \e{game_state}, so that the random
1473numbers are tied to the particular game state and hence the player
1474can't simply keep undoing their move until they get numbers they
1475like better.
1476
1477This facility is currently used only in Net, to implement the
1478\q{jumble} command, which sets every unlocked tile to a new random
1479orientation. This randomness \e{is} a reasonable use of the feature,
1480because it's non-adversarial \dash there's no advantage to the user
1481in getting different random numbers.
1482
1483\S{backend-supersede} Supersede its own game description
1484
1485In response to a move, a back end is (reluctantly) permitted to call
1486\cw{midend_supersede_game_desc()}:
1487
dafd6cf6 1488\c void midend_supersede_game_desc(midend *me,
69491f1e 1489\c char *desc, char *privdesc);
1490
1491When the user selects \q{New Game}, the mid-end calls
1492\cw{new_desc()} (\k{backend-new-desc}) to get a new game
1493description, and (as well as using that to generate an initial game
1494state) stores it for the save file and for telling to the user. The
1495function above overwrites that game description, and also splits it
1496in two. \c{desc} becomes the new game description which is provided
1497to the user on request, and is also the one used to construct a new
1498initial game state if the user selects \q{Restart}. \c{privdesc} is
1499a \q{private} game description, used to reconstruct the game's
1500initial state when reloading.
1501
1502The distinction between the two, as well as the need for this
1503function at all, comes from Mines. Mines begins with a blank grid
1504and no idea of where the mines actually are; \cw{new_desc()} does
1505almost no work in interactive mode, and simply returns a string
1506encoding the \c{random_state}. When the user first clicks to open a
1507tile, \e{then} Mines generates the mine positions, in such a way
1508that the game is soluble from that starting point. Then it uses this
1509function to supersede the random-state game description with a
1510proper one. But it needs two: one containing the initial click
1511location (because that's what you want to happen if you restart the
1512game, and also what you want to send to a friend so that they play
1513\e{the same game} as you), and one without the initial click
1514location (because when you save and reload the game, you expect to
1515see the same blank initial state as you had before saving).
1516
1517I should stress again that this function is a horrid hack. Nobody
1518should use it if they're not Mines; if you think you need to use it,
1519think again repeatedly in the hope of finding a better way to do
1520whatever it was you needed to do.
1521
dafd6cf6 1522\C{drawing} The drawing API
69491f1e 1523
1524The back end function \cw{redraw()} (\k{backend-redraw}) is required
dafd6cf6 1525to draw the puzzle's graphics on the window's drawing area, or on
1526paper if the puzzle is printable. To do this portably, it is
1527provided with a drawing API allowing it to talk directly to the
1528front end. In this chapter I document that API, both for the benefit
1529of back end authors trying to use it and for front end authors
1530trying to implement it.
1531
1532The drawing API as seen by the back end is a collection of global
1533functions, each of which takes a pointer to a \c{drawing} structure
1534(a \q{drawing object}). These objects are supplied as parameters to
1535the back end's \cw{redraw()} and \cw{print()} functions.
1536
1537In fact these global functions are not implemented directly by the
1538front end; instead, they are implemented centrally in \c{drawing.c}
1539and form a small piece of middleware. The drawing API as supplied by
1540the front end is a structure containing a set of function pointers,
1541plus a \cq{void *} handle which is passed to each of those
1542functions. This enables a single front end to switch between
1543multiple implementations of the drawing API if necessary. For
1544example, the Windows API supplies a printing mechanism integrated
1545into the same GDI which deals with drawing in windows, and therefore
74021716 1546the same API implementation can handle both drawing and printing;
1547but on Unix, the most common way for applications to print is by
1548producing PostScript output directly, and although it would be
1549\e{possible} to write a single (say) \cw{draw_rect()} function which
1550checked a global flag to decide whether to do GTK drawing operations
1551or output PostScript to a file, it's much nicer to have two separate
1552functions and switch between them as appropriate.
dafd6cf6 1553
1554When drawing, the puzzle window is indexed by pixel coordinates,
1555with the top left pixel defined as \cw{(0,0)} and the bottom right
1556pixel \cw{(w-1,h-1)}, where \c{w} and \c{h} are the width and height
69491f1e 1557values returned by the back end function \cw{compute_size()}
1558(\k{backend-compute-size}).
1559
dafd6cf6 1560When printing, the puzzle's print area is indexed in exactly the
1561same way (with an arbitrary tile size provided by the printing
1562module \c{printing.c}), to facilitate sharing of code between the
1563drawing and printing routines. However, when printing, puzzles may
1564no longer assume that the coordinate unit has any relationship to a
1565pixel; the printer's actual resolution might very well not even be
1566known at print time, so the coordinate unit might be smaller or
1567larger than a pixel. Puzzles' print functions should restrict
1568themselves to drawing geometric shapes rather than fiddly pixel
1569manipulation.
1570
1571\e{Puzzles' redraw functions may assume that the surface they draw
1572on is persistent}. It is the responsibility of every front end to
1573preserve the puzzle's window contents in the face of GUI window
1574expose issues and similar. It is not permissible to request the back
1575end redraw any part of a window that it has already drawn, unless
1576something has actually changed as a result of making moves in the
1577puzzle.
69491f1e 1578
1579Most front ends accomplish this by having the drawing routines draw
1580on a stored bitmap rather than directly on the window, and copying
1581the bitmap to the window every time a part of the window needs to be
1582redrawn. Therefore, it is vitally important that whenever the back
1583end does any drawing it informs the front end of which parts of the
1584window it has accessed, and hence which parts need repainting. This
1585is done by calling \cw{draw_update()} (\k{drawing-draw-update}).
1586
dafd6cf6 1587In the following sections I first discuss the drawing API as seen by
1588the back end, and then the \e{almost} identical function-pointer
1589form seen by the front end.
1590
1591\H{drawing-backend} Drawing API as seen by the back end
69491f1e 1592
dafd6cf6 1593This section documents the back-end drawing API, in the form of
1594functions which take a \c{drawing} object as an argument.
1595
1596\S{drawing-draw-rect} \cw{draw_rect()}
1597
1598\c void draw_rect(drawing *dr, int x, int y, int w, int h,
69491f1e 1599\c int colour);
1600
1601Draws a filled rectangle in the puzzle window.
1602
1603\c{x} and \c{y} give the coordinates of the top left pixel of the
1604rectangle. \c{w} and \c{h} give its width and height. Thus, the
1605horizontal extent of the rectangle runs from \c{x} to \c{x+w-1}
1606inclusive, and the vertical extent from \c{y} to \c{y+h-1}
1607inclusive.
1608
1609\c{colour} is an integer index into the colours array returned by
1610the back end function \cw{colours()} (\k{backend-colours}).
1611
1612There is no separate pixel-plotting function. If you want to plot a
1613single pixel, the approved method is to use \cw{draw_rect()} with
1614width and height set to 1.
1615
1616Unlike many of the other drawing functions, this function is
1617guaranteed to be pixel-perfect: the rectangle will be sharply
1618defined and not anti-aliased or anything like that.
1619
dafd6cf6 1620This function may be used for both drawing and printing.
1621
1622\S{drawing-draw-rect-outline} \cw{draw_rect_outline()}
69491f1e 1623
dafd6cf6 1624\c void draw_rect_outline(drawing *dr, int x, int y, int w, int h,
69491f1e 1625\c int colour);
1626
1627Draws an outline rectangle in the puzzle window.
1628
1629\c{x} and \c{y} give the coordinates of the top left pixel of the
1630rectangle. \c{w} and \c{h} give its width and height. Thus, the
1631horizontal extent of the rectangle runs from \c{x} to \c{x+w-1}
1632inclusive, and the vertical extent from \c{y} to \c{y+h-1}
1633inclusive.
1634
1635\c{colour} is an integer index into the colours array returned by
1636the back end function \cw{colours()} (\k{backend-colours}).
1637
1638From a back end perspective, this function may be considered to be
1639part of the drawing API. However, front ends are not required to
1640implement it, since it is actually implemented centrally (in
dafd6cf6 1641\cw{misc.c}) as a wrapper on \cw{draw_polygon()}.
69491f1e 1642
dafd6cf6 1643This function may be used for both drawing and printing.
69491f1e 1644
dafd6cf6 1645\S{drawing-draw-line} \cw{draw_line()}
1646
1647\c void draw_line(drawing *dr, int x1, int y1, int x2, int y2,
69491f1e 1648\c int colour);
1649
1650Draws a straight line in the puzzle window.
1651
1652\c{x1} and \c{y1} give the coordinates of one end of the line.
1653\c{x2} and \c{y2} give the coordinates of the other end. The line
1654drawn includes both those points.
1655
1656\c{colour} is an integer index into the colours array returned by
1657the back end function \cw{colours()} (\k{backend-colours}).
1658
1659Some platforms may perform anti-aliasing on this function.
1660Therefore, do not assume that you can erase a line by drawing the
1661same line over it in the background colour; anti-aliasing might
1662lead to perceptible ghost artefacts around the vanished line.
1663
dafd6cf6 1664This function may be used for both drawing and printing.
1665
1666\S{drawing-draw-polygon} \cw{draw_polygon()}
69491f1e 1667
dafd6cf6 1668\c void draw_polygon(drawing *dr, int *coords, int npoints,
69491f1e 1669\c int fillcolour, int outlinecolour);
1670
1671Draws an outlined or filled polygon in the puzzle window.
1672
1673\c{coords} is an array of \cw{(2*npoints)} integers, containing the
1674\c{x} and \c{y} coordinates of \c{npoints} vertices.
1675
1676\c{fillcolour} and \c{outlinecolour} are integer indices into the
1677colours array returned by the back end function \cw{colours()}
1678(\k{backend-colours}). \c{fillcolour} may also be \cw{-1} to
1679indicate that the polygon should be outlined only.
1680
1681The polygon defined by the specified list of vertices is first
1682filled in \c{fillcolour}, if specified, and then outlined in
1683\c{outlinecolour}.
1684
1685\c{outlinecolour} may \e{not} be \cw{-1}; it must be a valid colour
1686(and front ends are permitted to enforce this by assertion). This is
1687because different platforms disagree on whether a filled polygon
1688should include its boundary line or not, so drawing \e{only} a
1689filled polygon would have non-portable effects. If you want your
1690filled polygon not to have a visible outline, you must set
1691\c{outlinecolour} to the same as \c{fillcolour}.
1692
1693Some platforms may perform anti-aliasing on this function.
1694Therefore, do not assume that you can erase a polygon by drawing the
1695same polygon over it in the background colour. Also, be prepared for
1696the polygon to extend a pixel beyond its obvious bounding box as a
1697result of this; if you really need it not to do this to avoid
1698interfering with other delicate graphics, you should probably use
1699\cw{clip()} (\k{drawing-clip}).
1700
dafd6cf6 1701This function may be used for both drawing and printing.
1702
1703\S{drawing-draw-circle} \cw{draw_circle()}
69491f1e 1704
dafd6cf6 1705\c void draw_circle(drawing *dr, int cx, int cy, int radius,
69491f1e 1706\c int fillcolour, int outlinecolour);
1707
1708Draws an outlined or filled circle in the puzzle window.
1709
1710\c{cx} and \c{cy} give the coordinates of the centre of the circle.
1711\c{radius} gives its radius. The total horizontal pixel extent of
1712the circle is from \c{cx-radius+1} to \c{cx+radius-1} inclusive, and
1713the vertical extent similarly around \c{cy}.
1714
1715\c{fillcolour} and \c{outlinecolour} are integer indices into the
1716colours array returned by the back end function \cw{colours()}
1717(\k{backend-colours}). \c{fillcolour} may also be \cw{-1} to
1718indicate that the circle should be outlined only.
1719
1720The circle is first filled in \c{fillcolour}, if specified, and then
1721outlined in \c{outlinecolour}.
1722
1723\c{outlinecolour} may \e{not} be \cw{-1}; it must be a valid colour
1724(and front ends are permitted to enforce this by assertion). This is
1725because different platforms disagree on whether a filled circle
1726should include its boundary line or not, so drawing \e{only} a
1727filled circle would have non-portable effects. If you want your
1728filled circle not to have a visible outline, you must set
1729\c{outlinecolour} to the same as \c{fillcolour}.
1730
1731Some platforms may perform anti-aliasing on this function.
1732Therefore, do not assume that you can erase a circle by drawing the
1733same circle over it in the background colour. Also, be prepared for
1734the circle to extend a pixel beyond its obvious bounding box as a
1735result of this; if you really need it not to do this to avoid
1736interfering with other delicate graphics, you should probably use
1737\cw{clip()} (\k{drawing-clip}).
1738
dafd6cf6 1739This function may be used for both drawing and printing.
69491f1e 1740
dafd6cf6 1741\S{drawing-draw-text} \cw{draw_text()}
1742
1743\c void draw_text(drawing *dr, int x, int y, int fonttype,
69491f1e 1744\c int fontsize, int align, int colour, char *text);
1745
1746Draws text in the puzzle window.
1747
1748\c{x} and \c{y} give the coordinates of a point. The relation of
1749this point to the location of the text is specified by \c{align},
1750which is a bitwise OR of horizontal and vertical alignment flags:
1751
1752\dt \cw{ALIGN_VNORMAL}
1753
1754\dd Indicates that \c{y} is aligned with the baseline of the text.
1755
1756\dt \cw{ALIGN_VCENTRE}
1757
1758\dd Indicates that \c{y} is aligned with the vertical centre of the
1759text. (In fact, it's aligned with the vertical centre of normal
1760\e{capitalised} text: displaying two pieces of text with
1761\cw{ALIGN_VCENTRE} at the same \cw{y}-coordinate will cause their
1762baselines to be aligned with one another, even if one is an ascender
1763and the other a descender.)
1764
1765\dt \cw{ALIGN_HLEFT}
1766
1767\dd Indicates that \c{x} is aligned with the left-hand end of the
1768text.
1769
1770\dt \cw{ALIGN_HCENTRE}
1771
1772\dd Indicates that \c{x} is aligned with the horizontal centre of
1773the text.
1774
1775\dt \cw{ALIGN_HRIGHT}
1776
1777\dd Indicates that \c{x} is aligned with the right-hand end of the
1778text.
1779
1780\c{fonttype} is either \cw{FONT_FIXED} or \cw{FONT_VARIABLE}, for a
1781monospaced or proportional font respectively. (No more detail than
1782that may be specified; it would only lead to portability issues
1783between different platforms.)
1784
1785\c{fontsize} is the desired size, in pixels, of the text. This size
1786corresponds to the overall point size of the text, not to any
1787internal dimension such as the cap-height.
1788
1789\c{colour} is an integer index into the colours array returned by
1790the back end function \cw{colours()} (\k{backend-colours}).
1791
dafd6cf6 1792This function may be used for both drawing and printing.
1793
1794\S{drawing-clip} \cw{clip()}
69491f1e 1795
dafd6cf6 1796\c void clip(drawing *dr, int x, int y, int w, int h);
69491f1e 1797
1798Establishes a clipping rectangle in the puzzle window.
1799
1800\c{x} and \c{y} give the coordinates of the top left pixel of the
1801clipping rectangle. \c{w} and \c{h} give its width and height. Thus,
1802the horizontal extent of the rectangle runs from \c{x} to \c{x+w-1}
1803inclusive, and the vertical extent from \c{y} to \c{y+h-1}
1804inclusive. (These are exactly the same semantics as
1805\cw{draw_rect()}.)
1806
1807After this call, no drawing operation will affect anything outside
1808the specified rectangle. The effect can be reversed by calling
1809\cw{unclip()} (\k{drawing-unclip}).
1810
1811Back ends should not assume that a clipping rectangle will be
1812automatically cleared up by the front end if it's left lying around;
1813that might work on current front ends, but shouldn't be relied upon.
1814Always explicitly call \cw{unclip()}.
1815
dafd6cf6 1816This function may be used for both drawing and printing.
69491f1e 1817
dafd6cf6 1818\S{drawing-unclip} \cw{unclip()}
1819
1820\c void unclip(drawing *dr);
69491f1e 1821
1822Reverts the effect of a previous call to \cw{clip()}. After this
1823call, all drawing operations will be able to affect the entire
1824puzzle window again.
1825
dafd6cf6 1826This function may be used for both drawing and printing.
1827
1828\S{drawing-draw-update} \cw{draw_update()}
69491f1e 1829
dafd6cf6 1830\c void draw_update(drawing *dr, int x, int y, int w, int h);
69491f1e 1831
1832Informs the front end that a rectangular portion of the puzzle
1833window has been drawn on and needs to be updated.
1834
1835\c{x} and \c{y} give the coordinates of the top left pixel of the
1836update rectangle. \c{w} and \c{h} give its width and height. Thus,
1837the horizontal extent of the rectangle runs from \c{x} to \c{x+w-1}
1838inclusive, and the vertical extent from \c{y} to \c{y+h-1}
1839inclusive. (These are exactly the same semantics as
1840\cw{draw_rect()}.)
1841
1842The back end redraw function \e{must} call this function to report
1843any changes it has made to the window. Otherwise, those changes may
1844not become immediately visible, and may then appear at an
1845unpredictable subsequent time such as the next time the window is
1846covered and re-exposed.
1847
dafd6cf6 1848This function is only important when drawing. It may be called when
1849printing as well, but doing so is not compulsory, and has no effect.
1850(So if you have a shared piece of code between the drawing and
1851printing routines, that code may safely call \cw{draw_update()}.)
69491f1e 1852
dafd6cf6 1853\S{drawing-status-bar} \cw{status_bar()}
1854
1855\c void status_bar(drawing *dr, char *text);
69491f1e 1856
e9f8a17f 1857Sets the text in the game's status bar to \c{text}. The text is copied
1858from the supplied buffer, so the caller is free to deallocate or
1859modify the buffer after use.
69491f1e 1860
1861(This function is not exactly a \e{drawing} function, but it shares
1862with the drawing API the property that it may only be called from
1863within the back end redraw function, so this is as good a place as
1864any to document it.)
1865
83c0438f 1866The supplied text is filtered through the mid-end for optional
1867rewriting before being passed on to the front end; the mid-end will
1868prepend the current game time if the game is timed (and may in
1869future perform other rewriting if it seems like a good idea).
1870
dafd6cf6 1871This function is for drawing only; it must never be called during
1872printing.
69491f1e 1873
dafd6cf6 1874\S{drawing-blitter} Blitter functions
69491f1e 1875
e9f8a17f 1876This section describes a group of related functions which save and
69491f1e 1877restore a section of the puzzle window. This is most commonly used
1878to implement user interfaces involving dragging a puzzle element
1879around the window: at the end of each call to \cw{redraw()}, if an
1880object is currently being dragged, the back end saves the window
1881contents under that location and then draws the dragged object, and
1882at the start of the next \cw{redraw()} the first thing it does is to
1883restore the background.
1884
1885The front end defines an opaque type called a \c{blitter}, which is
1886capable of storing a rectangular area of a specified size.
1887
dafd6cf6 1888Blitter functions are for drawing only; they must never be called
1889during printing.
1890
1891\S2{drawing-blitter-new} \cw{blitter_new()}
69491f1e 1892
dafd6cf6 1893\c blitter *blitter_new(drawing *dr, int w, int h);
69491f1e 1894
1895Creates a new blitter object which stores a rectangle of size \c{w}
1896by \c{h} pixels. Returns a pointer to the blitter object.
1897
1898Blitter objects are best stored in the \c{game_drawstate}. A good
1899time to create them is in the \cw{set_size()} function
1900(\k{backend-set-size}), since it is at this point that you first
1901know how big a rectangle they will need to save.
1902
dafd6cf6 1903\S2{drawing-blitter-free} \cw{blitter_free()}
69491f1e 1904
dafd6cf6 1905\c void blitter_free(drawing *dr, blitter *bl);
69491f1e 1906
1907Disposes of a blitter object. Best called in \cw{free_drawstate()}.
1908(However, check that the blitter object is not \cw{NULL} before
1909attempting to free it; it is possible that a draw state might be
1910created and freed without ever having \cw{set_size()} called on it
1911in between.)
1912
dafd6cf6 1913\S2{drawing-blitter-save} \cw{blitter_save()}
69491f1e 1914
dafd6cf6 1915\c void blitter_save(drawing *dr, blitter *bl, int x, int y);
69491f1e 1916
1917This is a true drawing API function, in that it may only be called
1918from within the game redraw routine. It saves a rectangular portion
1919of the puzzle window into the specified blitter object.
1920
1921\c{x} and \c{y} give the coordinates of the top left corner of the
1922saved rectangle. The rectangle's width and height are the ones
1923specified when the blitter object was created.
1924
1925This function is required to cope and do the right thing if \c{x}
1926and \c{y} are out of range. (The right thing probably means saving
1927whatever part of the blitter rectangle overlaps with the visible
1928area of the puzzle window.)
1929
dafd6cf6 1930\S2{drawing-blitter-load} \cw{blitter_load()}
69491f1e 1931
dafd6cf6 1932\c void blitter_load(drawing *dr, blitter *bl, int x, int y);
69491f1e 1933
1934This is a true drawing API function, in that it may only be called
1935from within the game redraw routine. It restores a rectangular
1936portion of the puzzle window from the specified blitter object.
1937
1938\c{x} and \c{y} give the coordinates of the top left corner of the
1939rectangle to be restored. The rectangle's width and height are the
1940ones specified when the blitter object was created.
1941
1942Alternatively, you can specify both \c{x} and \c{y} as the special
1943value \cw{BLITTER_FROMSAVED}, in which case the rectangle will be
1944restored to exactly where it was saved from. (This is probably what
1945you want to do almost all the time, if you're using blitters to
1946implement draggable puzzle elements.)
1947
1948This function is required to cope and do the right thing if \c{x}
1949and \c{y} (or the equivalent ones saved in the blitter) are out of
1950range. (The right thing probably means restoring whatever part of
1951the blitter rectangle overlaps with the visible area of the puzzle
1952window.)
1953
1954If this function is called on a blitter which had previously been
1955saved from a partially out-of-range rectangle, then the parts of the
1956saved bitmap which were not visible at save time are undefined. If
1957the blitter is restored to a different position so as to make those
1958parts visible, the effect on the drawing area is undefined.
1959
dafd6cf6 1960\S{print-mono-colour} \cw{print_mono_colour()}
1961
1962\c int print_mono_colour(drawing *dr, int grey);
1963
1964This function allocates a colour index for a simple monochrome
1965colour during printing.
1966
1967\c{grey} must be 0 or 1. If \c{grey} is 0, the colour returned is
1968black; if \c{grey} is 1, the colour is white.
1969
1970\S{print-grey-colour} \cw{print_grey_colour()}
1971
1972\c int print_grey_colour(drawing *dr, int hatch, float grey);
1973
1974This function allocates a colour index for a grey-scale colour
1975during printing.
1976
1977\c{grey} may be any number between 0 (black) and 1 (white); for
1978example, 0.5 indicates a medium grey.
1979
1980If printing in black and white only, the \c{grey} value will not be
1981used; instead, regions shaded in this colour will be hatched with
1982parallel lines. The \c{hatch} parameter defines what type of
1983hatching should be used in place of this colour:
1984
1985\dt \cw{HATCH_SOLID}
1986
1987\dd In black and white, this colour will be replaced by solid black.
1988
1989\dt \cw{HATCH_CLEAR}
1990
1991\dd In black and white, this colour will be replaced by solid white.
1992
1993\dt \cw{HATCH_SLASH}
1994
1995\dd This colour will be hatched by lines slanting to the right at 45
1996degrees.
1997
1998\dt \cw{HATCH_BACKSLASH}
1999
2000\dd This colour will be hatched by lines slanting to the left at 45
2001degrees.
2002
2003\dt \cw{HATCH_HORIZ}
2004
2005\dd This colour will be hatched by horizontal lines.
2006
2007\dt \cw{HATCH_VERT}
2008
2009\dd This colour will be hatched by vertical lines.
2010
2011\dt \cw{HATCH_PLUS}
2012
2013\dd This colour will be hatched by criss-crossing horizontal and
2014vertical lines.
2015
2016\dt \cw{HATCH_X}
2017
2018\dd This colour will be hatched by criss-crossing diagonal lines.
2019
2020Colours defined to use hatching may not be used for drawing lines;
2021they may only be used for filling areas. That is, they may be used
2022as the \c{fillcolour} parameter to \cw{draw_circle()} and
2023\cw{draw_polygon()}, and as the colour parameter to
2024\cw{draw_rect()}, but may not be used as the \c{outlinecolour}
2025parameter to \cw{draw_circle()} or \cw{draw_polygon()}, or with
2026\cw{draw_line()}.
2027
2028\S{print-rgb-colour} \cw{print_rgb_colour()}
2029
2030\c int print_rgb_colour(drawing *dr, int hatch,
2031\c float r, float g, float b);
2032
2033This function allocates a colour index for a fully specified RGB
2034colour during printing.
2035
2036\c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1.
2037
f487468f 2038If printing in black and white only, these values will not be used;
2039instead, regions shaded in this colour will be hatched with parallel
2040lines. The \c{hatch} parameter defines what type of hatching should
2041be used in place of this colour; see \k{print-grey-colour} for its
2042definition.
dafd6cf6 2043
2044\S{print-line-width} \cw{print_line_width()}
2045
2046\c void print_line_width(drawing *dr, int width);
2047
2048This function is called to set the thickness of lines drawn during
2049printing. It is meaningless in drawing: all lines drawn by
2050\cw{draw_line()}, \cw{draw_circle} and \cw{draw_polygon()} are one
2051pixel in thickness. However, in printing there is no clear
2052definition of a pixel and so line widths must be explicitly
2053specified.
2054
2055The line width is specified in the usual coordinate system. Note,
2056however, that it is a hint only: the central printing system may
2057choose to vary line thicknesses at user request or due to printer
2058capabilities.
2059
2060\H{drawing-frontend} The drawing API as implemented by the front end
2061
2062This section describes the drawing API in the function-pointer form
2063in which it is implemented by a front end.
2064
2065(It isn't only platform-specific front ends which implement this
2066API; the platform-independent module \c{ps.c} also provides an
2067implementation of it which outputs PostScript. Thus, any platform
2068which wants to do PS printing can do so with minimum fuss.)
2069
2070The following entries all describe function pointer fields in a
2071structure called \c{drawing_api}. Each of the functions takes a
2072\cq{void *} context pointer, which it should internally cast back to
2073a more useful type. Thus, a drawing \e{object} (\c{drawing *)}
2074suitable for passing to the back end redraw or printing functions
2075is constructed by passing a \c{drawing_api} and a \cq{void *} to the
83c0438f 2076function \cw{drawing_new()} (see \k{drawing-new}).
dafd6cf6 2077
2078\S{drawingapi-draw-text} \cw{draw_text()}
2079
2080\c void (*draw_text)(void *handle, int x, int y, int fonttype,
2081\c int fontsize, int align, int colour, char *text);
2082
2083This function behaves exactly like the back end \cw{draw_text()}
2084function; see \k{drawing-draw-text}.
2085
2086\S{drawingapi-draw-rect} \cw{draw_rect()}
2087
2088\c void (*draw_rect)(void *handle, int x, int y, int w, int h,
2089\c int colour);
2090
2091This function behaves exactly like the back end \cw{draw_rect()}
2092function; see \k{drawing-draw-rect}.
2093
2094\S{drawingapi-draw-line} \cw{draw_line()}
2095
2096\c void (*draw_line)(void *handle, int x1, int y1, int x2, int y2,
2097\c int colour);
2098
2099This function behaves exactly like the back end \cw{draw_line()}
2100function; see \k{drawing-draw-line}.
2101
2102\S{drawingapi-draw-polygon} \cw{draw_polygon()}
2103
2104\c void (*draw_polygon)(void *handle, int *coords, int npoints,
2105\c int fillcolour, int outlinecolour);
2106
2107This function behaves exactly like the back end \cw{draw_polygon()}
2108function; see \k{drawing-draw-polygon}.
2109
2110\S{drawingapi-draw-circle} \cw{draw_circle()}
2111
2112\c void (*draw_circle)(void *handle, int cx, int cy, int radius,
2113\c int fillcolour, int outlinecolour);
2114
2115This function behaves exactly like the back end \cw{draw_circle()}
2116function; see \k{drawing-draw-circle}.
2117
2118\S{drawingapi-draw-update} \cw{draw_update()}
2119
2120\c void (*draw_update)(void *handle, int x, int y, int w, int h);
2121
2122This function behaves exactly like the back end \cw{draw_text()}
2123function; see \k{drawing-draw-text}.
2124
2125An implementation of this API which only supports printing is
2126permitted to define this function pointer to be \cw{NULL} rather
2127than bothering to define an empty function. The middleware in
2128\cw{drawing.c} will notice and avoid calling it.
2129
2130\S{drawingapi-clip} \cw{clip()}
2131
2132\c void (*clip)(void *handle, int x, int y, int w, int h);
69491f1e 2133
dafd6cf6 2134This function behaves exactly like the back end \cw{clip()}
2135function; see \k{drawing-clip}.
69491f1e 2136
dafd6cf6 2137\S{drawingapi-unclip} \cw{unclip()}
69491f1e 2138
dafd6cf6 2139\c void (*unclip)(void *handle);
69491f1e 2140
dafd6cf6 2141This function behaves exactly like the back end \cw{unclip()}
2142function; see \k{drawing-unclip}.
69491f1e 2143
dafd6cf6 2144\S{drawingapi-start-draw} \cw{start_draw()}
69491f1e 2145
dafd6cf6 2146\c void (*start_draw)(void *handle);
2147
2148This function is called at the start of drawing. It allows the front
2149end to initialise any temporary data required to draw with, such as
2150device contexts.
2151
2152Implementations of this API which do not provide drawing services
2153may define this function pointer to be \cw{NULL}; it will never be
2154called unless drawing is attempted.
2155
2156\S{drawingapi-end-draw} \cw{end_draw()}
2157
2158\c void (*end_draw)(void *handle);
69491f1e 2159
2160This function is called at the end of drawing. It allows the front
2161end to do cleanup tasks such as deallocating device contexts and
2162scheduling appropriate GUI redraw events.
2163
dafd6cf6 2164Implementations of this API which do not provide drawing services
2165may define this function pointer to be \cw{NULL}; it will never be
2166called unless drawing is attempted.
69491f1e 2167
dafd6cf6 2168\S{drawingapi-status-bar} \cw{status_bar()}
69491f1e 2169
dafd6cf6 2170\c void (*status_bar)(void *handle, char *text);
69491f1e 2171
dafd6cf6 2172This function behaves exactly like the back end \cw{status_bar()}
2173function; see \k{drawing-status-bar}.
2174
83c0438f 2175Front ends implementing this function need not worry about it being
2176called repeatedly with the same text; the middleware code in
2177\cw{status_bar()} will take care of this.
dafd6cf6 2178
2179Implementations of this API which do not provide drawing services
2180may define this function pointer to be \cw{NULL}; it will never be
2181called unless drawing is attempted.
2182
2183\S{drawingapi-blitter-new} \cw{blitter_new()}
2184
2185\c blitter *(*blitter_new)(void *handle, int w, int h);
2186
2187This function behaves exactly like the back end \cw{blitter_new()}
2188function; see \k{drawing-blitter-new}.
2189
2190Implementations of this API which do not provide drawing services
2191may define this function pointer to be \cw{NULL}; it will never be
2192called unless drawing is attempted.
2193
2194\S{drawingapi-blitter-free} \cw{blitter_free()}
2195
2196\c void (*blitter_free)(void *handle, blitter *bl);
2197
2198This function behaves exactly like the back end \cw{blitter_free()}
2199function; see \k{drawing-blitter-free}.
2200
2201Implementations of this API which do not provide drawing services
2202may define this function pointer to be \cw{NULL}; it will never be
2203called unless drawing is attempted.
2204
2205\S{drawingapi-blitter-save} \cw{blitter_save()}
2206
2207\c void (*blitter_save)(void *handle, blitter *bl, int x, int y);
2208
2209This function behaves exactly like the back end \cw{blitter_save()}
2210function; see \k{drawing-blitter-save}.
2211
2212Implementations of this API which do not provide drawing services
2213may define this function pointer to be \cw{NULL}; it will never be
2214called unless drawing is attempted.
2215
2216\S{drawingapi-blitter-load} \cw{blitter_load()}
2217
2218\c void (*blitter_load)(void *handle, blitter *bl, int x, int y);
2219
2220This function behaves exactly like the back end \cw{blitter_load()}
2221function; see \k{drawing-blitter-load}.
2222
2223Implementations of this API which do not provide drawing services
2224may define this function pointer to be \cw{NULL}; it will never be
2225called unless drawing is attempted.
2226
2227\S{drawingapi-begin-doc} \cw{begin_doc()}
2228
2229\c void (*begin_doc)(void *handle, int pages);
2230
2231This function is called at the beginning of a printing run. It gives
2232the front end an opportunity to initialise any required printing
2233subsystem. It also provides the number of pages in advance.
2234
2235Implementations of this API which do not provide printing services
2236may define this function pointer to be \cw{NULL}; it will never be
2237called unless printing is attempted.
2238
2239\S{drawingapi-begin-page} \cw{begin_page()}
2240
2241\c void (*begin_page)(void *handle, int number);
2242
2243This function is called during printing, at the beginning of each
2244page. It gives the page number (numbered from 1 rather than 0, so
2245suitable for use in user-visible contexts).
2246
2247Implementations of this API which do not provide printing services
2248may define this function pointer to be \cw{NULL}; it will never be
2249called unless printing is attempted.
2250
2251\S{drawingapi-begin-puzzle} \cw{begin_puzzle()}
2252
2253\c void (*begin_puzzle)(void *handle, float xm, float xc,
2254\c float ym, float yc, int pw, int ph, float wmm);
2255
2256This function is called during printing, just before printing a
2257single puzzle on a page. It specifies the size and location of the
2258puzzle on the page.
2259
2260\c{xm} and \c{xc} specify the horizontal position of the puzzle on
2261the page, as a linear function of the page width. The front end is
2262expected to multiply the page width by \c{xm}, add \c{xc} (measured
2263in millimetres), and use the resulting x-coordinate as the left edge
2264of the puzzle.
2265
2266Similarly, \c{ym} and \c{yc} specify the vertical position of the
2267puzzle as a function of the page height: the page height times
2268\c{xm}, plus \c{xc} millimetres, equals the desired distance from
2269the top of the page to the top of the puzzle.
2270
2271(This unwieldy mechanism is required because not all printing
2272systems can communicate the page size back to the software. The
2273PostScript back end, for example, writes out PS which determines the
2274page size at print time by means of calling \cq{clippath}, and
2275centres the puzzles within that. Thus, exactly the same PS file
2276works on A4 or on US Letter paper without needing local
2277configuration, which simplifies matters.)
2278
2279\cw{pw} and \cw{ph} give the size of the puzzle in drawing API
2280coordinates. The printing system will subsequently call the puzzle's
2281own print function, which will in turn call drawing API functions in
2282the expectation that an area \cw{pw} by \cw{ph} units is available
2283to draw the puzzle on.
2284
2285Finally, \cw{wmm} gives the desired width of the puzzle in
2286millimetres. (The aspect ratio is expected to be preserved, so if
2287the desired puzzle height is also needed then it can be computed as
2288\cw{wmm*ph/pw}.)
2289
2290Implementations of this API which do not provide printing services
2291may define this function pointer to be \cw{NULL}; it will never be
2292called unless printing is attempted.
2293
2294\S{drawingapi-end-puzzle} \cw{end_puzzle()}
2295
2296\c void (*end_puzzle)(void *handle);
2297
2298This function is called after the printing of a specific puzzle is
2299complete.
2300
2301Implementations of this API which do not provide printing services
2302may define this function pointer to be \cw{NULL}; it will never be
2303called unless printing is attempted.
2304
2305\S{drawingapi-end-page} \cw{end_page()}
2306
2307\c void (*end_page)(void *handle, int number);
2308
2309This function is called after the printing of a page is finished.
2310
2311Implementations of this API which do not provide printing services
2312may define this function pointer to be \cw{NULL}; it will never be
2313called unless printing is attempted.
2314
2315\S{drawingapi-end-doc} \cw{end_doc()}
2316
2317\c void (*end_doc)(void *handle);
2318
2319This function is called after the printing of the entire document is
2320finished. This is the moment to close files, send things to the
2321print spooler, or whatever the local convention is.
2322
2323Implementations of this API which do not provide printing services
2324may define this function pointer to be \cw{NULL}; it will never be
2325called unless printing is attempted.
2326
2327\S{drawingapi-line-width} \cw{line_width()}
2328
2329\c void (*line_width)(void *handle, float width);
2330
2331This function is called to set the line thickness, during printing
2332only. Note that the width is a \cw{float} here, where it was an
2333\cw{int} as seen by the back end. This is because \cw{drawing.c} may
2334have scaled it on the way past.
2335
2336However, the width is still specified in the same coordinate system
2337as the rest of the drawing.
2338
2339Implementations of this API which do not provide printing services
2340may define this function pointer to be \cw{NULL}; it will never be
2341called unless printing is attempted.
2342
2343\H{drawingapi-frontend} The drawing API as called by the front end
2344
2345There are a small number of functions provided in \cw{drawing.c}
2346which the front end needs to \e{call}, rather than helping to
2347implement. They are described in this section.
2348
83c0438f 2349\S{drawing-new} \cw{drawing_new()}
dafd6cf6 2350
83c0438f 2351\c drawing *drawing_new(const drawing_api *api, midend *me,
2352\c void *handle);
dafd6cf6 2353
2354This function creates a drawing object. It is passed a
2355\c{drawing_api}, which is a structure containing nothing but
2356function pointers; and also a \cq{void *} handle. The handle is
2357passed back to each function pointer when it is called.
2358
83c0438f 2359The \c{midend} parameter is used for rewriting the status bar
2360contents: \cw{status_bar()} (see \k{drawing-status-bar}) has to call
2361a function in the mid-end which might rewrite the status bar text.
2362If the drawing object is to be used only for printing, or if the
2363game is known not to call \cw{status_bar()}, this parameter may be
2364\cw{NULL}.
2365
dafd6cf6 2366\S{drawing-free} \cw{drawing_free()}
2367
2368\c void drawing_free(drawing *dr);
2369
2370This function frees a drawing object. Note that the \cq{void *}
2371handle is not freed; if that needs cleaning up it must be done by
2372the front end.
2373
2374\S{drawing-print-get-colour} \cw{print_get_colour()}
2375
2376\c void print_get_colour(drawing *dr, int colour, int *hatch,
2377\c float *r, float *g, float *b)
2378
2379This function is called by the implementations of the drawing API
2380functions when they are called in a printing context. It takes a
2381colour index as input, and returns the description of the colour as
2382requested by the back end.
2383
2384\c{*r}, \c{*g} and \c{*b} are filled with the RGB values of the
2385desired colour if printing in colour.
2386
2387\c{*hatch} is filled with the type of hatching (or not) desired if
2388printing in black and white. See \k{print-grey-colour} for details
2389of the values this integer can take.
69491f1e 2390
2391\C{midend} The API provided by the mid-end
2392
2393This chapter documents the API provided by the mid-end to be called
2394by the front end. You probably only need to read this if you are a
2395front end implementor, i.e. you are porting Puzzles to a new
2396platform. If you're only interested in writing new puzzles, you can
2397safely skip this chapter.
2398
2399All the persistent state in the mid-end is encapsulated within a
dafd6cf6 2400\c{midend} structure, to facilitate having multiple mid-ends in any
2401port which supports multiple puzzle windows open simultaneously.
2402Each \c{midend} is intended to handle the contents of a single
69491f1e 2403puzzle window.
2404
2405\H{midend-new} \cw{midend_new()}
2406
dafd6cf6 2407\c midend *midend_new(frontend *fe, const game *ourgame,
2408\c const drawing_api *drapi, void *drhandle)
69491f1e 2409
2410Allocates and returns a new mid-end structure.
2411
2412The \c{fe} argument is stored in the mid-end. It will be used when
2413calling back to functions such as \cw{activate_timer()}
dafd6cf6 2414(\k{frontend-activate-timer}), and will be passed on to the back end
2415function \cw{colours()} (\k{backend-colours}).
2416
2417The parameters \c{drapi} and \c{drhandle} are passed to
83c0438f 2418\cw{drawing_new()} (\k{drawing-new}) to construct a drawing object
dafd6cf6 2419which will be passed to the back end function \cw{redraw()}
2420(\k{backend-redraw}). Hence, all drawing-related function pointers
2421defined in \c{drapi} can expect to be called with \c{drhandle} as
2422their first argument.
69491f1e 2423
2424The \c{ourgame} argument points to a container structure describing
2425a game back end. The mid-end thus created will only be capable of
2426handling that one game. (So even in a monolithic front end
2427containing all the games, this imposes the constraint that any
2428individual puzzle window is tied to a single game. Unless, of
2429course, you feel brave enough to change the mid-end for the window
2430without closing the window...)
2431
2432\H{midend-free} \cw{midend_free()}
2433
dafd6cf6 2434\c void midend_free(midend *me);
69491f1e 2435
2436Frees a mid-end structure and all its associated data.
2437
2438\H{midend-set-params} \cw{midend_set_params()}
2439
dafd6cf6 2440\c void midend_set_params(midend *me, game_params *params);
69491f1e 2441
2442Sets the current game parameters for a mid-end. Subsequent games
2443generated by \cw{midend_new_game()} (\k{midend-new-game}) will use
2444these parameters until further notice.
2445
2446The usual way in which the front end will have an actual
2447\c{game_params} structure to pass to this function is if it had
2448previously got it from \cw{midend_fetch_preset()}
2449(\k{midend-fetch-preset}). Thus, this function is usually called in
2450response to the user making a selection from the presets menu.
2451
821ab2c6 2452\H{midend-get-params} \cw{midend_get_params()}
2453
2454\c game_params *midend_get_params(midend *me);
2455
2456Returns the current game parameters stored in this mid-end.
2457
2458The returned value is dynamically allocated, and should be freed
2459when finished with by passing it to the game's own
2460\cw{free_params()} function (see \k{backend-free-params}).
2461
69491f1e 2462\H{midend-size} \cw{midend_size()}
2463
dafd6cf6 2464\c void midend_size(midend *me, int *x, int *y, int expand);
69491f1e 2465
2466Tells the mid-end to figure out its window size.
2467
2468On input, \c{*x} and \c{*y} should contain the maximum or requested
2469size for the window. (Typically this will be the size of the screen
2470that the window has to fit on, or similar.) The mid-end will
2471repeatedly call the back end function \cw{compute_size()}
2472(\k{backend-compute-size}), searching for a tile size that best
2473satisfies the requirements. On exit, \c{*x} and \c{*y} will contain
2474the size needed for the puzzle window's drawing area. (It is of
2475course up to the front end to adjust this for any additional window
2476furniture such as menu bars and window borders, if necessary. The
2477status bar is also not included in this size.)
2478
2479If \c{expand} is set to \cw{FALSE}, then the game's tile size will
2480never go over its preferred one. This is the recommended approach
2481when opening a new window at default size: the game will use its
2482preferred size unless it has to use a smaller one to fit on the
2483screen.
2484
2485If \c{expand} is set to \cw{TRUE}, the mid-end will pick a tile size
2486which approximates the input size \e{as closely as possible}, and
2487will go over the game's preferred tile size if necessary to achieve
2488this. Use this option if you want your front end to support dynamic
2489resizing of the puzzle window with automatic scaling of the puzzle
2490to fit.
2491
2492The mid-end will try as hard as it can to return a size which is
2493less than or equal to the input size, in both dimensions. In extreme
2494circumstances it may fail (if even the lowest possible tile size
2495gives window dimensions greater than the input), in which case it
2496will return a size greater than the input size. Front ends should be
2497prepared for this to happen (i.e. don't crash or fail an assertion),
2498but may handle it in any way they see fit: by rejecting the game
2499parameters which caused the problem, by opening a window larger than
2500the screen regardless of inconvenience, by introducing scroll bars
2501on the window, by drawing on a large bitmap and scaling it into a
2502smaller window, or by any other means you can think of. It is likely
2503that when the tile size is that small the game will be unplayable
2504anyway, so don't put \e{too} much effort into handling it
2505creatively.
2506
2507If your platform has no limit on window size (or if you're planning
2508to use scroll bars for large puzzles), you can pass dimensions of
2509\cw{INT_MAX} as input to this function. You should probably not do
2510that \e{and} set the \c{expand} flag, though!
2511
2512\H{midend-new-game} \cw{midend_new_game()}
2513
dafd6cf6 2514\c void midend_new_game(midend *me);
69491f1e 2515
2516Causes the mid-end to begin a new game. Normally the game will be a
2517new randomly generated puzzle. However, if you have previously
2518called \cw{midend_game_id()} or \cw{midend_set_config()}, the game
2519generated might be dictated by the results of those functions. (In
2520particular, you \e{must} call \cw{midend_new_game()} after calling
2521either of those functions, or else no immediate effect will be
2522visible.)
2523
2524You will probably need to call \cw{midend_size()} after calling this
2525function, because if the game parameters have been changed since the
2526last new game then the window size might need to change. (If you
2527know the parameters \e{haven't} changed, you don't need to do this.)
2528
2529This function will create a new \c{game_drawstate}, but does not
2530actually perform a redraw (since you often need to call
2531\cw{midend_size()} before the redraw can be done). So after calling
2532this function and after calling \cw{midend_size()}, you should then
2533call \cw{midend_redraw()}. (It is not necessary to call
2534\cw{midend_force_redraw()}; that will discard the draw state and
2535create a fresh one, which is unnecessary in this case since there's
2536a fresh one already. It would work, but it's usually excessive.)
2537
2538\H{midend-restart-game} \cw{midend_restart_game()}
2539
dafd6cf6 2540\c void midend_restart_game(midend *me);
69491f1e 2541
2542This function causes the current game to be restarted. This is done
2543by placing a new copy of the original game state on the end of the
2544undo list (so that an accidental restart can be undone).
2545
2546This function automatically causes a redraw, i.e. the front end can
2547expect its drawing API to be called from \e{within} a call to this
2548function.
2549
2550\H{midend-force-redraw} \cw{midend_force_redraw()}
2551
dafd6cf6 2552\c void midend_force_redraw(midend *me);
69491f1e 2553
2554Forces a complete redraw of the puzzle window, by means of
2555discarding the current \c{game_drawstate} and creating a new one
2556from scratch before calling the game's \cw{redraw()} function.
2557
2558The front end can expect its drawing API to be called from within a
2559call to this function.
2560
2561\H{midend-redraw} \cw{midend_redraw()}
2562
dafd6cf6 2563\c void midend_redraw(midend *me);
69491f1e 2564
2565Causes a partial redraw of the puzzle window, by means of simply
2566calling the game's \cw{redraw()} function. (That is, the only things
2567redrawn will be things that have changed since the last redraw.)
2568
2569The front end can expect its drawing API to be called from within a
2570call to this function.
2571
2572\H{midend-process-key} \cw{midend_process_key()}
2573
dafd6cf6 2574\c int midend_process_key(midend *me, int x, int y, int button);
69491f1e 2575
2576The front end calls this function to report a mouse or keyboard
2577event. The parameters \c{x}, \c{y} and \c{button} are almost
2578identical to the ones passed to the back end function
2579\cw{interpret_move()} (\k{backend-interpret-move}), except that the
2580front end is \e{not} required to provide the guarantees about mouse
2581event ordering. The mid-end will sort out multiple simultaneous
2582button presses and changes of button; the front end's responsibility
2583is simply to pass on the mouse events it receives as accurately as
2584possible.
2585
2586(Some platforms may need to emulate absent mouse buttons by means of
2587using a modifier key such as Shift with another mouse button. This
2588tends to mean that if Shift is pressed or released in the middle of
2589a mouse drag, the mid-end will suddenly stop receiving, say,
2590\cw{LEFT_DRAG} events and start receiving \cw{RIGHT_DRAG}s, with no
2591intervening button release or press events. This too is something
2592which the mid-end will sort out for you; the front end has no
2593obligation to maintain sanity in this area.)
2594
2595The front end \e{should}, however, always eventually send some kind
2596of button release. On some platforms this requires special effort:
2597Windows, for example, requires a call to the system API function
2598\cw{SetCapture()} in order to ensure that your window receives a
2599mouse-up event even if the pointer has left the window by the time
2600the mouse button is released. On any platform that requires this
2601sort of thing, the front end \e{is} responsible for doing it.
2602
2603Calling this function is very likely to result in calls back to the
2604front end's drawing API and/or \cw{activate_timer()}
2605(\k{frontend-activate-timer}).
2606
2607\H{midend-colours} \cw{midend_colours()}
2608
dafd6cf6 2609\c float *midend_colours(midend *me, int *ncolours);
69491f1e 2610
2611Returns an array of the colours required by the game, in exactly the
2612same format as that returned by the back end function \cw{colours()}
2613(\k{backend-colours}). Front ends should call this function rather
2614than calling the back end's version directly, since the mid-end adds
2615standard customisation facilities. (At the time of writing, those
2616customisation facilities are implemented hackily by means of
2617environment variables, but it's not impossible that they may become
2618more full and formal in future.)
2619
2620\H{midend-timer} \cw{midend_timer()}
2621
dafd6cf6 2622\c void midend_timer(midend *me, float tplus);
69491f1e 2623
2624If the mid-end has called \cw{activate_timer()}
2625(\k{frontend-activate-timer}) to request regular callbacks for
2626purposes of animation or timing, this is the function the front end
2627should call on a regular basis. The argument \c{tplus} gives the
2628time, in seconds, since the last time either this function was
2629called or \cw{activate_timer()} was invoked.
2630
2631One of the major purposes of timing in the mid-end is to perform
2632move animation. Therefore, calling this function is very likely to
2633result in calls back to the front end's drawing API.
2634
2635\H{midend-num-presets} \cw{midend_num_presets()}
2636
dafd6cf6 2637\c int midend_num_presets(midend *me);
69491f1e 2638
2639Returns the number of game parameter presets supplied by this game.
2640Front ends should use this function and \cw{midend_fetch_preset()}
2641to configure their presets menu rather than calling the back end
2642directly, since the mid-end adds standard customisation facilities.
2643(At the time of writing, those customisation facilities are
2644implemented hackily by means of environment variables, but it's not
2645impossible that they may become more full and formal in future.)
2646
2647\H{midend-fetch-preset} \cw{midend_fetch_preset()}
2648
dafd6cf6 2649\c void midend_fetch_preset(midend *me, int n,
69491f1e 2650\c char **name, game_params **params);
2651
2652Returns one of the preset game parameter structures for the game. On
2653input \c{n} must be a non-negative integer and less than the value
2654returned from \cw{midend_num_presets()}. On output, \c{*name} is set
2655to an ASCII string suitable for entering in the game's presets menu,
2656and \c{*params} is set to the corresponding \c{game_params}
2657structure.
2658
2659Both of the two output values are dynamically allocated, but they
2660are owned by the mid-end structure: the front end should not ever
2661free them directly, because they will be freed automatically during
2662\cw{midend_free()}.
2663
2664\H{midend-wants-statusbar} \cw{midend_wants_statusbar()}
2665
dafd6cf6 2666\c int midend_wants_statusbar(midend *me);
69491f1e 2667
2668This function returns \cw{TRUE} if the puzzle has a use for a
2669textual status line (to display score, completion status, currently
2670active tiles, time, or anything else).
2671
2672Front ends should call this function rather than talking directly to
2673the back end.
2674
2675\H{midend-get-config} \cw{midend_get_config()}
2676
dafd6cf6 2677\c config_item *midend_get_config(midend *me, int which,
69491f1e 2678\c char **wintitle);
2679
2680Returns a dialog box description for user configuration.
2681
2682On input, \cw{which} should be set to one of three values, which
2683select which of the various dialog box descriptions is returned:
2684
2685\dt \cw{CFG_SETTINGS}
2686
2687\dd Requests the GUI parameter configuration box generated by the
2688puzzle itself. This should be used when the user selects \q{Custom}
2689from the game types menu (or equivalent). The mid-end passes this
2690request on to the back end function \cw{configure()}
2691(\k{backend-configure}).
2692
2693\dt \cw{CFG_DESC}
2694
2695\dd Requests a box suitable for entering a descriptive game ID (and
2696viewing the existing one). The mid-end generates this dialog box
2697description itself. This should be used when the user selects
2698\q{Specific} from the game menu (or equivalent).
2699
2700\dt \cw{CFG_SEED}
2701
2702\dd Requests a box suitable for entering a random-seed game ID (and
2703viewing the existing one). The mid-end generates this dialog box
2704description itself. This should be used when the user selects
2705\q{Random Seed} from the game menu (or equivalent).
2706
2707The returned value is an array of \cw{config_item}s, exactly as
2708described in \k{backend-configure}. Another returned value is an
2709ASCII string giving a suitable title for the configuration window,
2710in \c{*wintitle}.
2711
2712Both returned values are dynamically allocated and will need to be
2713freed. The window title can be freed in the obvious way; the
2714\cw{config_item} array is a slightly complex structure, so a utility
2715function \cw{free_cfg()} is provided to free it for you. See
2716\k{utils-free-cfg}.
2717
2718(Of course, you will probably not want to free the \cw{config_item}
2719array until the dialog box is dismissed, because before then you
2720will probably need to pass it to \cw{midend_set_config}.)
2721
2722\H{midend-set-config} \cw{midend_set_config()}
2723
dafd6cf6 2724\c char *midend_set_config(midend *me, int which,
69491f1e 2725\c config_item *cfg);
2726
2727Passes the mid-end the results of a configuration dialog box.
2728\c{which} should have the same value which it had when
2729\cw{midend_get_config()} was called; \c{cfg} should be the array of
2730\c{config_item}s returned from \cw{midend_get_config()}, modified to
2731contain the results of the user's editing operations.
2732
2733This function returns \cw{NULL} on success, or otherwise (if the
2734configuration data was in some way invalid) an ASCII string
2735containing an error message suitable for showing to the user.
2736
2737If the function succeeds, it is likely that the game parameters will
2738have been changed and it is certain that a new game will be
2739requested. The front end should therefore call
2740\cw{midend_new_game()}, and probably also re-think the window size
2741using \cw{midend_size()} and eventually perform a refresh using
2742\cw{midend_redraw()}.
2743
2744\H{midend-game-id} \cw{midend_game_id()}
2745
dafd6cf6 2746\c char *midend_game_id(midend *me, char *id);
69491f1e 2747
2748Passes the mid-end a string game ID (of any of the valid forms
2749\cq{params}, \cq{params:description} or \cq{params#seed}) which the
2750mid-end will process and use for the next generated game.
2751
2752This function returns \cw{NULL} on success, or otherwise (if the
2753configuration data was in some way invalid) an ASCII string
2754containing an error message (not dynamically allocated) suitable for
2755showing to the user. In the event of an error, the mid-end's
2756internal state will be left exactly as it was before the call.
2757
2758If the function succeeds, it is likely that the game parameters will
2759have been changed and it is certain that a new game will be
2760requested. The front end should therefore call
2761\cw{midend_new_game()}, and probably also re-think the window size
2762using \cw{midend_size()} and eventually case a refresh using
2763\cw{midend_redraw()}.
2764
dafd6cf6 2765\H{midend-get-game-id} \cw{midend_get_game_id()}
2766
2767\c char *midend_get_game_id(midend *me)
2768
2769Returns a descriptive game ID (i.e. one in the form
2770\cq{params:description}) describing the game currently active in the
2771mid-end. The returned string is dynamically allocated.
2772
69491f1e 2773\H{midend-text-format} \cw{midend_text_format()}
2774
dafd6cf6 2775\c char *midend_text_format(midend *me);
69491f1e 2776
2777Formats the current game's current state as ASCII text suitable for
2778copying to the clipboard. The returned string is dynamically
2779allocated.
2780
2781You should not call this function if the game's
2782\c{can_format_as_text} flag is \cw{FALSE}.
2783
2784If the returned string contains multiple lines (which is likely), it
2785will use the normal C line ending convention (\cw{\\n} only). On
2786platforms which use a different line ending convention for data in
2787the clipboard, it is the front end's responsibility to perform the
2788conversion.
2789
2790\H{midend-solve} \cw{midend_solve()}
2791
dafd6cf6 2792\c char *midend_solve(midend *me);
69491f1e 2793
2794Requests the mid-end to perform a Solve operation.
2795
2796On success, \cw{NULL} is returned. On failure, an error message (not
2797dynamically allocated) is returned, suitable for showing to the
2798user.
2799
2800The front end can expect its drawing API and/or
2801\cw{activate_timer()} to be called from within a call to this
2802function.
2803
69491f1e 2804\H{midend-serialise} \cw{midend_serialise()}
2805
dafd6cf6 2806\c void midend_serialise(midend *me,
69491f1e 2807\c void (*write)(void *ctx, void *buf, int len),
2808\c void *wctx);
2809
2810Calling this function causes the mid-end to convert its entire
2811internal state into a long ASCII text string, and to pass that
2812string (piece by piece) to the supplied \c{write} function.
2813
2814Desktop implementations can use this function to save a game in any
2815state (including half-finished) to a disk file, by supplying a
2816\c{write} function which is a wrapper on \cw{fwrite()} (or local
2817equivalent). Other implementations may find other uses for it, such
2818as compressing the large and sprawling mid-end state into a
2819manageable amount of memory when a palmtop application is suspended
2820so that another one can run; in this case \cw{write} might want to
2821write to a memory buffer rather than a file. There may be other uses
2822for it as well.
2823
2824This function will call back to the supplied \c{write} function a
2825number of times, with the first parameter (\c{ctx}) equal to
2826\c{wctx}, and the other two parameters pointing at a piece of the
2827output string.
2828
2829\H{midend-deserialise} \cw{midend_deserialise()}
2830
dafd6cf6 2831\c char *midend_deserialise(midend *me,
69491f1e 2832\c int (*read)(void *ctx, void *buf, int len),
2833\c void *rctx);
2834
2835This function is the counterpart to \cw{midend_serialise()}. It
2836calls the supplied \cw{read} function repeatedly to read a quantity
2837of data, and attempts to interpret that data as a serialised mid-end
2838as output by \cw{midend_serialise()}.
2839
2840The \cw{read} function is called with the first parameter (\c{ctx})
2841equal to \c{rctx}, and should attempt to read \c{len} bytes of data
2842into the buffer pointed to by \c{buf}. It should return \cw{FALSE}
2843on failure or \cw{TRUE} on success. It should not report success
2844unless it has filled the entire buffer; on platforms which might be
2845reading from a pipe or other blocking data source, \c{read} is
2846responsible for looping until the whole buffer has been filled.
2847
2848If the de-serialisation operation is successful, the mid-end's
2849internal data structures will be replaced by the results of the
2850load, and \cw{NULL} will be returned. Otherwise, the mid-end's state
2851will be completely unchanged and an error message (typically some
2852variation on \q{save file is corrupt}) will be returned. As usual,
2853the error message string is not dynamically allocated.
2854
2855If this function succeeds, it is likely that the game parameters
2856will have been changed. The front end should therefore probably
2857re-think the window size using \cw{midend_size()}, and probably
2858cause a refresh using \cw{midend_redraw()}.
2859
2860Because each mid-end is tied to a specific game back end, this
2861function will fail if you attempt to read in a save file generated
2862by a different game from the one configured in this mid-end, even if
2863your application is a monolithic one containing all the puzzles. (It
2864would be pretty easy to write a function which would look at a save
2865file and determine which game it was for; any front end implementor
2866who needs such a function can probably be accommodated.)
2867
2868\H{frontend-backend} Direct reference to the back end structure by
2869the front end
2870
2871Although \e{most} things the front end needs done should be done by
2872calling the mid-end, there are a few situations in which the front
2873end needs to refer directly to the game back end structure.
2874
2875The most obvious of these is
2876
2877\b passing the game back end as a parameter to \cw{midend_new()}.
2878
2879There are a few other back end features which are not wrapped by the
2880mid-end because there didn't seem much point in doing so:
2881
2882\b fetching the \c{name} field to use in window titles and similar
2883
2884\b reading the \c{can_configure}, \c{can_solve} and
2885\c{can_format_as_text} fields to decide whether to add those items
2886to the menu bar or equivalent
2887
2888\b reading the \c{winhelp_topic} field (Windows only)
2889
2890\b the GTK front end provides a \cq{--generate} command-line option
2891which directly calls the back end to do most of its work. This is
2892not really part of the main front end code, though, and I'm not sure
2893it counts.
2894
2895In order to find the game back end structure, the front end does one
2896of two things:
2897
2898\b If the particular front end is compiling a separate binary per
2899game, then the back end structure is a global variable with the
2900standard name \cq{thegame}:
2901
2902\lcont{
2903
2904\c extern const game thegame;
2905
2906}
2907
2908\b If the front end is compiled as a monolithic application
2909containing all the puzzles together (in which case the preprocessor
2910symbol \cw{COMBINED} must be defined when compiling most of the code
2911base), then there will be two global variables defined:
2912
2913\lcont{
2914
2915\c extern const game *gamelist[];
2916\c extern const int gamecount;
2917
2918\c{gamelist} will be an array of \c{gamecount} game structures,
2919declared in the source module \c{list.c}. The application should
2920search that array for the game it wants, probably by reaching into
2921each game structure and looking at its \c{name} field.
2922
2923}
2924
2925\H{frontend-api} Mid-end to front-end calls
2926
2927This section describes the small number of functions which a front
2928end must provide to be called by the mid-end or other standard
2929utility modules.
2930
2931\H{frontend-get-random-seed} \cw{get_random_seed()}
2932
2933\c void get_random_seed(void **randseed, int *randseedsize);
2934
2935This function is called by a new mid-end, and also occasionally by
2936game back ends. Its job is to return a piece of data suitable for
2937using as a seed for initialisation of a new \c{random_state}.
2938
2939On exit, \c{*randseed} should be set to point at a newly allocated
2940piece of memory containing some seed data, and \c{*randseedsize}
2941should be set to the length of that data.
2942
2943A simple and entirely adequate implementation is to return a piece
2944of data containing the current system time at the highest
2945conveniently available resolution.
2946
2947\H{frontend-activate-timer} \cw{activate_timer()}
2948
2949\c void activate_timer(frontend *fe);
2950
2951This is called by the mid-end to request that the front end begin
2952calling it back at regular intervals.
2953
2954The timeout interval is left up to the front end; the finer it is,
2955the smoother move animations will be, but the more CPU time will be
2956used. Current front ends use values around 20ms (i.e. 50Hz).
2957
2958After this function is called, the mid-end will expect to receive
2959calls to \cw{midend_timer()} on a regular basis.
2960
2961\H{frontend-deactivate-timer} \cw{deactivate_timer()}
2962
2963\c void deactivate_timer(frontend *fe);
2964
2965This is called by the mid-end to request that the front end stop
2966calling \cw{midend_timer()}.
2967
2968\H{frontend-fatal} \cw{fatal()}
2969
2970\c void fatal(char *fmt, ...);
2971
2972This is called by some utility functions if they encounter a
2973genuinely fatal error such as running out of memory. It is a
2974variadic function in the style of \cw{printf()}, and is expected to
2975show the formatted error message to the user any way it can and then
2976terminate the application. It must not return.
2977
dafd6cf6 2978\H{frontend-default-colour} \cw{frontend_default_colour()}
2979
2980\c void frontend_default_colour(frontend *fe, float *output);
2981
2982This function expects to be passed a pointer to an array of three
2983\cw{float}s. It returns the platform's local preferred background
2984colour in those three floats, as red, green and blue values (in that
2985order) ranging from \cw{0.0} to \cw{1.0}.
2986
2987This function should only ever be called by the back end function
2988\cw{colours()} (\k{backend-colours}). (Thus, it isn't a
2989\e{midend}-to-frontend function as such, but there didn't seem to be
2990anywhere else particularly good to put it. Sorry.)
2991
69491f1e 2992\C{utils} Utility APIs
2993
2994This chapter documents a variety of utility APIs provided for the
2995general use of the rest of the Puzzles code.
2996
2997\H{utils-random} Random number generation
2998
2999Platforms' local random number generators vary widely in quality and
3000seed size. Puzzles therefore supplies its own high-quality random
3001number generator, with the additional advantage of giving the same
3002results if fed the same seed data on different platforms. This
3003allows game random seeds to be exchanged between different ports of
3004Puzzles and still generate the same games.
3005
3006Unlike the ANSI C \cw{rand()} function, the Puzzles random number
3007generator has an \e{explicit} state object called a
3008\c{random_state}. One of these is managed by each mid-end, for
3009example, and passed to the back end to generate a game with.
3010
1fbb0680 3011\S{utils-random-init} \cw{random_new()}
69491f1e 3012
1fbb0680 3013\c random_state *random_new(char *seed, int len);
69491f1e 3014
3015Allocates, initialises and returns a new \c{random_state}. The input
3016data is used as the seed for the random number stream (i.e. using
3017the same seed at a later time will generate the same stream).
3018
3019The seed data can be any data at all; there is no requirement to use
3020printable ASCII, or NUL-terminated strings, or anything like that.
3021
e9f8a17f 3022\S{utils-random-copy} \cw{random_copy()}
3023
3024\c random_state *random_copy(random_state *tocopy);
3025
3026Allocates a new \c{random_state}, copies the contents of another
3027\c{random_state} into it, and returns the new state. If exactly the
3028same sequence of functions is subseqently called on both the copy and
3029the original, the results will be identical. This may be useful for
3030speculatively performing some operation using a given random state,
3031and later replaying that operation precisely.
3032
69491f1e 3033\S{utils-random-free} \cw{random_free()}
3034
3035\c void random_free(random_state *state);
3036
3037Frees a \c{random_state}.
3038
3039\S{utils-random-bits} \cw{random_bits()}
3040
3041\c unsigned long random_bits(random_state *state, int bits);
3042
3043Returns a random number from 0 to \cw{2^bits-1} inclusive. \c{bits}
3044should be between 1 and 32 inclusive.
3045
3046\S{utils-random-upto} \cw{random_upto()}
3047
3048\c unsigned long random_upto(random_state *state, unsigned long limit);
3049
3050Returns a random number from 0 to \cw{limit-1} inclusive.
3051
3052\S{utils-random-state-encode} \cw{random_state_encode()}
3053
3054\c char *random_state_encode(random_state *state);
3055
3056Encodes the entire contents of a \c{random_state} in printable
3057ASCII. Returns a dynamically allocated string containing that
3058encoding. This can subsequently be passed to
3059\cw{random_state_decode()} to reconstruct the same \c{random_state}.
3060
3061\S{utils-random-state-decode} \cw{random_state_decode()}
3062
3063\c random_state *random_state_decode(char *input);
3064
3065Decodes a string generated by \cw{random_state_encode()} and
3066reconstructs an equivalent \c{random_state} to the one encoded, i.e.
3067it should produce the same stream of random numbers.
3068
3069This function has no error reporting; if you pass it an invalid
3070string it will simply generate an arbitrary random state, which may
3071turn out to be noticeably non-random.
3072
3073\S{utils-shuffle} \cw{shuffle()}
3074
3075\c void shuffle(void *array, int nelts, int eltsize, random_state *rs);
3076
3077Shuffles an array into a random order. The interface is much like
3078ANSI C \cw{qsort()}, except that there's no need for a compare
3079function.
3080
3081\c{array} is a pointer to the first element of the array. \c{nelts}
3082is the number of elements in the array; \c{eltsize} is the size of a
3083single element (typically measured using \c{sizeof}). \c{rs} is a
3084\c{random_state} used to generate all the random numbers for the
3085shuffling process.
3086
3087\H{utils-alloc} Memory allocation
3088
3089Puzzles has some central wrappers on the standard memory allocation
3090functions, which provide compile-time type checking, and run-time
3091error checking by means of quitting the application if it runs out
3092of memory. This doesn't provide the best possible recovery from
3093memory shortage, but on the other hand it greatly simplifies the
3094rest of the code, because nothing else anywhere needs to worry about
3095\cw{NULL} returns from allocation.
3096
3097\S{utils-snew} \cw{snew()}
3098
3099\c var = snew(type);
3100\e iii iiii
3101
3102This macro takes a single argument which is a \e{type name}. It
3103allocates space for one object of that type. If allocation fails it
3104will call \cw{fatal()} and not return; so if it does return, you can
3105be confident that its return value is non-\cw{NULL}.
3106
3107The return value is cast to the specified type, so that the compiler
3108will type-check it against the variable you assign it into. Thus,
3109this ensures you don't accidentally allocate memory the size of the
3110wrong type and assign it into a variable of the right one (or vice
3111versa!).
3112
3113\S{utils-snewn} \cw{snewn()}
3114
3115\c var = snewn(n, type);
1f608c7c 3116\e iii i iiii
69491f1e 3117
3118This macro is the array form of \cw{snew()}. It takes two arguments;
3119the first is a number, and the second is a type name. It allocates
3120space for that many objects of that type, and returns a type-checked
3121non-\cw{NULL} pointer just as \cw{snew()} does.
3122
3123\S{utils-sresize} \cw{sresize()}
3124
3125\c var = sresize(var, n, type);
3126\e iii iii i iiii
3127
3128This macro is a type-checked form of \cw{realloc()}. It takes three
3129arguments: an input memory block, a new size in elements, and a
3130type. It re-sizes the input memory block to a size sufficient to
3131contain that many elements of that type. It returns a type-checked
3132non-\cw{NULL} pointer, like \cw{snew()} and \cw{snewn()}.
3133
3134The input memory block can be \cw{NULL}, in which case this function
3135will behave exactly like \cw{snewn()}. (In principle any
3136ANSI-compliant \cw{realloc()} implementation ought to cope with
3137this, but I've never quite trusted it to work everywhere.)
3138
3139\S{utils-sfree} \cw{sfree()}
3140
3141\c void sfree(void *p);
3142
3143This function is pretty much equivalent to \cw{free()}. It is
3144provided with a dynamically allocated block, and frees it.
3145
3146The input memory block can be \cw{NULL}, in which case this function
3147will do nothing. (In principle any ANSI-compliant \cw{free()}
3148implementation ought to cope with this, but I've never quite trusted
3149it to work everywhere.)
3150
3151\S{utils-dupstr} \cw{dupstr()}
3152
3153\c char *dupstr(const char *s);
3154
3155This function dynamically allocates a duplicate of a C string. Like
3156the \cw{snew()} functions, it guarantees to return non-\cw{NULL} or
3157not return at all.
3158
3159(Many platforms provide the function \cw{strdup()}. As well as
3160guaranteeing never to return \cw{NULL}, my version has the advantage
3161of being defined \e{everywhere}, rather than inconveniently not
3162quite everywhere.)
3163
3164\S{utils-free-cfg} \cw{free_cfg()}
3165
3166\c void free_cfg(config_item *cfg);
3167
3168This function correctly frees an array of \c{config_item}s,
3169including walking the array until it gets to the end and freeing
3170precisely those \c{sval} fields which are expected to be dynamically
3171allocated.
3172
3173(See \k{backend-configure} for details of the \c{config_item}
3174structure.)
3175
3176\H{utils-tree234} Sorted and counted tree functions
3177
3178Many games require complex algorithms for generating random puzzles,
3179and some require moderately complex algorithms even during play. A
3180common requirement during these algorithms is for a means of
3181maintaining sorted or unsorted lists of items, such that items can
3182be removed and added conveniently.
3183
3184For general use, Puzzles provides the following set of functions
3185which maintain 2-3-4 trees in memory. (A 2-3-4 tree is a balanced
3186tree structure, with the property that all lookups, insertions,
3187deletions, splits and joins can be done in \cw{O(log N)} time.)
3188
3189All these functions expect you to be storing a tree of \c{void *}
3190pointers. You can put anything you like in those pointers.
3191
3192By the use of per-node element counts, these tree structures have
3193the slightly unusual ability to look elements up by their numeric
3194index within the list represented by the tree. This means that they
3195can be used to store an unsorted list (in which case, every time you
3196insert a new element, you must explicitly specify the position where
3197you wish to insert it). They can also do numeric lookups in a sorted
3198tree, which might be useful for (for example) tracking the median of
3199a changing data set.
3200
3201As well as storing sorted lists, these functions can be used for
3202storing \q{maps} (associative arrays), by defining each element of a
3203tree to be a (key, value) pair.
3204
3205\S{utils-newtree234} \cw{newtree234()}
3206
3207\c tree234 *newtree234(cmpfn234 cmp);
3208
3209Creates a new empty tree, and returns a pointer to it.
3210
3211The parameter \c{cmp} determines the sorting criterion on the tree.
3212Its prototype is
3213
3214\c typedef int (*cmpfn234)(void *, void *);
3215
3216If you want a sorted tree, you should provide a function matching
3217this prototype, which returns like \cw{strcmp()} does (negative if
3218the first argument is smaller than the second, positive if it is
3219bigger, zero if they compare equal). In this case, the function
3220\cw{addpos234()} will not be usable on your tree (because all
3221insertions must respect the sorting order).
3222
3223If you want an unsorted tree, pass \cw{NULL}. In this case you will
3224not be able to use either \cw{add234()} or \cw{del234()}, or any
3225other function such as \cw{find234()} which depends on a sorting
3226order. Your tree will become something more like an array, except
3227that it will efficiently support insertion and deletion as well as
3228lookups by numeric index.
3229
3230\S{utils-freetree234} \cw{freetree234()}
3231
3232\c void freetree234(tree234 *t);
3233
3234Frees a tree. This function will not free the \e{elements} of the
3235tree (because they might not be dynamically allocated, or you might
3236be storing the same set of elements in more than one tree); it will
3237just free the tree structure itself. If you want to free all the
3238elements of a tree, you should empty it before passing it to
3239\cw{freetree234()}, by means of code along the lines of
3240
3241\c while ((element = delpos234(tree, 0)) != NULL)
3242\c sfree(element); /* or some more complicated free function */
3243\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
3244
3245\S{utils-add234} \cw{add234()}
3246
3247\c void *add234(tree234 *t, void *e);
3248
3249Inserts a new element \c{e} into the tree \c{t}. This function
3250expects the tree to be sorted; the new element is inserted according
3251to the sort order.
3252
3253If an element comparing equal to \c{e} is already in the tree, then
3254the insertion will fail, and the return value will be the existing
3255element. Otherwise, the insertion succeeds, and \c{e} is returned.
3256
3257\S{utils-addpos234} \cw{addpos234()}
3258
3259\c void *addpos234(tree234 *t, void *e, int index);
3260
3261Inserts a new element into an unsorted tree. Since there is no
3262sorting order to dictate where the new element goes, you must
3263specify where you want it to go. Setting \c{index} to zero puts the
3264new element right at the start of the list; setting \c{index} to the
3265current number of elements in the tree puts the new element at the
3266end.
3267
3268Return value is \c{e}, in line with \cw{add234()} (although this
3269function cannot fail except by running out of memory, in which case
3270it will bomb out and die rather than returning an error indication).
3271
3272\S{utils-index234} \cw{index234()}
3273
3274\c void *index234(tree234 *t, int index);
3275
3276Returns a pointer to the \c{index}th element of the tree, or
3277\cw{NULL} if \c{index} is out of range. Elements of the tree are
3278numbered from zero.
3279
3280\S{utils-find234} \cw{find234()}
3281
3282\c void *find234(tree234 *t, void *e, cmpfn234 cmp);
3283
3284Searches for an element comparing equal to \c{e} in a sorted tree.
3285
3286If \c{cmp} is \cw{NULL}, the tree's ordinary comparison function
3287will be used to perform the search. However, sometimes you don't
3288want that; suppose, for example, each of your elements is a big
3289structure containing a \c{char *} name field, and you want to find
3290the element with a given name. You \e{could} achieve this by
3291constructing a fake element structure, setting its name field
3292appropriately, and passing it to \cw{find234()}, but you might find
3293it more convenient to pass \e{just} a name string to \cw{find234()},
3294supplying an alternative comparison function which expects one of
3295its arguments to be a bare name and the other to be a large
3296structure containing a name field.
3297
3298Therefore, if \c{cmp} is not \cw{NULL}, then it will be used to
3299compare \c{e} to elements of the tree. The first argument passed to
3300\c{cmp} will always be \c{e}; the second will be an element of the
3301tree.
3302
3303(See \k{utils-newtree234} for the definition of the \c{cmpfn234}
3304function pointer type.)
3305
3306The returned value is the element found, or \cw{NULL} if the search
3307is unsuccessful.
3308
3309\S{utils-findrel234} \cw{findrel234()}
3310
3311\c void *findrel234(tree234 *t, void *e, cmpfn234 cmp, int relation);
3312
3313This function is like \cw{find234()}, but has the additional ability
3314to do a \e{relative} search. The additional parameter \c{relation}
3315can be one of the following values:
3316
3317\dt \cw{REL234_EQ}
3318
3319\dd Find only an element that compares equal to \c{e}. This is
3320exactly the behaviour of \cw{find234()}.
3321
3322\dt \cw{REL234_LT}
3323
3324\dd Find the greatest element that compares strictly less than
3325\c{e}. \c{e} may be \cw{NULL}, in which case it finds the greatest
3326element in the whole tree (which could also be done by
3327\cw{index234(t, count234(t)-1)}).
3328
3329\dt \cw{REL234_LE}
3330
3331\dd Find the greatest element that compares less than or equal to
3332\c{e}. (That is, find an element that compares equal to \c{e} if
3333possible, but failing that settle for something just less than it.)
3334
3335\dt \cw{REL234_GT}
3336
3337\dd Find the smallest element that compares strictly greater than
3338\c{e}. \c{e} may be \cw{NULL}, in which case it finds the smallest
3339element in the whole tree (which could also be done by
3340\cw{index234(t, 0)}).
3341
3342\dt \cw{REL234_GE}
3343
3344\dd Find the smallest element that compares greater than or equal to
3345\c{e}. (That is, find an element that compares equal to \c{e} if
3346possible, but failing that settle for something just bigger than
3347it.)
3348
3349Return value, as before, is the element found or \cw{NULL} if no
3350element satisfied the search criterion.
3351
3352\S{utils-findpos234} \cw{findpos234()}
3353
3354\c void *findpos234(tree234 *t, void *e, cmpfn234 cmp, int *index);
3355
3356This function is like \cw{find234()}, but has the additional feature
3357of returning the index of the element found in the tree; that index
3358is written to \c{*index} in the event of a successful search (a
3359non-\cw{NULL} return value).
3360
3361\c{index} may be \cw{NULL}, in which case this function behaves
3362exactly like \cw{find234()}.
3363
3364\S{utils-findrelpos234} \cw{findrelpos234()}
3365
3366\c void *findrelpos234(tree234 *t, void *e, cmpfn234 cmp, int relation,
3367\c int *index);
3368
3369This function combines all the features of \cw{findrel234()} and
3370\cw{findpos234()}.
3371
3372\S{utils-del234} \cw{del234()}
3373
3374\c void *del234(tree234 *t, void *e);
3375
3376Finds an element comparing equal to \c{e} in the tree, deletes it,
3377and returns it.
3378
3379The input tree must be sorted.
3380
3381The element found might be \c{e} itself, or might merely compare
3382equal to it.
3383
3384Return value is \cw{NULL} if no such element is found.
3385
3386\S{utils-delpos234} \cw{delpos234()}
3387
3388\c void *delpos234(tree234 *t, int index);
3389
3390Deletes the element at position \c{index} in the tree, and returns
3391it.
3392
3393Return value is \cw{NULL} if the index is out of range.
3394
3395\S{utils-count234} \cw{count234()}
3396
3397\c int count234(tree234 *t);
3398
3399Returns the number of elements currently in the tree.
3400
3401\S{utils-splitpos234} \cw{splitpos234()}
3402
3403\c tree234 *splitpos234(tree234 *t, int index, int before);
3404
3405Splits the input tree into two pieces at a given position, and
3406creates a new tree containing all the elements on one side of that
3407position.
3408
3409If \c{before} is \cw{TRUE}, then all the items at or after position
3410\c{index} are left in the input tree, and the items before that
3411point are returned in the new tree. Otherwise, the reverse happens:
3412all the items at or after \c{index} are moved into the new tree, and
3413those before that point are left in the old one.
3414
3415If \c{index} is equal to 0 or to the number of elements in the input
3416tree, then one of the two trees will end up empty (and this is not
3417an error condition). If \c{index} is further out of range in either
3418direction, the operation will fail completely and return \cw{NULL}.
3419
3420This operation completes in \cw{O(log N)} time, no matter how large
3421the tree or how balanced or unbalanced the split.
3422
3423\S{utils-split234} \cw{split234()}
3424
3425\c tree234 *split234(tree234 *t, void *e, cmpfn234 cmp, int rel);
3426
3427Splits a sorted tree according to its sort order.
3428
3429\c{rel} can be any of the relation constants described in
3430\k{utils-findrel234}, \e{except} for \cw{REL234_EQ}. All the
3431elements having that relation to \c{e} will be transferred into the
3432new tree; the rest will be left in the old one.
3433
3434The parameter \c{cmp} has the same semantics as it does in
3435\cw{find234()}: if it is not \cw{NULL}, it will be used in place of
3436the tree's own comparison function when comparing elements to \c{e},
3437in such a way that \c{e} itself is always the first of its two
3438operands.
3439
3440Again, this operation completes in \cw{O(log N)} time, no matter how
3441large the tree or how balanced or unbalanced the split.
3442
3443\S{utils-join234} \cw{join234()}
3444
3445\c tree234 *join234(tree234 *t1, tree234 *t2);
3446
3447Joins two trees together by concatenating the lists they represent.
3448All the elements of \c{t2} are moved into \c{t1}, in such a way that
3449they appear \e{after} the elements of \c{t1}. The tree \c{t2} is
3450freed; the return value is \c{t1}.
3451
3452If you apply this function to a sorted tree and it violates the sort
3453order (i.e. the smallest element in \c{t2} is smaller than or equal
3454to the largest element in \c{t1}), the operation will fail and
3455return \cw{NULL}.
3456
3457This operation completes in \cw{O(log N)} time, no matter how large
3458the trees being joined together.
3459
3460\S{utils-join234r} \cw{join234r()}
3461
3462\c tree234 *join234r(tree234 *t1, tree234 *t2);
3463
3464Joins two trees together in exactly the same way as \cw{join234()},
3465but this time the combined tree is returned in \c{t2}, and \c{t1} is
3466destroyed. The elements in \c{t1} still appear before those in
3467\c{t2}.
3468
3469Again, this operation completes in \cw{O(log N)} time, no matter how
3470large the trees being joined together.
3471
3472\S{utils-copytree234} \cw{copytree234()}
3473
3474\c tree234 *copytree234(tree234 *t, copyfn234 copyfn,
3475\c void *copyfnstate);
3476
3477Makes a copy of an entire tree.
3478
3479If \c{copyfn} is \cw{NULL}, the tree will be copied but the elements
3480will not be; i.e. the new tree will contain pointers to exactly the
3481same physical elements as the old one.
3482
3483If you want to copy each actual element during the operation, you
3484can instead pass a function in \c{copyfn} which makes a copy of each
3485element. That function has the prototype
3486
3487\c typedef void *(*copyfn234)(void *state, void *element);
3488
3489and every time it is called, the \c{state} parameter will be set to
3490the value you passed in as \c{copyfnstate}.
3491
3492\H{utils-misc} Miscellaneous utility functions and macros
3493
3494This section contains all the utility functions which didn't
3495sensibly fit anywhere else.
3496
3497\S{utils-truefalse} \cw{TRUE} and \cw{FALSE}
3498
3499The main Puzzles header file defines the macros \cw{TRUE} and
3500\cw{FALSE}, which are used throughout the code in place of 0 and 1
3501to indicate that the values are in a boolean context. For code base
3502consistency, I'd prefer it if submissions of new code followed this
3503convention as well.
3504
3505\S{utils-maxmin} \cw{max()} and \cw{min()}
3506
3507The main Puzzles header file defines the pretty standard macros
3508\cw{max()} and \cw{min()}, each of which is given two arguments and
3509returns the one which compares greater or less respectively.
3510
3511These macros may evaluate their arguments multiple times. Avoid side
3512effects.
3513
3514\S{utils-pi} \cw{PI}
3515
3516The main Puzzles header file defines a macro \cw{PI} which expands
3517to a floating-point constant representing pi.
3518
3519(I've never understood why ANSI's \cw{<math.h>} doesn't define this.
3520It'd be so useful!)
3521
3522\S{utils-obfuscate-bitmap} \cw{obfuscate_bitmap()}
3523
3524\c void obfuscate_bitmap(unsigned char *bmp, int bits, int decode);
3525
3526This function obscures the contents of a piece of data, by
3527cryptographic methods. It is useful for games of hidden information
3528(such as Mines, Guess or Black Box), in which the game ID
3529theoretically reveals all the information the player is supposed to
3530be trying to guess. So in order that players should be able to send
3531game IDs to one another without accidentally spoiling the resulting
3532game by looking at them, these games obfuscate their game IDs using
3533this function.
3534
3535Although the obfuscation function is cryptographic, it cannot
3536properly be called encryption because it has no key. Therefore,
3537anybody motivated enough can re-implement it, or hack it out of the
3538Puzzles source, and strip the obfuscation off one of these game IDs
3539to see what lies beneath. (Indeed, they could usually do it much
3540more easily than that, by entering the game ID into their own copy
3541of the puzzle and hitting Solve.) The aim is not to protect against
3542a determined attacker; the aim is simply to protect people who
3543wanted to play the game honestly from \e{accidentally} spoiling
3544their own fun.
3545
3546The input argument \c{bmp} points at a piece of memory to be
3547obfuscated. \c{bits} gives the length of the data. Note that that
3548length is in \e{bits} rather than bytes: if you ask for obfuscation
3549of a partial number of bytes, then you will get it. Bytes are
3550considered to be used from the top down: thus, for example, setting
3551\c{bits} to 10 will cover the whole of \cw{bmp[0]} and the \e{top
3552two} bits of \cw{bmp[1]}. The remainder of a partially used byte is
3553undefined (i.e. it may be corrupted by the function).
3554
3555The parameter \c{decode} is \cw{FALSE} for an encoding operation,
3556and \cw{TRUE} for a decoding operation. Each is the inverse of the
3557other. (There's no particular reason you shouldn't obfuscate by
3558decoding and restore cleartext by encoding, if you really wanted to;
3559it should still work.)
3560
3561The input bitmap is processed in place.
3562
3563\S{utils-bin2hex} \cw{bin2hex()}
3564
3565\c char *bin2hex(const unsigned char *in, int inlen);
3566
3567This function takes an input byte array and converts it into an
3568ASCII string encoding those bytes in (lower-case) hex. It returns a
3569dynamically allocated string containing that encoding.
3570
3571This function is useful for encoding the result of
3572\cw{obfuscate_bitmap()} in printable ASCII for use in game IDs.
3573
3574\S{utils-hex2bin} \cw{hex2bin()}
3575
3576\c unsigned char *hex2bin(const char *in, int outlen);
3577
3578This function takes an ASCII string containing hex digits, and
3579converts it back into a byte array of length \c{outlen}. If there
3580aren't enough hex digits in the string, the contents of the
3581resulting array will be undefined.
3582
3583This function is the inverse of \cw{bin2hex()}.
3584
3585\S{utils-game-mkhighlight} \cw{game_mkhighlight()}
3586
3587\c void game_mkhighlight(frontend *fe, float *ret,
3588\c int background, int highlight, int lowlight);
3589
3590It's reasonably common for a puzzle game's graphics to use
3591highlights and lowlights to indicate \q{raised} or \q{lowered}
3592sections. Fifteen, Sixteen and Twiddle are good examples of this.
3593
3594Puzzles using this graphical style are running a risk if they just
3595use whatever background colour is supplied to them by the front end,
3596because that background colour might be too light to see any
3597highlights on at all. (In particular, it's not unheard of for the
3598front end to specify a default background colour of white.)
3599
3600Therefore, such puzzles can call this utility function from their
3601\cw{colours()} routine (\k{backend-colours}). You pass it your front
3602end handle, a pointer to the start of your return array, and three
3603colour indices. It will:
3604
3605\b call \cw{frontend_default_colour()} (\k{frontend-default-colour})
3606to fetch the front end's default background colour
3607
3608\b alter the brightness of that colour if it's unsuitable
3609
3610\b define brighter and darker variants of the colour to be used as
3611highlights and lowlights
3612
3613\b write those results into the relevant positions in the \c{ret}
3614array.
3615
3616Thus, \cw{ret[background*3]} to \cw{ret[background*3+2]} will be set
3617to RGB values defining a sensible background colour, and similary
3618\c{highlight} and \c{lowlight} will be set to sensible colours.
3619
3620\C{writing} How to write a new puzzle
3621
3622This chapter gives a guide to how to actually write a new puzzle:
3623where to start, what to do first, how to solve common problems.
3624
3625The previous chapters have been largely composed of facts. This one
3626is mostly advice.
3627
3628\H{writing-editorial} Choosing a puzzle
3629
3630Before you start writing a puzzle, you have to choose one. Your
3631taste in puzzle games is up to you, of course; and, in fact, you're
3632probably reading this guide because you've \e{already} thought of a
3633game you want to write. But if you want to get it accepted into the
3634official Puzzles distribution, then there's a criterion it has to
3635meet.
3636
3637The current Puzzles editorial policy is that all games should be
3638\e{fair}. A fair game is one which a player can only fail to
3639complete through demonstrable lack of skill \dash that is, such that
3640a better player in the same situation would have \e{known} to do
3641something different.
3642
3643For a start, that means every game presented to the user must have
3644\e{at least one solution}. Giving the unsuspecting user a puzzle
3645which is actually impossible is not acceptable. (There is an
3646exception: if the user has selected some non-default option which is
3647clearly labelled as potentially unfair, \e{then} you're allowed to
3648generate possibly insoluble puzzles, because the user isn't
3649unsuspecting any more. Same Game and Mines both have options of this
3650type.)
3651
3652Also, this actually \e{rules out} games such as Klondike, or the
3653normal form of Mahjong Solitaire. Those games have the property that
3654even if there is a solution (i.e. some sequence of moves which will
3655get from the start state to the solved state), the player doesn't
3656necessarily have enough information to \e{find} that solution. In
3657both games, it is possible to reach a dead end because you had an
3658arbitrary choice to make and made it the wrong way. This violates
3659the fairness criterion, because a better player couldn't have known
3660they needed to make the other choice.
3661
3662(GNOME has a variant on Mahjong Solitaire which makes it fair: there
3663is a Shuffle operation which randomly permutes all the remaining
3664tiles without changing their positions, which allows you to get out
3665of a sticky situation. Using this operation adds a 60-second penalty
3666to your solution time, so it's to the player's advantage to try to
3667minimise the chance of having to use it. It's still possible to
3668render the game uncompletable if you end up with only two tiles
3669vertically stacked, but that's easy to foresee and avoid using a
3670shuffle operation. This form of the game \e{is} fair. Implementing
3671it in Puzzles would require an infrastructure change so that the
3672back end could communicate time penalties to the mid-end, but that
3673would be easy enough.)
3674
3675Providing a \e{unique} solution is a little more negotiable; it
3676depends on the puzzle. Solo would have been of unacceptably low
3677quality if it didn't always have a unique solution, whereas Twiddle
3678inherently has multiple solutions by its very nature and it would
3679have been meaningless to even \e{suggest} making it uniquely
3680soluble. Somewhere in between, Flip could reasonably be made to have
3681unique solutions (by enforcing a zero-dimension kernel in every
3682generated matrix) but it doesn't seem like a serious quality problem
3683that it doesn't.
3684
3685Of course, you don't \e{have} to care about all this. There's
3686nothing stopping you implementing any puzzle you want to if you're
3687happy to maintain your puzzle yourself, distribute it from your own
3688web site, fork the Puzzles code completely, or anything like that.
3689It's free software; you can do what you like with it. But any game
3690that you want to be accepted into \e{my} Puzzles code base has to
3691satisfy the fairness criterion, which means all randomly generated
3692puzzles must have a solution (unless the user has deliberately
3693chosen otherwise) and it must be possible \e{in theory} to find that
3694solution without having to guess.
3695
3696\H{writing-gs} Getting started
3697
3698The simplest way to start writing a new puzzle is to copy
3699\c{nullgame.c}. This is a template puzzle source file which does
3700almost nothing, but which contains all the back end function
3701prototypes and declares the back end data structure correctly. It is
3702built every time the rest of Puzzles is built, to ensure that it
3703doesn't get out of sync with the code and remains buildable.
3704
3705So start by copying \c{nullgame.c} into your new source file. Then
3706you'll gradually add functionality until the very boring Null Game
3707turns into your real game.
3708
3709Next you'll need to add your puzzle to the Makefiles, in order to
3710compile it conveniently. \e{Do not edit the Makefiles}: they are
3711created automatically by the script \c{mkfiles.pl}, from the file
3712called \c{Recipe}. Edit \c{Recipe}, and then re-run \c{mkfiles.pl}.
3713
3714Once your source file is building, you can move on to the fun bit.
3715
3716\S{writing-generation} Puzzle generation
3717
3718Randomly generating instances of your puzzle is almost certain to be
3719the most difficult part of the code, and also the task with the
3720highest chance of turning out to be completely infeasible. Therefore
3721I strongly recommend doing it \e{first}, so that if it all goes
3722horribly wrong you haven't wasted any more time than you absolutely
3723had to. What I usually do is to take an unmodified \c{nullgame.c},
3724and start adding code to \cw{new_game_desc()} which tries to
3725generate a puzzle instance and print it out using \cw{printf()}.
3726Once that's working, \e{then} I start connecting it up to the return
3727value of \cw{new_game_desc()}, populating other structures like
3728\c{game_params}, and generally writing the rest of the source file.
3729
3730There are many ways to generate a puzzle which is known to be
3731soluble. In this section I list all the methods I currently know of,
3732in case any of them can be applied to your puzzle. (Not all of these
3733methods will work, or in some cases even make sense, for all
3734puzzles.)
3735
3736Some puzzles are mathematically tractable, meaning you can work out
3737in advance which instances are soluble. Sixteen, for example, has a
3738parity constraint in some settings which renders exactly half the
3739game space unreachable, but it can be mathematically proved that any
3740position not in that half \e{is} reachable. Therefore, Sixteen's
3741grid generation simply consists of selecting at random from a well
3742defined subset of the game space. Cube in its default state is even
3743easier: \e{every} possible arrangement of the blue squares and the
3744cube's starting position is soluble!
3745
3746Another option is to redefine what you mean by \q{soluble}. Black
3747Box takes this approach. There are layouts of balls in the box which
3748are completely indistinguishable from one another no matter how many
3749beams you fire into the box from which angles, which would normally
3750be grounds for declaring those layouts unfair; but fortunately,
3751detecting that indistinguishability is computationally easy. So
3752Black Box doesn't demand that your ball placements match its own; it
3753merely demands that your ball placements be \e{indistinguishable}
3754from the ones it was thinking of. If you have an ambiguous puzzle,
3755then any of the possible answers is considered to be a solution.
3756Having redefined the rules in that way, any puzzle is soluble again.
3757
3758Those are the simple techniques. If they don't work, you have to get
3759cleverer.
3760
3761One way to generate a soluble puzzle is to start from the solved
3762state and make inverse moves until you reach a starting state. Then
3763you know there's a solution, because you can just list the inverse
3764moves you made and make them in the opposite order to return to the
3765solved state.
3766
3767This method can be simple and effective for puzzles where you get to
3768decide what's a starting state and what's not. In Pegs, for example,
3769the generator begins with one peg in the centre of the board and
3770makes inverse moves until it gets bored; in this puzzle, valid
3771inverse moves are easy to detect, and \e{any} state that's reachable
3772from the solved state by inverse moves is a reasonable starting
3773position. So Pegs just continues making inverse moves until the
3774board satisfies some criteria about extent and density, and then
3775stops and declares itself done.
3776
3777For other puzzles, it can be a lot more difficult. Same Game uses
3778this strategy too, and it's lucky to get away with it at all: valid
3779inverse moves aren't easy to find (because although it's easy to
3780insert additional squares in a Same Game position, it's difficult to
3781arrange that \e{after} the insertion they aren't adjacent to any
3782other squares of the same colour), so you're constantly at risk of
3783running out of options and having to backtrack or start again. Also,
3784Same Game grids never start off half-empty, which means you can't
3785just stop when you run out of moves \dash you have to find a way to
3786fill the grid up \e{completely}.
3787
3788The other way to generate a puzzle that's soluble is to start from
3789the other end, and actually write a \e{solver}. This tends to ensure
3790that a puzzle has a \e{unique} solution over and above having a
3791solution at all, so it's a good technique to apply to puzzles for
3792which that's important.
3793
3794One theoretical drawback of generating soluble puzzles by using a
3795solver is that your puzzles are restricted in difficulty to those
3796which the solver can handle. (Most solvers are not fully general:
3797many sets of puzzle rules are NP-complete or otherwise nasty, so
3798most solvers can only handle a subset of the theoretically soluble
3799puzzles.) It's been my experience in practice, however, that this
3800usually isn't a problem; computers are good at very different things
3801from humans, and what the computer thinks is nice and easy might
3802still be pleasantly challenging for a human. For example, when
3803solving Dominosa puzzles I frequently find myself using a variety of
3804reasoning techniques that my solver doesn't know about; in
3805principle, therefore, I should be able to solve the puzzle using
3806only those techniques it \e{does} know about, but this would involve
3807repeatedly searching the entire grid for the one simple deduction I
3808can make. Computers are good at this sort of exhaustive search, but
3809it's been my experience that human solvers prefer to do more complex
3810deductions than to spend ages searching for simple ones. So in many
3811cases I don't find my own playing experience to be limited by the
3812restrictions on the solver.
3813
3814(This isn't \e{always} the case. Solo is a counter-example;
3815generating Solo puzzles using a simple solver does lead to
3816qualitatively easier puzzles. Therefore I had to make the Solo
3817solver rather more advanced than most of them.)
3818
3819There are several different ways to apply a solver to the problem of
3820generating a soluble puzzle. I list a few of them below.
3821
3822The simplest approach is brute force: randomly generate a puzzle,
3823use the solver to see if it's soluble, and if not, throw it away and
3824try again until you get lucky. This is often a viable technique if
3825all else fails, but it tends not to scale well: for many puzzle
3826types, the probability of finding a uniquely soluble instance
3827decreases sharply as puzzle size goes up, so this technique might
3828work reasonably fast for small puzzles but take (almost) forever at
3829larger sizes. Still, if there's no other alternative it can be
3830usable: Pattern and Dominosa both use this technique. (However,
3831Dominosa has a means of tweaking the randomly generated grids to
3832increase the \e{probability} of them being soluble, by ruling out
3833one of the most common ambiguous cases. This improved generation
3834speed by over a factor of 10 on the highest preset!)
3835
3836An approach which can be more scalable involves generating a grid
3837and then tweaking it to make it soluble. This is the technique used
3838by Mines and also by Net: first a random puzzle is generated, and
3839then the solver is run to see how far it gets. Sometimes the solver
3840will get stuck; when that happens, examine the area it's having
3841trouble with, and make a small random change in that area to allow
3842it to make more progress. Continue solving (possibly even without
3843restarting the solver), tweaking as necessary, until the solver
3844finishes. Then restart the solver from the beginning to ensure that
3845the tweaks haven't caused new problems in the process of solving old
3846ones (which can sometimes happen).
3847
3848This strategy works well in situations where the usual solver
3849failure mode is to get stuck in an easily localised spot. Thus it
3850works well for Net and Mines, whose most common failure mode tends
3851to be that most of the grid is fine but there are a few widely
3852separated ambiguous sections; but it would work less well for
3853Dominosa, in which the way you get stuck is to have scoured the
3854whole grid and not found anything you can deduce \e{anywhere}. Also,
3855it relies on there being a low probability that tweaking the grid
3856introduces a new problem at the same time as solving the old one;
3857Mines and Net also have the property that most of their deductions
3858are local, so that it's very unlikely for a tweak to affect
3859something half way across the grid from the location where it was
3860applied. In Dominosa, by contrast, a lot of deductions use
3861information about half the grid (\q{out of all the sixes, only one
3862is next to a three}, which can depend on the values of up to 32 of
3863the 56 squares in the default setting!), so this tweaking strategy
3864would be rather less likely to work well.
3865
0004c8b3 3866A more specialised strategy is that used in Solo and Slant. These
3867puzzles have the property that they derive their difficulty from not
3868presenting all the available clues. (In Solo's case, if all the
3869possible clues were provided then the puzzle would already be
3870solved; in Slant it would still require user action to fill in the
3871lines, but it would present no challenge at all). Therefore, a
3872simple generation technique is to leave the decision of which clues
3873to provide until the last minute. In other words, first generate a
3874random \e{filled} grid with all possible clues present, and then
3875gradually remove clues for as long as the solver reports that it's
3876still soluble. Unlike the methods described above, this technique
3877\e{cannot} fail \dash once you've got a filled grid, nothing can
3878stop you from being able to convert it into a viable puzzle.
3879However, it wouldn't even be meaningful to apply this technique to
3880(say) Pattern, in which clues can never be left out, so the only way
3881to affect the set of clues is by altering the solution.
69491f1e 3882
3883(Unfortunately, Solo is complicated by the need to provide puzzles
3884at varying difficulty levels. It's easy enough to generate a puzzle
3885of \e{at most} a given level of difficulty; you just have a solver
3886with configurable intelligence, and you set it to a given level and
3887apply the above technique, thus guaranteeing that the resulting grid
3888is solvable by someone with at most that much intelligence. However,
3889generating a puzzle of \e{at least} a given level of difficulty is
3890rather harder; if you go for \e{at most} Intermediate level, you're
3891likely to find that you've accidentally generated a Trivial grid a
3892lot of the time, because removing just one number is sufficient to
3893take the puzzle from Trivial straight to Ambiguous. In that
3894situation Solo has no remaining options but to throw the puzzle away
3895and start again.)
3896
3897A final strategy is to use the solver \e{during} puzzle
3898construction: lay out a bit of the grid, run the solver to see what
3899it allows you to deduce, and then lay out a bit more to allow the
3900solver to make more progress. There are articles on the web that
3901recommend constructing Sudoku puzzles by this method (which is
3902completely the opposite way round to how Solo does it); for Sudoku
3903it has the advantage that you get to specify your clue squares in
3904advance (so you can have them make pretty patterns).
3905
3906Rectangles uses a strategy along these lines. First it generates a
3907grid by placing the actual rectangles; then it has to decide where
3908in each rectangle to place a number. It uses a solver to help it
3909place the numbers in such a way as to ensure a unique solution. It
3910does this by means of running a test solver, but it runs the solver
3911\e{before} it's placed any of the numbers \dash which means the
3912solver must be capable of coping with uncertainty about exactly
3913where the numbers are! It runs the solver as far as it can until it
3914gets stuck; then it narrows down the possible positions of a number
3915in order to allow the solver to make more progress, and so on. Most
3916of the time this process terminates with the grid fully solved, at
3917which point any remaining number-placement decisions can be made at
3918random from the options not so far ruled out. Note that unlike the
3919Net/Mines tweaking strategy described above, this algorithm does not
3920require a checking run after it completes: if it finishes
3921successfully at all, then it has definitely produced a uniquely
3922soluble puzzle.
3923
3924Most of the strategies described above are not 100% reliable. Each
3925one has a failure rate: every so often it has to throw out the whole
3926grid and generate a fresh one from scratch. (Solo's strategy would
3927be the exception, if it weren't for the need to provide configurable
3928difficulty levels.) Occasional failures are not a fundamental
3929problem in this sort of work, however: it's just a question of
3930dividing the grid generation time by the success rate (if it takes
393110ms to generate a candidate grid and 1/5 of them work, then it will
3932take 50ms on average to generate a viable one), and seeing whether
3933the expected time taken to \e{successfully} generate a puzzle is
3934unacceptably slow. Dominosa's generator has a very low success rate
3935(about 1 out of 20 candidate grids turn out to be usable, and if you
3936think \e{that's} bad then go and look at the source code and find
3937the comment showing what the figures were before the generation-time
3938tweaks!), but the generator itself is very fast so this doesn't
3939matter. Rectangles has a slower generator, but fails well under 50%
3940of the time.
3941
3942So don't be discouraged if you have an algorithm that doesn't always
3943work: if it \e{nearly} always works, that's probably good enough.
3944The one place where reliability is important is that your algorithm
3945must never produce false positives: it must not claim a puzzle is
3946soluble when it isn't. It can produce false negatives (failing to
3947notice that a puzzle is soluble), and it can fail to generate a
3948puzzle at all, provided it doesn't do either so often as to become
3949slow.
3950
e9f8a17f 3951One last piece of advice: for grid-based puzzles, when writing and
69491f1e 3952testing your generation algorithm, it's almost always a good idea
3953\e{not} to test it initially on a grid that's square (i.e.
e9f8a17f 3954\cw{w==h}), because if the grid is square then you won't notice if
3955you mistakenly write \c{h} instead of \c{w} (or vice versa)
3956somewhere in the code. Use a rectangular grid for testing, and any
3957size of grid will be likely to work after that.
69491f1e 3958
3959\S{writing-textformats} Designing textual description formats
3960
3961Another aspect of writing a puzzle which is worth putting some
3962thought into is the design of the various text description formats:
3963the format of the game parameter encoding, the game description
3964encoding, and the move encoding.
3965
3966The first two of these should be reasonably intuitive for a user to
3967type in; so provide some flexibility where possible. Suppose, for
3968example, your parameter format consists of two numbers separated by
3969an \c{x} to specify the grid dimensions (\c{10x10} or \c{20x15}),
3970and then has some suffixes to specify other aspects of the game
3971type. It's almost always a good idea in this situation to arrange
3972that \cw{decode_params()} can handle the suffixes appearing in any
3973order, even if \cw{encode_params()} only ever generates them in one
3974order.
3975
3976These formats will also be expected to be reasonably stable: users
3977will expect to be able to exchange game IDs with other users who
3978aren't running exactly the same version of your game. So make them
3979robust and stable: don't build too many assumptions into the game ID
3980format which will have to be changed every time something subtle
3981changes in the puzzle code.
3982
3983\H{writing-howto} Common how-to questions
3984
3985This section lists some common things people want to do when writing
3986a puzzle, and describes how to achieve them within the Puzzles
3987framework.
3988
3989\S{writing-howto-cursor} Drawing objects at only one position
3990
3991A common phenomenon is to have an object described in the
3992\c{game_state} or the \c{game_ui} which can only be at one position.
3993A cursor \dash probably specified in the \c{game_ui} \dash is a good
3994example.
3995
3996In the \c{game_ui}, it would \e{obviously} be silly to have an array
3997covering the whole game grid with a boolean flag stating whether the
3998cursor was at each position. Doing that would waste space, would
3999make it difficult to find the cursor in order to do anything with
4000it, and would introduce the potential for synchronisation bugs in
4001which you ended up with two cursors or none. The obviously sensible
4002way to store a cursor in the \c{game_ui} is to have fields directly
e9f8a17f 4003encoding the cursor's coordinates.
69491f1e 4004
4005However, it is a mistake to assume that the same logic applies to
4006the \c{game_drawstate}. If you replicate the cursor position fields
4007in the draw state, the redraw code will get very complicated. In the
4008draw state, in fact, it \e{is} probably the right thing to have a
4009cursor flag for every position in the grid. You probably have an
4010array for the whole grid in the drawstate already (stating what is
4011currently displayed in the window at each position); the sensible
4012approach is to add a \q{cursor} flag to each element of that array.
4013Then the main redraw loop will look something like this
4014(pseudo-code):
4015
4016\c for (y = 0; y < h; y++) {
4017\c for (x = 0; x < w; x++) {
4018\c int value = state->symbol_at_position[y][x];
4019\c if (x == ui->cursor_x && y == ui->cursor_y)
4020\c value |= CURSOR;
4021\c if (ds->symbol_at_position[y][x] != value) {
74021716 4022\c symbol_drawing_subroutine(dr, ds, x, y, value);
69491f1e 4023\c ds->symbol_at_position[y][x] = value;
4024\c }
4025\c }
4026\c }
4027
4028This loop is very simple, pretty hard to get wrong, and
4029\e{automatically} deals both with erasing the previous cursor and
4030drawing the new one, with no special case code required.
4031
4032This type of loop is generally a sensible way to write a redraw
4033function, in fact. The best thing is to ensure that the information
4034stored in the draw state for each position tells you \e{everything}
4035about what was drawn there. A good way to ensure that is to pass
4036precisely the same information, and \e{only} that information, to a
4037subroutine that does the actual drawing; then you know there's no
4038additional information which affects the drawing but which you don't
4039notice changes in.
4040
4041\S{writing-keyboard-cursor} Implementing a keyboard-controlled cursor
4042
4043It is often useful to provide a keyboard control method in a
4044basically mouse-controlled game. A keyboard-controlled cursor is
4045best implemented by storing its location in the \c{game_ui} (since
4046if it were in the \c{game_state} then the user would have to
4047separately undo every cursor move operation). So the procedure would
4048be:
4049
4050\b Put cursor position fields in the \c{game_ui}.
4051
4052\b \cw{interpret_move()} responds to arrow keys by modifying the
4053cursor position fields and returning \cw{""}.
4054
4055\b \cw{interpret_move()} responds to some sort of fire button by
4056actually performing a move based on the current cursor location.
4057
4058\b You might want an additional \c{game_ui} field stating whether
4059the cursor is currently visible, and having it disappear when a
4060mouse action occurs (so that it doesn't clutter the display when not
4061actually in use).
4062
4063\b You might also want to automatically hide the cursor in
4064\cw{changed_state()} when the current game state changes to one in
4065which there is no move to make (which is the case in some types of
4066completed game).
4067
4068\b \cw{redraw()} draws the cursor using the technique described in
4069\k{writing-howto-cursor}.
4070
4071\S{writing-howto-dragging} Implementing draggable sprites
4072
4073Some games have a user interface which involves dragging some sort
4074of game element around using the mouse. If you need to show a
4075graphic moving smoothly over the top of other graphics, use a
4076blitter (see \k{drawing-blitter} for the blitter API) to save the
4077background underneath it. The typical scenario goes:
4078
4079\b Have a blitter field in the \c{game_drawstate}.
4080
4081\b Set the blitter field to \cw{NULL} in the game's
4082\cw{new_drawstate()} function, since you don't yet know how big the
4083piece of saved background needs to be.
4084
4085\b In the game's \cw{set_size()} function, once you know the size of
4086the object you'll be dragging around the display and hence the
05e50a96 4087required size of the blitter, actually allocate the blitter.
69491f1e 4088
4089\b In \cw{free_drawstate()}, free the blitter if it's not \cw{NULL}.
4090
4091\b In \cw{interpret_move()}, respond to mouse-down and mouse-drag
4092events by updating some fields in the \cw{game_ui} which indicate
4093that a drag is in progress.
4094
4095\b At the \e{very end} of \cw{redraw()}, after all other drawing has
4096been done, draw the moving object if there is one. First save the
4097background under the object in the blitter; then set a clip
4098rectangle covering precisely the area you just saved (just in case
4099anti-aliasing or some other error causes your drawing to go beyond
4100the area you saved). Then draw the object, and call \cw{unclip()}.
4101Finally, set a flag in the \cw{game_drawstate} that indicates that
4102the blitter needs restoring.
4103
4104\b At the very start of \cw{redraw()}, before doing anything else at
4105all, check the flag in the \cw{game_drawstate}, and if it says the
4106blitter needs restoring then restore it. (Then clear the flag, so
4107that this won't happen again in the next redraw if no moving object
4108is drawn this time.)
4109
4110This way, you will be able to write the rest of the redraw function
4111completely ignoring the dragged object, as if it were floating above
4112your bitmap and being completely separate.
4113
4114\S{writing-ref-counting} Sharing large invariant data between all
4115game states
4116
4117In some puzzles, there is a large amount of data which never changes
4118between game states. The array of numbers in Dominosa is a good
4119example.
4120
4121You \e{could} dynamically allocate a copy of that array in every
4122\c{game_state}, and have \cw{dup_game()} make a fresh copy of it for
4123every new \c{game_state}; but it would waste memory and time. A
4124more efficient way is to use a reference-counted structure.
4125
4126\b Define a structure type containing the data in question, and also
4127containing an integer reference count.
4128
4129\b Have a field in \c{game_state} which is a pointer to this
4130structure.
4131
4132\b In \cw{new_game()}, when creating a fresh game state at the start
4133of a new game, create an instance of this structure, initialise it
4134with the invariant data, and set its reference count to 1.
4135
4136\b In \cw{dup_game()}, rather than making a copy of the structure
4137for the new game state, simply set the new game state to point at
4138the same copy of the structure, and increment its reference count.
4139
4140\b In \cw{free_game()}, decrement the reference count in the
4141structure pointed to by the game state; if the count reaches zero,
4142free the structure.
4143
4144This way, the invariant data will persist for only as long as it's
4145genuinely needed; \e{as soon} as the last game state for a
4146particular puzzle instance is freed, the invariant data for that
4147puzzle will vanish as well. Reference counting is a very efficient
4148form of garbage collection, when it works at all. (Which it does in
4149this instance, of course, because there's no possibility of circular
4150references.)
4151
4152\S{writing-flash-types} Implementing multiple types of flash
4153
4154In some games you need to flash in more than one different way.
4155Mines, for example, flashes white when you win, and flashes red when
4156you tread on a mine and die.
4157
4158The simple way to do this is:
4159
4160\b Have a field in the \c{game_ui} which describes the type of flash.
4161
4162\b In \cw{flash_length()}, examine the old and new game states to
4163decide whether a flash is required and what type. Write the type of
4164flash to the \c{game_ui} field whenever you return non-zero.
4165
4166\b In \cw{redraw()}, when you detect that \c{flash_time} is
4167non-zero, examine the field in \c{game_ui} to decide which type of
4168flash to draw.
4169
4170\cw{redraw()} will never be called with \c{flash_time} non-zero
4171unless \cw{flash_length()} was first called to tell the mid-end that
4172a flash was required; so whenever \cw{redraw()} notices that
4173\c{flash_time} is non-zero, you can be sure that the field in
4174\c{game_ui} is correctly set.
4175
4176\S{writing-move-anim} Animating game moves
4177
4178A number of puzzle types benefit from a quick animation of each move
4179you make.
4180
4181For some games, such as Fifteen, this is particularly easy. Whenever
4182\cw{redraw()} is called with \c{oldstate} non-\cw{NULL}, Fifteen
4183simply compares the position of each tile in the two game states,
4184and if the tile is not in the same place then it draws it some
4185fraction of the way from its old position to its new position. This
4186method copes automatically with undo.
4187
4188Other games are less obvious. In Sixteen, for example, you can't
4189just draw each tile a fraction of the way from its old to its new
4190position: if you did that, the end tile would zip very rapidly past
4191all the others to get to the other end and that would look silly.
4192(Worse, it would look inconsistent if the end tile was drawn on top
4193going one way and on the bottom going the other way.)
4194
4195A useful trick here is to define a field or two in the game state
4196that indicates what the last move was.
4197
4198\b Add a \q{last move} field to the \c{game_state} (or two or more
4199fields if the move is complex enough to need them).
4200
4201\b \cw{new_game()} initialises this field to a null value for a new
4202game state.
4203
4204\b \cw{execute_move()} sets up the field to reflect the move it just
4205performed.
4206
4207\b \cw{redraw()} now needs to examine its \c{dir} parameter. If
4208\c{dir} is positive, it determines the move being animated by
4209looking at the last-move field in \c{newstate}; but if \c{dir} is
4210negative, it has to look at the last-move field in \c{oldstate}, and
4211invert whatever move it finds there.
4212
4213Note also that Sixteen needs to store the \e{direction} of the move,
4214because you can't quite determine it by examining the row or column
4215in question. You can in almost all cases, but when the row is
4216precisely two squares long it doesn't work since a move in either
4217direction looks the same. (You could argue that since moving a
42182-element row left and right has the same effect, it doesn't matter
4219which one you animate; but in fact it's very disorienting to click
4220the arrow left and find the row moving right, and almost as bad to
4221undo a move to the right and find the game animating \e{another}
4222move to the right.)
4223
4224\S{writing-conditional-anim} Animating drag operations
4225
4226In Untangle, moves are made by dragging a node from an old position
4227to a new position. Therefore, at the time when the move is initially
4228made, it should not be animated, because the node has already been
4229dragged to the right place and doesn't need moving there. However,
4230it's nice to animate the same move if it's later undone or redone.
4231This requires a bit of fiddling.
4232
4233The obvious approach is to have a flag in the \c{game_ui} which
4234inhibits move animation, and to set that flag in
4235\cw{interpret_move()}. The question is, when would the flag be reset
4236again? The obvious place to do so is \cw{changed_state()}, which
4237will be called once per move. But it will be called \e{before}
4238\cw{anim_length()}, so if it resets the flag then \cw{anim_length()}
4239will never see the flag set at all.
4240
4241The solution is to have \e{two} flags in a queue.
4242
4243\b Define two flags in \c{game_ui}; let's call them \q{current} and
4244\q{next}.
4245
4246\b Set both to \cw{FALSE} in \c{new_ui()}.
4247
4248\b When a drag operation completes in \cw{interpret_move()}, set the
4249\q{next} flag to \cw{TRUE}.
4250
4251\b Every time \cw{changed_state()} is called, set the value of
4252\q{current} to the value in \q{next}, and then set the value of
4253\q{next} to \cw{FALSE}.
4254
4255\b That way, \q{current} will be \cw{TRUE} \e{after} a call to
4256\cw{changed_state()} if and only if that call to
4257\cw{changed_state()} was the result of a drag operation processed by
4258\cw{interpret_move()}. Any other call to \cw{changed_state()}, due
4259to an Undo or a Redo or a Restart or a Solve, will leave \q{current}
4260\cw{FALSE}.
4261
4262\b So now \cw{anim_length()} can request a move animation if and
4263only if the \q{current} flag is \e{not} set.
4264
4265\S{writing-cheating} Inhibiting the victory flash when Solve is used
4266
4267Many games flash when you complete them, as a visual congratulation
4268for having got to the end of the puzzle. It often seems like a good
4269idea to disable that flash when the puzzle is brought to a solved
4270state by means of the Solve operation.
4271
4272This is easily done:
4273
4274\b Add a \q{cheated} flag to the \c{game_state}.
4275
4276\b Set this flag to \cw{FALSE} in \cw{new_game()}.
4277
4278\b Have \cw{solve()} return a move description string which clearly
4279identifies the move as a solve operation.
4280
4281\b Have \cw{execute_move()} respond to that clear identification by
4282setting the \q{cheated} flag in the returned \c{game_state}. The
4283flag will then be propagated to all subsequent game states, even if
4284the user continues fiddling with the game after it is solved.
4285
4286\b \cw{flash_length()} now returns non-zero if \c{oldstate} is not
4287completed and \c{newstate} is, \e{and} neither state has the
4288\q{cheated} flag set.
4289
4290\H{writing-testing} Things to test once your puzzle is written
4291
4292Puzzle implementations written in this framework are self-testing as
4293far as I could make them.
4294
4295Textual game and move descriptions, for example, are generated and
4296parsed as part of the normal process of play. Therefore, if you can
4297make moves in the game \e{at all} you can be reasonably confident
4298that the mid-end serialisation interface will function correctly and
4299you will be able to save your game. (By contrast, if I'd stuck with
4300a single \cw{make_move()} function performing the jobs of both
4301\cw{interpret_move()} and \cw{execute_move()}, and had separate
4302functions to encode and decode a game state in string form, then
4303those functions would not be used during normal play; so they could
4304have been completely broken, and you'd never know it until you tried
4305to save the game \dash which would have meant you'd have to test
4306game saving \e{extensively} and make sure to test every possible
4307type of game state. As an added bonus, doing it the way I did leads
4308to smaller save files.)
4309
4310There is one exception to this, which is the string encoding of the
4311\c{game_ui}. Most games do not store anything permanent in the
4312\c{game_ui}, and hence do not need to put anything in its encode and
4313decode functions; but if there is anything in there, you do need to
4314test game loading and saving to ensure those functions work
4315properly.
4316
4317It's also worth testing undo and redo of all operations, to ensure
4318that the redraw and the animations (if any) work properly. Failing
4319to animate undo properly seems to be a common error.
4320
4321Other than that, just use your common sense.