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