There are a number of function call interfaces within Puzzles, and
this guide will discuss each one in a chapter of its own. After
-that, there will be a section about how to design new games, with
-some general design thoughts and tips.
+that, (\k{writing}) discusses how to design new games, with some
+general design thoughts and tips.
\C{backend} Interface to the back end
\b On platforms such as MacOS X and PalmOS, which build all the
puzzles into a single monolithic binary, the game structure in each
back end must have a different name, and there's a helper module
-\c{list.c} which contains a complete list of those game structures.
+\c{list.c} (constructed automatically by the same Perl script that
+builds the \cw{Makefile}s) which contains a complete list of those
+game structures.
On the latter type of platform, source files may assume that the
preprocessor symbol \c{COMBINED} has been defined. Thus, the usual
sufficient to give the grid dimensions and the location and contents
of the clue squares. (Indeed, one might very easily type in a puzzle
out of a newspaper without \e{knowing} what its difficulty level is
-in Solo's terminology.) Therefore. Solo's \cw{encode_params()} only
+in Solo's terminology.) Therefore, Solo's \cw{encode_params()} only
encodes the difficulty level if \c{full} is set.
\S{backend-decode-params} \cw{decode_params()}
cursor, for example, can be reset to a default position on reloading
the game without impacting the user experience. If the user should
somehow manage to save a game while a mouse drag was in progress,
-then discarding that mouse drag would be an outright \e{feature},
+then discarding that mouse drag would be an outright \e{feature}.
A typical thing that \e{would} be worth encoding in this function is
the Mines death counter: it's in the \c{game_ui} rather than the
\dt \cw{BUTTON_BEATS(x,y)}
-\dd Given any \cw{x} and \cw{y} from the set (\cw{LEFT_BUTTON},
-\cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}), this macro evaluates to a
+\dd Given any \cw{x} and \cw{y} from the set \{\cw{LEFT_BUTTON},
+\cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}\}, this macro evaluates to a
bit flag which indicates that when buttons \cw{x} and \cw{y} are
both pressed simultaneously, the mid-end should consider \cw{x} to
have priority. (In the absence of any such flags, the mid-end will
This is likely not to be what you want. If a puzzle needs randomness
in the middle of play, it's likely to be more sensible to store some
-sort of random state within the \e{game_state}, so that the random
+sort of random state within the \c{game_state}, so that the random
numbers are tied to the particular game state and hence the player
can't simply keep undoing their move until they get numbers they
like better.
\e{Puzzles' redraw functions may assume that the surface they draw
on is persistent}. It is the responsibility of every front end to
preserve the puzzle's window contents in the face of GUI window
-expose issues and similar. It is not permissible to request the back
-end redraw any part of a window that it has already drawn, unless
-something has actually changed as a result of making moves in the
-puzzle.
+expose issues and similar. It is not permissible to request that the
+back end redraw any part of a window that it has already drawn,
+unless something has actually changed as a result of making moves in
+the puzzle.
Most front ends accomplish this by having the drawing routines draw
on a stored bitmap rather than directly on the window, and copying
\c void (*draw_update)(void *handle, int x, int y, int w, int h);
-This function behaves exactly like the back end \cw{draw_text()}
-function; see \k{drawing-draw-text}.
+This function behaves exactly like the back end \cw{draw_update()}
+function; see \k{drawing-draw-update}.
An implementation of this API which only supports printing is
permitted to define this function pointer to be \cw{NULL} rather
Similarly, \c{ym} and \c{yc} specify the vertical position of the
puzzle as a function of the page height: the page height times
-\c{xm}, plus \c{xc} millimetres, equals the desired distance from
+\c{ym}, plus \c{yc} millimetres, equals the desired distance from
the top of the page to the top of the puzzle.
(This unwieldy mechanism is required because not all printing
\c extern const int gamecount;
\c{gamelist} will be an array of \c{gamecount} game structures,
-declared in the source module \c{list.c}. The application should
-search that array for the game it wants, probably by reaching into
-each game structure and looking at its \c{name} field.
+declared in the automatically constructed source module \c{list.c}.
+The application should search that array for the game it wants,
+probably by reaching into each game structure and looking at its
+\c{name} field.
}
\S{utils-truefalse} \cw{TRUE} and \cw{FALSE}
The main Puzzles header file defines the macros \cw{TRUE} and
-\cw{FALSE}, which are used throughout the code in place of 0 and 1
-to indicate that the values are in a boolean context. For code base
-consistency, I'd prefer it if submissions of new code followed this
-convention as well.
+\cw{FALSE}, which are used throughout the code in place of 1 and 0
+(respectively) to indicate that the values are in a boolean context.
+For code base consistency, I'd prefer it if submissions of new code
+followed this convention as well.
\S{utils-maxmin} \cw{max()} and \cw{min()}
created automatically by the script \c{mkfiles.pl}, from the file
called \c{Recipe}. Edit \c{Recipe}, and then re-run \c{mkfiles.pl}.
+Also, don't forget to add your puzzle to \c{list.c}: if you don't,
+then it will still run fine on platforms which build each puzzle
+separately, but Mac OS X and other monolithic platforms will not
+include your new puzzle in their single binary.
+
Once your source file is building, you can move on to the fun bit.
\S{writing-generation} Puzzle generation
~mdw / sgt / puzzles / blobdiff