There are a number of function call interfaces within Puzzles, and
this guide will discuss each one in a chapter of its own. After
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
\C{backend} Interface to the back end
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
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()}
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,
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
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)}
\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
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
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.
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
\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
Most front ends accomplish this by having the drawing routines draw
on a stored bitmap rather than directly on the window, and copying
\S{utils-truefalse} \cw{TRUE} and \cw{FALSE}
The main Puzzles header file defines the macros \cw{TRUE} and
\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()}
\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}.
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
Once your source file is building, you can move on to the fun bit.
\S{writing-generation} Puzzle generation
~mdw / sgt / puzzles / commitdiff