Require games to accept new_ui(NULL) if they have preferences.

This will be necessary in the next commit, so that the midend can make
a game_ui out of nothing in order to store preferences in it.

The only game actually affected by this requirement is Pearl, which
has a preference (GUI style) and also allocates space based on the
game_state's grid size to store the coordinates of a path being
dragged, so if there is no game_state, it can't do the latter - which
is OK, because it also won't be expected to.

1 files changed, 15 insertions, 3 deletions

diff --git a/devel.but b/devel.but
index 68a0df2..2459863 100644
--- a/devel.but
+++ b/devel.but
@@ -732,6 +732,10 @@ with this function.
 If there are no user preferences, you can set both this function
 pointer and \c{set_prefs} to \cw{NULL}.
 
+If you implement these functions, you must also ensure that your
+game's \cw{new_ui()} function can be called with a null \c{game_state}
+pointer. (See \k{backend-new-ui}.)
+
 In every \c{config_item} returned from this function, you must set an
 additional field beyond the ones described in \k{backend-configure}:
 
@@ -928,9 +932,17 @@ allocations contained within it.
 \c game_ui *(*new_ui)(const game_state *state);
 
 This function allocates and returns a new \c{game_ui} structure for
-playing a particular puzzle. It is passed a pointer to the initial
-\c{game_state}, in case it needs to refer to that when setting up
-the initial values for the new game.
+playing a particular puzzle.
+
+Usually, this function is passed a pointer to the initial
+\c{game_state}, in case it needs to refer to that when setting up the
+initial values for the new game.
+
+However, if the puzzle defines \c{get_prefs()} and \c{set_prefs()}
+functions, then this function may also be called with
+\cw{state==NULL}. In this situation it must still allocate a
+\c{game_ui} which can be used by \c{get_prefs()} and \c{set_prefs()},
+although it need not be usable for actually playing a game.
 
 \S{backend-free-ui} \cw{free_ui()}