chiark / gitweb /
Return error messages as 'const char *', not 'char *'.
[sgt-puzzles.git] / midend.c
1 /*
2  * midend.c: general middle fragment sitting between the
3  * platform-specific front end and game-specific back end.
4  * Maintains a move list, takes care of Undo and Redo commands, and
5  * processes standard keystrokes for undo/redo/new/quit.
6  */
7
8 #include <stdio.h>
9 #include <string.h>
10 #include <assert.h>
11 #include <stdlib.h>
12 #include <ctype.h>
13
14 #include "puzzles.h"
15
16 enum { DEF_PARAMS, DEF_SEED, DEF_DESC };   /* for midend_game_id_int */
17
18 enum { NEWGAME, MOVE, SOLVE, RESTART };/* for midend_state_entry.movetype */
19
20 #define special(type) ( (type) != MOVE )
21
22 struct midend_state_entry {
23     game_state *state;
24     char *movestr;
25     int movetype;
26 };
27
28 struct midend {
29     frontend *frontend;
30     random_state *random;
31     const game *ourgame;
32
33     struct preset_menu *preset_menu;
34     char **encoded_presets; /* for midend_which_preset to check against */
35     int n_encoded_presets;
36
37     /*
38      * `desc' and `privdesc' deserve a comment.
39      * 
40      * `desc' is the game description as presented to the user when
41      * they ask for Game -> Specific. `privdesc', if non-NULL, is a
42      * different game description used to reconstruct the initial
43      * game_state when de-serialising. If privdesc is NULL, `desc'
44      * is used for both.
45      * 
46      * For almost all games, `privdesc' is NULL and never used. The
47      * exception (as usual) is Mines: the initial game state has no
48      * squares open at all, but after the first click `desc' is
49      * rewritten to describe a game state with an initial click and
50      * thus a bunch of squares open. If we used that desc to
51      * serialise and deserialise, then the initial game state after
52      * deserialisation would look unlike the initial game state
53      * beforehand, and worse still execute_move() might fail on the
54      * attempted first click. So `privdesc' is also used in this
55      * case, to provide a game description describing the same
56      * fixed mine layout _but_ no initial click. (These game IDs
57      * may also be typed directly into Mines if you like.)
58      */
59     char *desc, *privdesc, *seedstr;
60     char *aux_info;
61     enum { GOT_SEED, GOT_DESC, GOT_NOTHING } genmode;
62
63     int nstates, statesize, statepos;
64     struct midend_state_entry *states;
65
66     char *newgame_undo_buf;
67     int newgame_undo_len, newgame_undo_size;
68
69     game_params *params, *curparams;
70     game_drawstate *drawstate;
71     game_ui *ui;
72
73     game_state *oldstate;
74     float anim_time, anim_pos;
75     float flash_time, flash_pos;
76     int dir;
77
78     int timing;
79     float elapsed;
80     char *laststatus;
81
82     drawing *drawing;
83
84     int pressed_mouse_button;
85
86     int preferred_tilesize, tilesize, winwidth, winheight;
87
88     void (*game_id_change_notify_function)(void *);
89     void *game_id_change_notify_ctx;
90 };
91
92 #define ensure(me) do { \
93     if ((me)->nstates >= (me)->statesize) { \
94         (me)->statesize = (me)->nstates + 128; \
95         (me)->states = sresize((me)->states, (me)->statesize, \
96                                struct midend_state_entry); \
97     } \
98 } while (0)
99
100 /*
101  * Structure storing all the decoded data from reading a serialised
102  * game. We keep it in one of these while we check its sanity, and
103  * only once we're completely satisfied do we install it all in the
104  * midend structure proper.
105  */
106 struct deserialise_data {
107     char *seed, *parstr, *desc, *privdesc;
108     char *auxinfo, *uistr, *cparstr;
109     float elapsed;
110     game_params *params, *cparams;
111     game_ui *ui;
112     struct midend_state_entry *states;
113     int nstates, statepos;
114 };
115
116 /*
117  * Forward reference.
118  */
119 static const char *midend_deserialise_internal(
120     midend *me, int (*read)(void *ctx, void *buf, int len), void *rctx,
121     char *(*check)(void *ctx, midend *, const struct deserialise_data *),
122     void *cctx);
123
124 void midend_reset_tilesize(midend *me)
125 {
126     me->preferred_tilesize = me->ourgame->preferred_tilesize;
127     {
128         /*
129          * Allow an environment-based override for the default tile
130          * size by defining a variable along the lines of
131          * `NET_TILESIZE=15'.
132          */
133
134         char buf[80], *e;
135         int j, k, ts;
136
137         sprintf(buf, "%s_TILESIZE", me->ourgame->name);
138         for (j = k = 0; buf[j]; j++)
139             if (!isspace((unsigned char)buf[j]))
140                 buf[k++] = toupper((unsigned char)buf[j]);
141         buf[k] = '\0';
142         if ((e = getenv(buf)) != NULL && sscanf(e, "%d", &ts) == 1 && ts > 0)
143             me->preferred_tilesize = ts;
144     }
145 }
146
147 midend *midend_new(frontend *fe, const game *ourgame,
148                    const drawing_api *drapi, void *drhandle)
149 {
150     midend *me = snew(midend);
151     void *randseed;
152     int randseedsize;
153
154     get_random_seed(&randseed, &randseedsize);
155
156     me->frontend = fe;
157     me->ourgame = ourgame;
158     me->random = random_new(randseed, randseedsize);
159     me->nstates = me->statesize = me->statepos = 0;
160     me->states = NULL;
161     me->newgame_undo_buf = NULL;
162     me->newgame_undo_size = me->newgame_undo_len = 0;
163     me->params = ourgame->default_params();
164     me->game_id_change_notify_function = NULL;
165     me->game_id_change_notify_ctx = NULL;
166
167     /*
168      * Allow environment-based changing of the default settings by
169      * defining a variable along the lines of `NET_DEFAULT=25x25w'
170      * in which the value is an encoded parameter string.
171      */
172     {
173         char buf[80], *e;
174         int j, k;
175         sprintf(buf, "%s_DEFAULT", me->ourgame->name);
176         for (j = k = 0; buf[j]; j++)
177             if (!isspace((unsigned char)buf[j]))
178                 buf[k++] = toupper((unsigned char)buf[j]);
179         buf[k] = '\0';
180         if ((e = getenv(buf)) != NULL)
181             me->ourgame->decode_params(me->params, e);
182     }
183     me->curparams = NULL;
184     me->desc = me->privdesc = NULL;
185     me->seedstr = NULL;
186     me->aux_info = NULL;
187     me->genmode = GOT_NOTHING;
188     me->drawstate = NULL;
189     me->oldstate = NULL;
190     me->preset_menu = NULL;
191     me->anim_time = me->anim_pos = 0.0F;
192     me->flash_time = me->flash_pos = 0.0F;
193     me->dir = 0;
194     me->ui = NULL;
195     me->pressed_mouse_button = 0;
196     me->laststatus = NULL;
197     me->timing = FALSE;
198     me->elapsed = 0.0F;
199     me->tilesize = me->winwidth = me->winheight = 0;
200     if (drapi)
201         me->drawing = drawing_new(drapi, me, drhandle);
202     else
203         me->drawing = NULL;
204
205     midend_reset_tilesize(me);
206
207     sfree(randseed);
208
209     return me;
210 }
211
212 const game *midend_which_game(midend *me)
213 {
214     return me->ourgame;
215 }
216
217 static void midend_purge_states(midend *me)
218 {
219     while (me->nstates > me->statepos) {
220         me->ourgame->free_game(me->states[--me->nstates].state);
221         if (me->states[me->nstates].movestr)
222             sfree(me->states[me->nstates].movestr);
223     }
224 }
225
226 static void midend_free_game(midend *me)
227 {
228     while (me->nstates > 0) {
229         me->nstates--;
230         me->ourgame->free_game(me->states[me->nstates].state);
231         sfree(me->states[me->nstates].movestr);
232     }
233
234     if (me->drawstate)
235         me->ourgame->free_drawstate(me->drawing, me->drawstate);
236 }
237
238 static void midend_free_preset_menu(midend *me, struct preset_menu *menu)
239 {
240     if (menu) {
241         int i;
242         for (i = 0; i < menu->n_entries; i++) {
243             sfree(menu->entries[i].title);
244             if (menu->entries[i].params)
245                 me->ourgame->free_params(menu->entries[i].params);
246             midend_free_preset_menu(me, menu->entries[i].submenu);
247         }
248         sfree(menu->entries);
249         sfree(menu);
250     }
251 }
252
253 void midend_free(midend *me)
254 {
255     midend_free_game(me);
256
257     if (me->drawing)
258         drawing_free(me->drawing);
259     random_free(me->random);
260     sfree(me->newgame_undo_buf);
261     sfree(me->states);
262     sfree(me->desc);
263     sfree(me->privdesc);
264     sfree(me->seedstr);
265     sfree(me->aux_info);
266     me->ourgame->free_params(me->params);
267     midend_free_preset_menu(me, me->preset_menu);
268     if (me->ui)
269         me->ourgame->free_ui(me->ui);
270     if (me->curparams)
271         me->ourgame->free_params(me->curparams);
272     sfree(me->laststatus);
273     sfree(me);
274 }
275
276 static void midend_size_new_drawstate(midend *me)
277 {
278     /*
279      * Don't even bother, if we haven't worked out our tile size
280      * anyway yet.
281      */
282     if (me->tilesize > 0) {
283         me->ourgame->compute_size(me->params, me->tilesize,
284                                   &me->winwidth, &me->winheight);
285         me->ourgame->set_size(me->drawing, me->drawstate,
286                               me->params, me->tilesize);
287     }
288 }
289
290 void midend_size(midend *me, int *x, int *y, int user_size)
291 {
292     int min, max;
293     int rx, ry;
294
295     /*
296      * We can't set the size on the same drawstate twice. So if
297      * we've already sized one drawstate, we must throw it away and
298      * create a new one.
299      */
300     if (me->drawstate && me->tilesize > 0) {
301         me->ourgame->free_drawstate(me->drawing, me->drawstate);
302         me->drawstate = me->ourgame->new_drawstate(me->drawing,
303                                                    me->states[0].state);
304     }
305
306     /*
307      * Find the tile size that best fits within the given space. If
308      * `user_size' is TRUE, we must actually find the _largest_ such
309      * tile size, in order to get as close to the user's explicit
310      * request as possible; otherwise, we bound above at the game's
311      * preferred tile size, so that the game gets what it wants
312      * provided that this doesn't break the constraint from the
313      * front-end (which is likely to be a screen size or similar).
314      */
315     if (user_size) {
316         max = 1;
317         do {
318             max *= 2;
319             me->ourgame->compute_size(me->params, max, &rx, &ry);
320         } while (rx <= *x && ry <= *y);
321     } else
322         max = me->preferred_tilesize + 1;
323     min = 1;
324
325     /*
326      * Now binary-search between min and max. We're looking for a
327      * boundary rather than a value: the point at which tile sizes
328      * stop fitting within the given dimensions. Thus, we stop when
329      * max and min differ by exactly 1.
330      */
331     while (max - min > 1) {
332         int mid = (max + min) / 2;
333         me->ourgame->compute_size(me->params, mid, &rx, &ry);
334         if (rx <= *x && ry <= *y)
335             min = mid;
336         else
337             max = mid;
338     }
339
340     /*
341      * Now `min' is a valid size, and `max' isn't. So use `min'.
342      */
343
344     me->tilesize = min;
345     if (user_size)
346         /* If the user requested a change in size, make it permanent. */
347         me->preferred_tilesize = me->tilesize;
348     midend_size_new_drawstate(me);
349     *x = me->winwidth;
350     *y = me->winheight;
351 }
352
353 int midend_tilesize(midend *me) { return me->tilesize; }
354
355 void midend_set_params(midend *me, game_params *params)
356 {
357     me->ourgame->free_params(me->params);
358     me->params = me->ourgame->dup_params(params);
359 }
360
361 game_params *midend_get_params(midend *me)
362 {
363     return me->ourgame->dup_params(me->params);
364 }
365
366 static void midend_set_timer(midend *me)
367 {
368     me->timing = (me->ourgame->is_timed &&
369                   me->ourgame->timing_state(me->states[me->statepos-1].state,
370                                             me->ui));
371     if (me->timing || me->flash_time || me->anim_time)
372         activate_timer(me->frontend);
373     else
374         deactivate_timer(me->frontend);
375 }
376
377 void midend_force_redraw(midend *me)
378 {
379     if (me->drawstate)
380         me->ourgame->free_drawstate(me->drawing, me->drawstate);
381     me->drawstate = me->ourgame->new_drawstate(me->drawing,
382                                                me->states[0].state);
383     midend_size_new_drawstate(me);
384     midend_redraw(me);
385 }
386
387 static void newgame_serialise_write(void *ctx, void *buf, int len)
388 {
389     midend *const me = ctx;
390     int new_len;
391
392     assert(len < INT_MAX - me->newgame_undo_len);
393     new_len = me->newgame_undo_len + len;
394     if (new_len > me->newgame_undo_size) {
395         me->newgame_undo_size = new_len + new_len / 4 + 1024;
396         me->newgame_undo_buf = sresize(me->newgame_undo_buf,
397                                        me->newgame_undo_size, char);
398     }
399     memcpy(me->newgame_undo_buf + me->newgame_undo_len, buf, len);
400     me->newgame_undo_len = new_len;
401 }
402
403 void midend_new_game(midend *me)
404 {
405     me->newgame_undo_len = 0;
406     midend_serialise(me, newgame_serialise_write, me);
407
408     midend_stop_anim(me);
409     midend_free_game(me);
410
411     assert(me->nstates == 0);
412
413     if (me->genmode == GOT_DESC) {
414         me->genmode = GOT_NOTHING;
415     } else {
416         random_state *rs;
417
418         if (me->genmode == GOT_SEED) {
419             me->genmode = GOT_NOTHING;
420         } else {
421             /*
422              * Generate a new random seed. 15 digits comes to about
423              * 48 bits, which should be more than enough.
424              * 
425              * I'll avoid putting a leading zero on the number,
426              * just in case it confuses anybody who thinks it's
427              * processed as an integer rather than a string.
428              */
429             char newseed[16];
430             int i;
431             newseed[15] = '\0';
432             newseed[0] = '1' + (char)random_upto(me->random, 9);
433             for (i = 1; i < 15; i++)
434                 newseed[i] = '0' + (char)random_upto(me->random, 10);
435             sfree(me->seedstr);
436             me->seedstr = dupstr(newseed);
437
438             if (me->curparams)
439                 me->ourgame->free_params(me->curparams);
440             me->curparams = me->ourgame->dup_params(me->params);
441         }
442
443         sfree(me->desc);
444         sfree(me->privdesc);
445         sfree(me->aux_info);
446         me->aux_info = NULL;
447
448         rs = random_new(me->seedstr, strlen(me->seedstr));
449         /*
450          * If this midend has been instantiated without providing a
451          * drawing API, it is non-interactive. This means that it's
452          * being used for bulk game generation, and hence we should
453          * pass the non-interactive flag to new_desc.
454          */
455         me->desc = me->ourgame->new_desc(me->curparams, rs,
456                                          &me->aux_info, (me->drawing != NULL));
457         me->privdesc = NULL;
458         random_free(rs);
459     }
460
461     ensure(me);
462
463     /*
464      * It might seem a bit odd that we're using me->params to
465      * create the initial game state, rather than me->curparams
466      * which is better tailored to this specific game and which we
467      * always know.
468      * 
469      * It's supposed to be an invariant in the midend that
470      * me->params and me->curparams differ in no aspect that is
471      * important after generation (i.e. after new_desc()). By
472      * deliberately passing the _less_ specific of these two
473      * parameter sets, we provoke play-time misbehaviour in the
474      * case where a game has failed to encode a play-time parameter
475      * in the non-full version of encode_params().
476      */
477     me->states[me->nstates].state =
478         me->ourgame->new_game(me, me->params, me->desc);
479
480     /*
481      * As part of our commitment to self-testing, test the aux
482      * string to make sure nothing ghastly went wrong.
483      */
484     if (me->ourgame->can_solve && me->aux_info) {
485         game_state *s;
486         const char *msg;
487         char *movestr;
488
489         msg = NULL;
490         movestr = me->ourgame->solve(me->states[0].state,
491                                      me->states[0].state,
492                                      me->aux_info, &msg);
493         assert(movestr && !msg);
494         s = me->ourgame->execute_move(me->states[0].state, movestr);
495         assert(s);
496         me->ourgame->free_game(s);
497         sfree(movestr);
498     }
499
500     me->states[me->nstates].movestr = NULL;
501     me->states[me->nstates].movetype = NEWGAME;
502     me->nstates++;
503     me->statepos = 1;
504     me->drawstate = me->ourgame->new_drawstate(me->drawing,
505                                                me->states[0].state);
506     midend_size_new_drawstate(me);
507     me->elapsed = 0.0F;
508     me->flash_pos = me->flash_time = 0.0F;
509     me->anim_pos = me->anim_time = 0.0F;
510     if (me->ui)
511         me->ourgame->free_ui(me->ui);
512     me->ui = me->ourgame->new_ui(me->states[0].state);
513     midend_set_timer(me);
514     me->pressed_mouse_button = 0;
515
516     if (me->game_id_change_notify_function)
517         me->game_id_change_notify_function(me->game_id_change_notify_ctx);
518 }
519
520 int midend_can_undo(midend *me)
521 {
522     return (me->statepos > 1 || me->newgame_undo_len);
523 }
524
525 int midend_can_redo(midend *me)
526 {
527     return (me->statepos < me->nstates);
528 }
529
530 struct newgame_undo_deserialise_read_ctx {
531     midend *me;
532     int len, pos;
533 };
534
535 static int newgame_undo_deserialise_read(void *ctx, void *buf, int len)
536 {
537     struct newgame_undo_deserialise_read_ctx *const rctx = ctx;
538     midend *const me = rctx->me;
539
540     int use = min(len, rctx->len - rctx->pos);
541     memcpy(buf, me->newgame_undo_buf + rctx->pos, use);
542     rctx->pos += use;
543     return use;
544 }
545
546 struct newgame_undo_deserialise_check_ctx {
547     int refused;
548 };
549
550 static char *newgame_undo_deserialise_check(
551     void *vctx, midend *me, const struct deserialise_data *data)
552 {
553     struct newgame_undo_deserialise_check_ctx *ctx =
554         (struct newgame_undo_deserialise_check_ctx *)vctx;
555     char *old, *new;
556
557     /*
558      * Undoing a New Game operation is only permitted if it doesn't
559      * change the game parameters. The point of having the ability at
560      * all is to recover from the momentary finger error of having hit
561      * the 'n' key (perhaps in place of some other nearby key), or hit
562      * the New Game menu item by mistake when aiming for the adjacent
563      * Restart; in both those situations, the game params are the same
564      * before and after the new-game operation.
565      *
566      * In principle, we could generalise this so that _any_ call to
567      * midend_new_game could be undone, but that would need all front
568      * ends to be alert to the possibility that any keystroke passed
569      * to midend_process_key might (if it turns out to have been one
570      * of the synonyms for undo, which the frontend doesn't
571      * necessarily check for) have various knock-on effects like
572      * needing to select a different preset in the game type menu, or
573      * even resizing the window. At least for the moment, it's easier
574      * not to do that, and to simply disallow any newgame-undo that is
575      * disruptive in either of those ways.
576      *
577      * We check both params and cparams, to be as safe as possible.
578      */
579
580     old = me->ourgame->encode_params(me->params, TRUE);
581     new = me->ourgame->encode_params(data->params, TRUE);
582     if (strcmp(old, new)) {
583         /* Set a flag to distinguish this deserialise failure
584          * from one due to faulty decoding */
585         ctx->refused = TRUE;
586         return "Undoing this new-game operation would change params";
587     }
588
589     old = me->ourgame->encode_params(me->curparams, TRUE);
590     new = me->ourgame->encode_params(data->cparams, TRUE);
591     if (strcmp(old, new)) {
592         ctx->refused = TRUE;
593         return "Undoing this new-game operation would change params";
594     }
595
596     /*
597      * Otherwise, fine, go ahead.
598      */
599     return NULL;
600 }
601
602 static int midend_undo(midend *me)
603 {
604     const char *deserialise_error;
605
606     if (me->statepos > 1) {
607         if (me->ui)
608             me->ourgame->changed_state(me->ui,
609                                        me->states[me->statepos-1].state,
610                                        me->states[me->statepos-2].state);
611         me->statepos--;
612         me->dir = -1;
613         return 1;
614     } else if (me->newgame_undo_len) {
615         /* This undo cannot be undone with redo */
616         struct newgame_undo_deserialise_read_ctx rctx;
617         struct newgame_undo_deserialise_check_ctx cctx;
618         rctx.me = me;
619         rctx.len = me->newgame_undo_len; /* copy for reentrancy safety */
620         rctx.pos = 0;
621         cctx.refused = FALSE;
622         deserialise_error = midend_deserialise_internal(
623             me, newgame_undo_deserialise_read, &rctx,
624             newgame_undo_deserialise_check, &cctx);
625         if (cctx.refused) {
626             /*
627              * Our post-deserialisation check shows that we can't use
628              * this saved game after all. (deserialise_error will
629              * contain the dummy error message generated by our check
630              * function, which we ignore.)
631              */
632             return 0;
633         } else {
634             /*
635              * There should never be any _other_ deserialisation
636              * error, because this serialised data has been held in
637              * our memory since it was created, and hasn't had any
638              * opportunity to be corrupted on disk, accidentally
639              * replaced by the wrong file, etc., by user error.
640              */
641             assert(!deserialise_error);
642             return 1;
643         }
644     } else
645         return 0;
646 }
647
648 static int midend_redo(midend *me)
649 {
650     if (me->statepos < me->nstates) {
651         if (me->ui)
652             me->ourgame->changed_state(me->ui,
653                                        me->states[me->statepos-1].state,
654                                        me->states[me->statepos].state);
655         me->statepos++;
656         me->dir = +1;
657         return 1;
658     } else
659         return 0;
660 }
661
662 static void midend_finish_move(midend *me)
663 {
664     float flashtime;
665
666     /*
667      * We do not flash if the later of the two states is special.
668      * This covers both forward Solve moves and backward (undone)
669      * Restart moves.
670      */
671     if ((me->oldstate || me->statepos > 1) &&
672         ((me->dir > 0 && !special(me->states[me->statepos-1].movetype)) ||
673          (me->dir < 0 && me->statepos < me->nstates &&
674           !special(me->states[me->statepos].movetype)))) {
675         flashtime = me->ourgame->flash_length(me->oldstate ? me->oldstate :
676                                               me->states[me->statepos-2].state,
677                                               me->states[me->statepos-1].state,
678                                               me->oldstate ? me->dir : +1,
679                                               me->ui);
680         if (flashtime > 0) {
681             me->flash_pos = 0.0F;
682             me->flash_time = flashtime;
683         }
684     }
685
686     if (me->oldstate)
687         me->ourgame->free_game(me->oldstate);
688     me->oldstate = NULL;
689     me->anim_pos = me->anim_time = 0;
690     me->dir = 0;
691
692     midend_set_timer(me);
693 }
694
695 void midend_stop_anim(midend *me)
696 {
697     if (me->oldstate || me->anim_time != 0) {
698         midend_finish_move(me);
699         midend_redraw(me);
700     }
701 }
702
703 void midend_restart_game(midend *me)
704 {
705     game_state *s;
706
707     assert(me->statepos >= 1);
708     if (me->statepos == 1)
709         return;                        /* no point doing anything at all! */
710
711     /*
712      * During restart, we reconstruct the game from the (public)
713      * game description rather than from states[0], because that
714      * way Mines gets slightly more sensible behaviour (restart
715      * goes to _after_ the first click so you don't have to
716      * remember where you clicked).
717      */
718     s = me->ourgame->new_game(me, me->params, me->desc);
719
720     /*
721      * Now enter the restarted state as the next move.
722      */
723     midend_stop_anim(me);
724     midend_purge_states(me);
725     ensure(me);
726     me->states[me->nstates].state = s;
727     me->states[me->nstates].movestr = dupstr(me->desc);
728     me->states[me->nstates].movetype = RESTART;
729     me->statepos = ++me->nstates;
730     if (me->ui)
731         me->ourgame->changed_state(me->ui,
732                                    me->states[me->statepos-2].state,
733                                    me->states[me->statepos-1].state);
734     me->flash_pos = me->flash_time = 0.0F;
735     midend_finish_move(me);
736     midend_redraw(me);
737     midend_set_timer(me);
738 }
739
740 static int midend_really_process_key(midend *me, int x, int y, int button)
741 {
742     game_state *oldstate =
743         me->ourgame->dup_game(me->states[me->statepos - 1].state);
744     int type = MOVE, gottype = FALSE, ret = 1;
745     float anim_time;
746     game_state *s;
747     char *movestr = NULL;
748
749     if (!IS_UI_FAKE_KEY(button)) {
750         movestr = me->ourgame->interpret_move(
751             me->states[me->statepos-1].state,
752             me->ui, me->drawstate, x, y, button);
753     }
754
755     if (!movestr) {
756         if (button == 'n' || button == 'N' || button == '\x0E' ||
757             button == UI_NEWGAME) {
758             midend_new_game(me);
759             midend_redraw(me);
760             goto done;                 /* never animate */
761         } else if (button == 'u' || button == 'U' ||
762                    button == '\x1A' || button == '\x1F' ||
763                    button == UI_UNDO) {
764             midend_stop_anim(me);
765             type = me->states[me->statepos-1].movetype;
766             gottype = TRUE;
767             if (!midend_undo(me))
768                 goto done;
769         } else if (button == 'r' || button == 'R' ||
770                    button == '\x12' || button == '\x19' ||
771                    button == UI_REDO) {
772             midend_stop_anim(me);
773             if (!midend_redo(me))
774                 goto done;
775         } else if ((button == '\x13' || button == UI_SOLVE) &&
776                    me->ourgame->can_solve) {
777             if (midend_solve(me))
778                 goto done;
779         } else if (button == 'q' || button == 'Q' || button == '\x11' ||
780                    button == UI_QUIT) {
781             ret = 0;
782             goto done;
783         } else
784             goto done;
785     } else {
786         if (movestr == UI_UPDATE)
787             s = me->states[me->statepos-1].state;
788         else {
789             s = me->ourgame->execute_move(me->states[me->statepos-1].state,
790                                           movestr);
791             assert(s != NULL);
792         }
793
794         if (s == me->states[me->statepos-1].state) {
795             /*
796              * make_move() is allowed to return its input state to
797              * indicate that although no move has been made, the UI
798              * state has been updated and a redraw is called for.
799              */
800             midend_redraw(me);
801             midend_set_timer(me);
802             goto done;
803         } else if (s) {
804             midend_stop_anim(me);
805             midend_purge_states(me);
806             ensure(me);
807             assert(movestr != NULL);
808             me->states[me->nstates].state = s;
809             me->states[me->nstates].movestr = movestr;
810             me->states[me->nstates].movetype = MOVE;
811             me->statepos = ++me->nstates;
812             me->dir = +1;
813             if (me->ui)
814                 me->ourgame->changed_state(me->ui,
815                                            me->states[me->statepos-2].state,
816                                            me->states[me->statepos-1].state);
817         } else {
818             goto done;
819         }
820     }
821
822     if (!gottype)
823         type = me->states[me->statepos-1].movetype;
824
825     /*
826      * See if this move requires an animation.
827      */
828     if (special(type) && !(type == SOLVE &&
829                            (me->ourgame->flags & SOLVE_ANIMATES))) {
830         anim_time = 0;
831     } else {
832         anim_time = me->ourgame->anim_length(oldstate,
833                                              me->states[me->statepos-1].state,
834                                              me->dir, me->ui);
835     }
836
837     me->oldstate = oldstate; oldstate = NULL;
838     if (anim_time > 0) {
839         me->anim_time = anim_time;
840     } else {
841         me->anim_time = 0.0;
842         midend_finish_move(me);
843     }
844     me->anim_pos = 0.0;
845
846     midend_redraw(me);
847
848     midend_set_timer(me);
849
850     done:
851     if (oldstate) me->ourgame->free_game(oldstate);
852     return ret;
853 }
854
855 int midend_process_key(midend *me, int x, int y, int button)
856 {
857     int ret = 1;
858
859     /*
860      * Harmonise mouse drag and release messages.
861      * 
862      * Some front ends might accidentally switch from sending, say,
863      * RIGHT_DRAG messages to sending LEFT_DRAG, half way through a
864      * drag. (This can happen on the Mac, for example, since
865      * RIGHT_DRAG is usually done using Command+drag, and if the
866      * user accidentally releases Command half way through the drag
867      * then there will be trouble.)
868      * 
869      * It would be an O(number of front ends) annoyance to fix this
870      * in the front ends, but an O(number of back ends) annoyance
871      * to have each game capable of dealing with it. Therefore, we
872      * fix it _here_ in the common midend code so that it only has
873      * to be done once.
874      * 
875      * The possible ways in which things can go screwy in the front
876      * end are:
877      * 
878      *  - in a system containing multiple physical buttons button
879      *    presses can inadvertently overlap. We can see ABab (caps
880      *    meaning button-down and lowercase meaning button-up) when
881      *    the user had semantically intended AaBb.
882      * 
883      *  - in a system where one button is simulated by means of a
884      *    modifier key and another button, buttons can mutate
885      *    between press and release (possibly during drag). So we
886      *    can see Ab instead of Aa.
887      * 
888      * Definite requirements are:
889      * 
890      *  - button _presses_ must never be invented or destroyed. If
891      *    the user presses two buttons in succession, the button
892      *    presses must be transferred to the backend unchanged. So
893      *    if we see AaBb , that's fine; if we see ABab (the button
894      *    presses inadvertently overlapped) we must somehow
895      *    `correct' it to AaBb.
896      * 
897      *  - every mouse action must end up looking like a press, zero
898      *    or more drags, then a release. This allows back ends to
899      *    make the _assumption_ that incoming mouse data will be
900      *    sane in this regard, and not worry about the details.
901      * 
902      * So my policy will be:
903      * 
904      *  - treat any button-up as a button-up for the currently
905      *    pressed button, or ignore it if there is no currently
906      *    pressed button.
907      * 
908      *  - treat any drag as a drag for the currently pressed
909      *    button, or ignore it if there is no currently pressed
910      *    button.
911      * 
912      *  - if we see a button-down while another button is currently
913      *    pressed, invent a button-up for the first one and then
914      *    pass the button-down through as before.
915      * 
916      * 2005-05-31: An addendum to the above. Some games might want
917      * a `priority order' among buttons, such that if one button is
918      * pressed while another is down then a fixed one of the
919      * buttons takes priority no matter what order they're pressed
920      * in. Mines, in particular, wants to treat a left+right click
921      * like a left click for the benefit of users of other
922      * implementations. So the last of the above points is modified
923      * in the presence of an (optional) button priority order.
924      *
925      * A further addition: we translate certain keyboard presses to
926      * cursor key 'select' buttons, so that a) frontends don't have
927      * to translate these themselves (like they do for CURSOR_UP etc),
928      * and b) individual games don't have to hard-code button presses
929      * of '\n' etc for keyboard-based cursors. The choice of buttons
930      * here could eventually be controlled by a runtime configuration
931      * option.
932      */
933     if (IS_MOUSE_DRAG(button) || IS_MOUSE_RELEASE(button)) {
934         if (me->pressed_mouse_button) {
935             if (IS_MOUSE_DRAG(button)) {
936                 button = me->pressed_mouse_button +
937                     (LEFT_DRAG - LEFT_BUTTON);
938             } else {
939                 button = me->pressed_mouse_button +
940                     (LEFT_RELEASE - LEFT_BUTTON);
941             }
942         } else
943             return ret;                /* ignore it */
944     } else if (IS_MOUSE_DOWN(button) && me->pressed_mouse_button) {
945         /*
946          * If the new button has lower priority than the old one,
947          * don't bother doing this.
948          */
949         if (me->ourgame->flags &
950             BUTTON_BEATS(me->pressed_mouse_button, button))
951             return ret;                /* just ignore it */
952
953         /*
954          * Fabricate a button-up for the previously pressed button.
955          */
956         ret = ret && midend_really_process_key
957             (me, x, y, (me->pressed_mouse_button +
958                         (LEFT_RELEASE - LEFT_BUTTON)));
959     }
960
961     /*
962      * Translate keyboard presses to cursor selection.
963      */
964     if (button == '\n' || button == '\r')
965       button = CURSOR_SELECT;
966     if (button == ' ')
967       button = CURSOR_SELECT2;
968
969     /*
970      * Normalise both backspace characters (8 and 127) to \b. Easier
971      * to do this once, here, than to require all front ends to
972      * carefully generate the same one - now each front end can
973      * generate whichever is easiest.
974      */
975     if (button == '\177')
976         button = '\b';
977
978     /*
979      * Now send on the event we originally received.
980      */
981     ret = ret && midend_really_process_key(me, x, y, button);
982
983     /*
984      * And update the currently pressed button.
985      */
986     if (IS_MOUSE_RELEASE(button))
987         me->pressed_mouse_button = 0;
988     else if (IS_MOUSE_DOWN(button))
989         me->pressed_mouse_button = button;
990
991     return ret;
992 }
993
994 void midend_redraw(midend *me)
995 {
996     assert(me->drawing);
997
998     if (me->statepos > 0 && me->drawstate) {
999         start_draw(me->drawing);
1000         if (me->oldstate && me->anim_time > 0 &&
1001             me->anim_pos < me->anim_time) {
1002             assert(me->dir != 0);
1003             me->ourgame->redraw(me->drawing, me->drawstate, me->oldstate,
1004                                 me->states[me->statepos-1].state, me->dir,
1005                                 me->ui, me->anim_pos, me->flash_pos);
1006         } else {
1007             me->ourgame->redraw(me->drawing, me->drawstate, NULL,
1008                                 me->states[me->statepos-1].state, +1 /*shrug*/,
1009                                 me->ui, 0.0, me->flash_pos);
1010         }
1011         end_draw(me->drawing);
1012     }
1013 }
1014
1015 /*
1016  * Nasty hacky function used to implement the --redo option in
1017  * gtk.c. Only used for generating the puzzles' icons.
1018  */
1019 void midend_freeze_timer(midend *me, float tprop)
1020 {
1021     me->anim_pos = me->anim_time * tprop;
1022     midend_redraw(me);
1023     deactivate_timer(me->frontend);
1024 }
1025
1026 void midend_timer(midend *me, float tplus)
1027 {
1028     int need_redraw = (me->anim_time > 0 || me->flash_time > 0);
1029
1030     me->anim_pos += tplus;
1031     if (me->anim_pos >= me->anim_time ||
1032         me->anim_time == 0 || !me->oldstate) {
1033         if (me->anim_time > 0)
1034             midend_finish_move(me);
1035     }
1036
1037     me->flash_pos += tplus;
1038     if (me->flash_pos >= me->flash_time || me->flash_time == 0) {
1039         me->flash_pos = me->flash_time = 0;
1040     }
1041
1042     if (need_redraw)
1043         midend_redraw(me);
1044
1045     if (me->timing) {
1046         float oldelapsed = me->elapsed;
1047         me->elapsed += tplus;
1048         if ((int)oldelapsed != (int)me->elapsed)
1049             status_bar(me->drawing, me->laststatus ? me->laststatus : "");
1050     }
1051
1052     midend_set_timer(me);
1053 }
1054
1055 float *midend_colours(midend *me, int *ncolours)
1056 {
1057     float *ret;
1058
1059     ret = me->ourgame->colours(me->frontend, ncolours);
1060
1061     {
1062         int i;
1063
1064         /*
1065          * Allow environment-based overrides for the standard
1066          * colours by defining variables along the lines of
1067          * `NET_COLOUR_4=6000c0'.
1068          */
1069
1070         for (i = 0; i < *ncolours; i++) {
1071             char buf[80], *e;
1072             unsigned int r, g, b;
1073             int j, k;
1074
1075             sprintf(buf, "%s_COLOUR_%d", me->ourgame->name, i);
1076             for (j = k = 0; buf[j]; j++)
1077                 if (!isspace((unsigned char)buf[j]))
1078                     buf[k++] = toupper((unsigned char)buf[j]);
1079             buf[k] = '\0';
1080             if ((e = getenv(buf)) != NULL &&
1081                 sscanf(e, "%2x%2x%2x", &r, &g, &b) == 3) {
1082                 ret[i*3 + 0] = r / 255.0F;
1083                 ret[i*3 + 1] = g / 255.0F;
1084                 ret[i*3 + 2] = b / 255.0F;
1085             }
1086         }
1087     }
1088
1089     return ret;
1090 }
1091
1092 struct preset_menu *preset_menu_new(void)
1093 {
1094     struct preset_menu *menu = snew(struct preset_menu);
1095     menu->n_entries = 0;
1096     menu->entries_size = 0;
1097     menu->entries = NULL;
1098     return menu;
1099 }
1100
1101 static struct preset_menu_entry *preset_menu_add(struct preset_menu *menu,
1102                                                  char *title)
1103 {
1104     struct preset_menu_entry *toret;
1105     if (menu->n_entries >= menu->entries_size) {
1106         menu->entries_size = menu->n_entries * 5 / 4 + 10;
1107         menu->entries = sresize(menu->entries, menu->entries_size,
1108                                 struct preset_menu_entry);
1109     }
1110     toret = &menu->entries[menu->n_entries++];
1111     toret->title = title;
1112     toret->params = NULL;
1113     toret->submenu = NULL;
1114     return toret;
1115 }
1116
1117 struct preset_menu *preset_menu_add_submenu(struct preset_menu *parent,
1118                                             char *title)
1119 {
1120     struct preset_menu_entry *entry = preset_menu_add(parent, title);
1121     entry->submenu = preset_menu_new();
1122     return entry->submenu;
1123 }
1124
1125 void preset_menu_add_preset(struct preset_menu *parent,
1126                             char *title, game_params *params)
1127 {
1128     struct preset_menu_entry *entry = preset_menu_add(parent, title);
1129     entry->params = params;
1130 }
1131
1132 game_params *preset_menu_lookup_by_id(struct preset_menu *menu, int id)
1133 {
1134     int i;
1135     game_params *retd;
1136
1137     for (i = 0; i < menu->n_entries; i++) {
1138         if (id == menu->entries[i].id)
1139             return menu->entries[i].params;
1140         if (menu->entries[i].submenu &&
1141             (retd = preset_menu_lookup_by_id(
1142                  menu->entries[i].submenu, id)) != NULL)
1143             return retd;
1144     }
1145
1146     return NULL;
1147 }
1148
1149 static char *preset_menu_add_from_user_env(
1150     midend *me, struct preset_menu *menu, char *p, int top_level)
1151 {
1152     while (*p) {
1153         char *name, *val;
1154         game_params *preset;
1155
1156         name = p;
1157         while (*p && *p != ':') p++;
1158         if (*p) *p++ = '\0';
1159         val = p;
1160         while (*p && *p != ':') p++;
1161         if (*p) *p++ = '\0';
1162
1163         if (!strcmp(val, "#")) {
1164             /*
1165              * Special case: either open a new submenu with the given
1166              * title, or terminate the current submenu.
1167              */
1168             if (*name) {
1169                 struct preset_menu *submenu =
1170                     preset_menu_add_submenu(menu, dupstr(name));
1171                 p = preset_menu_add_from_user_env(me, submenu, p, FALSE);
1172             } else {
1173                 /*
1174                  * If we get a 'close submenu' indication at the top
1175                  * level, there's not much we can do but quietly
1176                  * ignore it.
1177                  */
1178                 if (!top_level)
1179                     return p;
1180             }
1181             continue;
1182         }
1183
1184         preset = me->ourgame->default_params();
1185         me->ourgame->decode_params(preset, val);
1186
1187         if (me->ourgame->validate_params(preset, TRUE)) {
1188             /* Drop this one from the list. */
1189             me->ourgame->free_params(preset);
1190             continue;
1191         }
1192
1193         preset_menu_add_preset(menu, dupstr(name), preset);
1194     }
1195
1196     return p;
1197 }
1198
1199 static void preset_menu_alloc_ids(midend *me, struct preset_menu *menu)
1200 {
1201     int i;
1202
1203     for (i = 0; i < menu->n_entries; i++)
1204         menu->entries[i].id = me->n_encoded_presets++;
1205
1206     for (i = 0; i < menu->n_entries; i++)
1207         if (menu->entries[i].submenu)
1208             preset_menu_alloc_ids(me, menu->entries[i].submenu);
1209 }
1210
1211 static void preset_menu_encode_params(midend *me, struct preset_menu *menu)
1212 {
1213     int i;
1214
1215     for (i = 0; i < menu->n_entries; i++) {
1216         if (menu->entries[i].params) {
1217             me->encoded_presets[menu->entries[i].id] =
1218                 me->ourgame->encode_params(menu->entries[i].params, TRUE);
1219         } else {
1220             preset_menu_encode_params(me, menu->entries[i].submenu);
1221         }
1222     }
1223 }
1224
1225 struct preset_menu *midend_get_presets(midend *me, int *id_limit)
1226 {
1227     int i;
1228
1229     if (me->preset_menu)
1230         return me->preset_menu;
1231
1232 #if 0
1233     /* Expect the game to implement exactly one of the two preset APIs */
1234     assert(me->ourgame->fetch_preset || me->ourgame->preset_menu);
1235     assert(!(me->ourgame->fetch_preset && me->ourgame->preset_menu));
1236 #endif
1237
1238     if (me->ourgame->fetch_preset) {
1239         char *name;
1240         game_params *preset;
1241
1242         /* Simple one-level menu */
1243         assert(!me->ourgame->preset_menu);
1244         me->preset_menu = preset_menu_new();
1245         for (i = 0; me->ourgame->fetch_preset(i, &name, &preset); i++)
1246             preset_menu_add_preset(me->preset_menu, name, preset);
1247
1248     } else {
1249         /* Hierarchical menu provided by the game backend */
1250         me->preset_menu = me->ourgame->preset_menu();
1251     }
1252
1253     {
1254         /*
1255          * Allow user extensions to the preset list by defining an
1256          * environment variable <gamename>_PRESETS whose value is a
1257          * colon-separated list of items, alternating between textual
1258          * titles in the menu and encoded parameter strings. For
1259          * example, "SOLO_PRESETS=2x3 Advanced:2x3da" would define
1260          * just one additional preset for Solo.
1261          */
1262         char buf[80], *e;
1263         int j, k;
1264
1265         sprintf(buf, "%s_PRESETS", me->ourgame->name);
1266         for (j = k = 0; buf[j]; j++)
1267             if (!isspace((unsigned char)buf[j]))
1268                 buf[k++] = toupper((unsigned char)buf[j]);
1269         buf[k] = '\0';
1270
1271         if ((e = getenv(buf)) != NULL) {
1272             e = dupstr(e);
1273             preset_menu_add_from_user_env(me, me->preset_menu, e, TRUE);
1274             sfree(e);
1275         }
1276     }
1277
1278     /*
1279      * Finalise the menu: allocate an integer id to each entry, and
1280      * store string encodings of the presets' parameters in
1281      * me->encoded_presets.
1282      */
1283     me->n_encoded_presets = 0;
1284     preset_menu_alloc_ids(me, me->preset_menu);
1285     me->encoded_presets = snewn(me->n_encoded_presets, char *);
1286     for (i = 0; i < me->n_encoded_presets; i++)
1287         me->encoded_presets[i] = NULL;
1288     preset_menu_encode_params(me, me->preset_menu);
1289
1290     if (id_limit)
1291         *id_limit = me->n_encoded_presets;
1292     return me->preset_menu;
1293 }
1294
1295 int midend_which_preset(midend *me)
1296 {
1297     char *encoding = me->ourgame->encode_params(me->params, TRUE);
1298     int i, ret;
1299
1300     ret = -1;
1301     for (i = 0; i < me->n_encoded_presets; i++)
1302         if (me->encoded_presets[i] &&
1303             !strcmp(encoding, me->encoded_presets[i])) {
1304             ret = i;
1305             break;
1306         }
1307
1308     sfree(encoding);
1309     return ret;
1310 }
1311
1312 int midend_wants_statusbar(midend *me)
1313 {
1314     return me->ourgame->wants_statusbar;
1315 }
1316
1317 void midend_request_id_changes(midend *me, void (*notify)(void *), void *ctx)
1318 {
1319     me->game_id_change_notify_function = notify;
1320     me->game_id_change_notify_ctx = ctx;
1321 }
1322
1323 void midend_supersede_game_desc(midend *me, char *desc, char *privdesc)
1324 {
1325     sfree(me->desc);
1326     sfree(me->privdesc);
1327     me->desc = dupstr(desc);
1328     me->privdesc = privdesc ? dupstr(privdesc) : NULL;
1329     if (me->game_id_change_notify_function)
1330         me->game_id_change_notify_function(me->game_id_change_notify_ctx);
1331 }
1332
1333 config_item *midend_get_config(midend *me, int which, char **wintitle)
1334 {
1335     char *titlebuf, *parstr, *rest;
1336     config_item *ret;
1337     char sep;
1338
1339     assert(wintitle);
1340     titlebuf = snewn(40 + strlen(me->ourgame->name), char);
1341
1342     switch (which) {
1343       case CFG_SETTINGS:
1344         sprintf(titlebuf, "%s configuration", me->ourgame->name);
1345         *wintitle = titlebuf;
1346         return me->ourgame->configure(me->params);
1347       case CFG_SEED:
1348       case CFG_DESC:
1349         if (!me->curparams) {
1350           sfree(titlebuf);
1351           return NULL;
1352         }
1353         sprintf(titlebuf, "%s %s selection", me->ourgame->name,
1354                 which == CFG_SEED ? "random" : "game");
1355         *wintitle = titlebuf;
1356
1357         ret = snewn(2, config_item);
1358
1359         ret[0].type = C_STRING;
1360         if (which == CFG_SEED)
1361             ret[0].name = "Game random seed";
1362         else
1363             ret[0].name = "Game ID";
1364         /*
1365          * For CFG_DESC the text going in here will be a string
1366          * encoding of the restricted parameters, plus a colon,
1367          * plus the game description. For CFG_SEED it will be the
1368          * full parameters, plus a hash, plus the random seed data.
1369          * Either of these is a valid full game ID (although only
1370          * the former is likely to persist across many code
1371          * changes).
1372          */
1373         parstr = me->ourgame->encode_params(me->curparams, which == CFG_SEED);
1374         assert(parstr);
1375         if (which == CFG_DESC) {
1376             rest = me->desc ? me->desc : "";
1377             sep = ':';
1378         } else {
1379             rest = me->seedstr ? me->seedstr : "";
1380             sep = '#';
1381         }
1382         ret[0].u.string.sval = snewn(strlen(parstr) + strlen(rest) + 2, char);
1383         sprintf(ret[0].u.string.sval, "%s%c%s", parstr, sep, rest);
1384         sfree(parstr);
1385
1386         ret[1].type = C_END;
1387         ret[1].name = NULL;
1388
1389         return ret;
1390     }
1391
1392     assert(!"We shouldn't be here");
1393     return NULL;
1394 }
1395
1396 static const char *midend_game_id_int(midend *me, char *id, int defmode)
1397 {
1398     const char *error;
1399     char *par, *desc, *seed;
1400     game_params *newcurparams, *newparams, *oldparams1, *oldparams2;
1401     int free_params;
1402
1403     seed = strchr(id, '#');
1404     desc = strchr(id, ':');
1405
1406     if (desc && (!seed || desc < seed)) {
1407         /*
1408          * We have a colon separating parameters from game
1409          * description. So `par' now points to the parameters
1410          * string, and `desc' to the description string.
1411          */
1412         *desc++ = '\0';
1413         par = id;
1414         seed = NULL;
1415     } else if (seed && (!desc || seed < desc)) {
1416         /*
1417          * We have a hash separating parameters from random seed.
1418          * So `par' now points to the parameters string, and `seed'
1419          * to the seed string.
1420          */
1421         *seed++ = '\0';
1422         par = id;
1423         desc = NULL;
1424     } else {
1425         /*
1426          * We only have one string. Depending on `defmode', we take
1427          * it to be either parameters, seed or description.
1428          */
1429         if (defmode == DEF_SEED) {
1430             seed = id;
1431             par = desc = NULL;
1432         } else if (defmode == DEF_DESC) {
1433             desc = id;
1434             par = seed = NULL;
1435         } else {
1436             par = id;
1437             seed = desc = NULL;
1438         }
1439     }
1440
1441     /*
1442      * We must be reasonably careful here not to modify anything in
1443      * `me' until we have finished validating things. This function
1444      * must either return an error and do nothing to the midend, or
1445      * return success and do everything; nothing in between is
1446      * acceptable.
1447      */
1448     newcurparams = newparams = oldparams1 = oldparams2 = NULL;
1449
1450     if (par) {
1451         /*
1452          * The params string may underspecify the game parameters, so
1453          * we must first initialise newcurparams with a full set of
1454          * params from somewhere else before we decode_params the
1455          * input string over the top.
1456          *
1457          * But which set? It depends on what other data we have.
1458          *
1459          * If we've been given a _descriptive_ game id, then that may
1460          * well underspecify by design, e.g. Solo game descriptions
1461          * often start just '3x3:' without specifying one of Solo's
1462          * difficulty settings, because it isn't necessary once a game
1463          * has been generated (and you might not even know it, if
1464          * you're manually transcribing a game description). In that
1465          * situation, I've always felt that the best thing to set the
1466          * difficulty to (for use if the user hits 'New Game' after
1467          * pasting in that game id) is whatever it was previously set
1468          * to. That is, we use whatever is already in me->params as
1469          * the basis for our decoding of this input string.
1470          *
1471          * A random-seed based game id, however, should use the real,
1472          * built-in default params, and not even check the
1473          * <game>_DEFAULT environment setting, because when people
1474          * paste each other random seeds - whether it's two users
1475          * arranging to generate the same game at the same time to
1476          * race solving them, or a user sending a bug report upstream
1477          * - the whole point is for the random game id to always be
1478          * interpreted the same way, even if it does underspecify.
1479          *
1480          * A parameter string typed in on its own, with no seed _or_
1481          * description, gets treated the same way as a random seed,
1482          * because again I think the most likely reason for doing that
1483          * is to have a portable representation of a set of params.
1484          */
1485         if (desc) {
1486             newcurparams = me->ourgame->dup_params(me->params);
1487         } else {
1488             newcurparams = me->ourgame->default_params();
1489         }
1490         me->ourgame->decode_params(newcurparams, par);
1491         error = me->ourgame->validate_params(newcurparams, desc == NULL);
1492         if (error) {
1493             me->ourgame->free_params(newcurparams);
1494             return error;
1495         }
1496         oldparams1 = me->curparams;
1497
1498         /*
1499          * Now filter only the persistent parts of this state into
1500          * the long-term params structure, unless we've _only_
1501          * received a params string in which case the whole lot is
1502          * persistent.
1503          */
1504         oldparams2 = me->params;
1505         if (seed || desc) {
1506             char *tmpstr;
1507
1508             newparams = me->ourgame->dup_params(me->params);
1509
1510             tmpstr = me->ourgame->encode_params(newcurparams, FALSE);
1511             me->ourgame->decode_params(newparams, tmpstr);
1512
1513             sfree(tmpstr);
1514         } else {
1515             newparams = me->ourgame->dup_params(newcurparams);
1516         }
1517         free_params = TRUE;
1518     } else {
1519         newcurparams = me->curparams;
1520         newparams = me->params;
1521         free_params = FALSE;
1522     }
1523
1524     if (desc) {
1525         error = me->ourgame->validate_desc(newparams, desc);
1526         if (error) {
1527             if (free_params) {
1528                 if (newcurparams)
1529                     me->ourgame->free_params(newcurparams);
1530                 if (newparams)
1531                     me->ourgame->free_params(newparams);
1532             }
1533             return error;
1534         }
1535     }
1536
1537     /*
1538      * Now we've got past all possible error points. Update the
1539      * midend itself.
1540      */
1541     me->params = newparams;
1542     me->curparams = newcurparams;
1543     if (oldparams1)
1544         me->ourgame->free_params(oldparams1);
1545     if (oldparams2)
1546         me->ourgame->free_params(oldparams2);
1547
1548     sfree(me->desc);
1549     sfree(me->privdesc);
1550     me->desc = me->privdesc = NULL;
1551     sfree(me->seedstr);
1552     me->seedstr = NULL;
1553
1554     if (desc) {
1555         me->desc = dupstr(desc);
1556         me->genmode = GOT_DESC;
1557         sfree(me->aux_info);
1558         me->aux_info = NULL;
1559     }
1560
1561     if (seed) {
1562         me->seedstr = dupstr(seed);
1563         me->genmode = GOT_SEED;
1564     }
1565
1566     return NULL;
1567 }
1568
1569 const char *midend_game_id(midend *me, char *id)
1570 {
1571     return midend_game_id_int(me, id, DEF_PARAMS);
1572 }
1573
1574 char *midend_get_game_id(midend *me)
1575 {
1576     char *parstr, *ret;
1577
1578     parstr = me->ourgame->encode_params(me->curparams, FALSE);
1579     assert(parstr);
1580     assert(me->desc);
1581     ret = snewn(strlen(parstr) + strlen(me->desc) + 2, char);
1582     sprintf(ret, "%s:%s", parstr, me->desc);
1583     sfree(parstr);
1584     return ret;
1585 }
1586
1587 char *midend_get_random_seed(midend *me)
1588 {
1589     char *parstr, *ret;
1590
1591     if (!me->seedstr)
1592         return NULL;
1593
1594     parstr = me->ourgame->encode_params(me->curparams, TRUE);
1595     assert(parstr);
1596     ret = snewn(strlen(parstr) + strlen(me->seedstr) + 2, char);
1597     sprintf(ret, "%s#%s", parstr, me->seedstr);
1598     sfree(parstr);
1599     return ret;
1600 }
1601
1602 const char *midend_set_config(midend *me, int which, config_item *cfg)
1603 {
1604     const char *error;
1605     game_params *params;
1606
1607     switch (which) {
1608       case CFG_SETTINGS:
1609         params = me->ourgame->custom_params(cfg);
1610         error = me->ourgame->validate_params(params, TRUE);
1611
1612         if (error) {
1613             me->ourgame->free_params(params);
1614             return error;
1615         }
1616
1617         me->ourgame->free_params(me->params);
1618         me->params = params;
1619         break;
1620
1621       case CFG_SEED:
1622       case CFG_DESC:
1623         error = midend_game_id_int(me, cfg[0].u.string.sval,
1624                                    (which == CFG_SEED ? DEF_SEED : DEF_DESC));
1625         if (error)
1626             return error;
1627         break;
1628     }
1629
1630     return NULL;
1631 }
1632
1633 int midend_can_format_as_text_now(midend *me)
1634 {
1635     if (me->ourgame->can_format_as_text_ever)
1636         return me->ourgame->can_format_as_text_now(me->params);
1637     else
1638         return FALSE;
1639 }
1640
1641 char *midend_text_format(midend *me)
1642 {
1643     if (me->ourgame->can_format_as_text_ever && me->statepos > 0 &&
1644         me->ourgame->can_format_as_text_now(me->params))
1645         return me->ourgame->text_format(me->states[me->statepos-1].state);
1646     else
1647         return NULL;
1648 }
1649
1650 const char *midend_solve(midend *me)
1651 {
1652     game_state *s;
1653     const char *msg;
1654     char *movestr;
1655
1656     if (!me->ourgame->can_solve)
1657         return "This game does not support the Solve operation";
1658
1659     if (me->statepos < 1)
1660         return "No game set up to solve";   /* _shouldn't_ happen! */
1661
1662     msg = NULL;
1663     movestr = me->ourgame->solve(me->states[0].state,
1664                                  me->states[me->statepos-1].state,
1665                                  me->aux_info, &msg);
1666     assert(movestr != UI_UPDATE);
1667     if (!movestr) {
1668         if (!msg)
1669             msg = "Solve operation failed";   /* _shouldn't_ happen, but can */
1670         return msg;
1671     }
1672     s = me->ourgame->execute_move(me->states[me->statepos-1].state, movestr);
1673     assert(s);
1674
1675     /*
1676      * Now enter the solved state as the next move.
1677      */
1678     midend_stop_anim(me);
1679     midend_purge_states(me);
1680     ensure(me);
1681     me->states[me->nstates].state = s;
1682     me->states[me->nstates].movestr = movestr;
1683     me->states[me->nstates].movetype = SOLVE;
1684     me->statepos = ++me->nstates;
1685     if (me->ui)
1686         me->ourgame->changed_state(me->ui,
1687                                    me->states[me->statepos-2].state,
1688                                    me->states[me->statepos-1].state);
1689     me->dir = +1;
1690     if (me->ourgame->flags & SOLVE_ANIMATES) {
1691         me->oldstate = me->ourgame->dup_game(me->states[me->statepos-2].state);
1692         me->anim_time =
1693             me->ourgame->anim_length(me->states[me->statepos-2].state,
1694                                      me->states[me->statepos-1].state,
1695                                      +1, me->ui);
1696         me->anim_pos = 0.0;
1697     } else {
1698         me->anim_time = 0.0;
1699         midend_finish_move(me);
1700     }
1701     if (me->drawing)
1702         midend_redraw(me);
1703     midend_set_timer(me);
1704     return NULL;
1705 }
1706
1707 int midend_status(midend *me)
1708 {
1709     /*
1710      * We should probably never be called when the state stack has no
1711      * states on it at all - ideally, midends should never be left in
1712      * that state for long enough to get put down and forgotten about.
1713      * But if we are, I think we return _true_ - pedantically speaking
1714      * a midend in that state is 'vacuously solved', and more
1715      * practically, a user whose midend has been left in that state
1716      * probably _does_ want the 'new game' option to be prominent.
1717      */
1718     if (me->statepos == 0)
1719         return +1;
1720
1721     return me->ourgame->status(me->states[me->statepos-1].state);
1722 }
1723
1724 char *midend_rewrite_statusbar(midend *me, char *text)
1725 {
1726     /*
1727      * An important special case is that we are occasionally called
1728      * with our own laststatus, to update the timer.
1729      */
1730     if (me->laststatus != text) {
1731         sfree(me->laststatus);
1732         me->laststatus = dupstr(text);
1733     }
1734
1735     if (me->ourgame->is_timed) {
1736         char timebuf[100], *ret;
1737         int min, sec;
1738
1739         sec = (int)me->elapsed;
1740         min = sec / 60;
1741         sec %= 60;
1742         sprintf(timebuf, "[%d:%02d] ", min, sec);
1743
1744         ret = snewn(strlen(timebuf) + strlen(text) + 1, char);
1745         strcpy(ret, timebuf);
1746         strcat(ret, text);
1747         return ret;
1748
1749     } else {
1750         return dupstr(text);
1751     }
1752 }
1753
1754 #define SERIALISE_MAGIC "Simon Tatham's Portable Puzzle Collection"
1755 #define SERIALISE_VERSION "1"
1756
1757 void midend_serialise(midend *me,
1758                       void (*write)(void *ctx, void *buf, int len),
1759                       void *wctx)
1760 {
1761     int i;
1762
1763     /*
1764      * Each line of the save file contains three components. First
1765      * exactly 8 characters of header word indicating what type of
1766      * data is contained on the line; then a colon followed by a
1767      * decimal integer giving the length of the main string on the
1768      * line; then a colon followed by the string itself (exactly as
1769      * many bytes as previously specified, no matter what they
1770      * contain). Then a newline (of reasonably flexible form).
1771      */
1772 #define wr(h,s) do { \
1773     char hbuf[80]; \
1774     char *str = (s); \
1775     char lbuf[9];                               \
1776     copy_left_justified(lbuf, sizeof(lbuf), h); \
1777     sprintf(hbuf, "%s:%d:", lbuf, (int)strlen(str)); \
1778     write(wctx, hbuf, strlen(hbuf)); \
1779     write(wctx, str, strlen(str)); \
1780     write(wctx, "\n", 1); \
1781 } while (0)
1782
1783     /*
1784      * Magic string identifying the file, and version number of the
1785      * file format.
1786      */
1787     wr("SAVEFILE", SERIALISE_MAGIC);
1788     wr("VERSION", SERIALISE_VERSION);
1789
1790     /*
1791      * The game name. (Copied locally to avoid const annoyance.)
1792      */
1793     {
1794         char *s = dupstr(me->ourgame->name);
1795         wr("GAME", s);
1796         sfree(s);
1797     }
1798
1799     /*
1800      * The current long-term parameters structure, in full.
1801      */
1802     if (me->params) {
1803         char *s = me->ourgame->encode_params(me->params, TRUE);
1804         wr("PARAMS", s);
1805         sfree(s);
1806     }
1807
1808     /*
1809      * The current short-term parameters structure, in full.
1810      */
1811     if (me->curparams) {
1812         char *s = me->ourgame->encode_params(me->curparams, TRUE);
1813         wr("CPARAMS", s);
1814         sfree(s);
1815     }
1816
1817     /*
1818      * The current game description, the privdesc, and the random seed.
1819      */
1820     if (me->seedstr)
1821         wr("SEED", me->seedstr);
1822     if (me->desc)
1823         wr("DESC", me->desc);
1824     if (me->privdesc)
1825         wr("PRIVDESC", me->privdesc);
1826
1827     /*
1828      * The game's aux_info. We obfuscate this to prevent spoilers
1829      * (people are likely to run `head' or similar on a saved game
1830      * file simply to find out what it is, and don't necessarily
1831      * want to be told the answer to the puzzle!)
1832      */
1833     if (me->aux_info) {
1834         unsigned char *s1;
1835         char *s2;
1836         int len;
1837
1838         len = strlen(me->aux_info);
1839         s1 = snewn(len, unsigned char);
1840         memcpy(s1, me->aux_info, len);
1841         obfuscate_bitmap(s1, len*8, FALSE);
1842         s2 = bin2hex(s1, len);
1843
1844         wr("AUXINFO", s2);
1845
1846         sfree(s2);
1847         sfree(s1);
1848     }
1849
1850     /*
1851      * Any required serialisation of the game_ui.
1852      */
1853     if (me->ui) {
1854         char *s = me->ourgame->encode_ui(me->ui);
1855         if (s) {
1856             wr("UI", s);
1857             sfree(s);
1858         }
1859     }
1860
1861     /*
1862      * The game time, if it's a timed game.
1863      */
1864     if (me->ourgame->is_timed) {
1865         char buf[80];
1866         sprintf(buf, "%g", me->elapsed);
1867         wr("TIME", buf);
1868     }
1869
1870     /*
1871      * The length of, and position in, the states list.
1872      */
1873     {
1874         char buf[80];
1875         sprintf(buf, "%d", me->nstates);
1876         wr("NSTATES", buf);
1877         sprintf(buf, "%d", me->statepos);
1878         wr("STATEPOS", buf);
1879     }
1880
1881     /*
1882      * For each state after the initial one (which we know is
1883      * constructed from either privdesc or desc), enough
1884      * information for execute_move() to reconstruct it from the
1885      * previous one.
1886      */
1887     for (i = 1; i < me->nstates; i++) {
1888         assert(me->states[i].movetype != NEWGAME);   /* only state 0 */
1889         switch (me->states[i].movetype) {
1890           case MOVE:
1891             wr("MOVE", me->states[i].movestr);
1892             break;
1893           case SOLVE:
1894             wr("SOLVE", me->states[i].movestr);
1895             break;
1896           case RESTART:
1897             wr("RESTART", me->states[i].movestr);
1898             break;
1899         }
1900     }
1901
1902 #undef wr
1903 }
1904
1905 /*
1906  * Internal version of midend_deserialise, taking an extra check
1907  * function to be called just before beginning to install things in
1908  * the midend.
1909  *
1910  * Like midend_deserialise proper, this function returns NULL on
1911  * success, or an error message.
1912  */
1913 static const char *midend_deserialise_internal(
1914     midend *me, int (*read)(void *ctx, void *buf, int len), void *rctx,
1915     char *(*check)(void *ctx, midend *, const struct deserialise_data *data),
1916     void *cctx)
1917 {
1918     struct deserialise_data data;
1919     int gotstates = 0;
1920     int started = FALSE;
1921     int i;
1922
1923     char *val = NULL;
1924     /* Initially all errors give the same report */
1925     char *ret = "Data does not appear to be a saved game file";
1926
1927     data.seed = data.parstr = data.desc = data.privdesc = NULL;
1928     data.auxinfo = data.uistr = data.cparstr = NULL;
1929     data.elapsed = 0.0F;
1930     data.params = data.cparams = NULL;
1931     data.ui = NULL;
1932     data.states = NULL;
1933     data.nstates = 0;
1934     data.statepos = -1;
1935
1936     /*
1937      * Loop round and round reading one key/value pair at a time
1938      * from the serialised stream, until we have enough game states
1939      * to finish.
1940      */
1941     while (data.nstates <= 0 || data.statepos < 0 ||
1942            gotstates < data.nstates-1) {
1943         char key[9], c;
1944         int len;
1945
1946         do {
1947             if (!read(rctx, key, 1)) {
1948                 /* unexpected EOF */
1949                 goto cleanup;
1950             }
1951         } while (key[0] == '\r' || key[0] == '\n');
1952
1953         if (!read(rctx, key+1, 8)) {
1954             /* unexpected EOF */
1955             goto cleanup;
1956         }
1957
1958         if (key[8] != ':') {
1959             if (started)
1960                 ret = "Data was incorrectly formatted for a saved game file";
1961             goto cleanup;
1962         }
1963         len = strcspn(key, ": ");
1964         assert(len <= 8);
1965         key[len] = '\0';
1966
1967         len = 0;
1968         while (1) {
1969             if (!read(rctx, &c, 1)) {
1970                 /* unexpected EOF */
1971                 goto cleanup;
1972             }
1973
1974             if (c == ':') {
1975                 break;
1976             } else if (c >= '0' && c <= '9') {
1977                 len = (len * 10) + (c - '0');
1978             } else {
1979                 if (started)
1980                     ret = "Data was incorrectly formatted for a"
1981                     " saved game file";
1982                 goto cleanup;
1983             }
1984         }
1985
1986         val = snewn(len+1, char);
1987         if (!read(rctx, val, len)) {
1988             if (started)
1989             goto cleanup;
1990         }
1991         val[len] = '\0';
1992
1993         if (!started) {
1994             if (strcmp(key, "SAVEFILE") || strcmp(val, SERIALISE_MAGIC)) {
1995                 /* ret already has the right message in it */
1996                 goto cleanup;
1997             }
1998             /* Now most errors are this one, unless otherwise specified */
1999             ret = "Saved data ended unexpectedly";
2000             started = TRUE;
2001         } else {
2002             if (!strcmp(key, "VERSION")) {
2003                 if (strcmp(val, SERIALISE_VERSION)) {
2004                     ret = "Cannot handle this version of the saved game"
2005                         " file format";
2006                     goto cleanup;
2007                 }
2008             } else if (!strcmp(key, "GAME")) {
2009                 if (strcmp(val, me->ourgame->name)) {
2010                     ret = "Save file is from a different game";
2011                     goto cleanup;
2012                 }
2013             } else if (!strcmp(key, "PARAMS")) {
2014                 sfree(data.parstr);
2015                 data.parstr = val;
2016                 val = NULL;
2017             } else if (!strcmp(key, "CPARAMS")) {
2018                 sfree(data.cparstr);
2019                 data.cparstr = val;
2020                 val = NULL;
2021             } else if (!strcmp(key, "SEED")) {
2022                 sfree(data.seed);
2023                 data.seed = val;
2024                 val = NULL;
2025             } else if (!strcmp(key, "DESC")) {
2026                 sfree(data.desc);
2027                 data.desc = val;
2028                 val = NULL;
2029             } else if (!strcmp(key, "PRIVDESC")) {
2030                 sfree(data.privdesc);
2031                 data.privdesc = val;
2032                 val = NULL;
2033             } else if (!strcmp(key, "AUXINFO")) {
2034                 unsigned char *tmp;
2035                 int len = strlen(val) / 2;   /* length in bytes */
2036                 tmp = hex2bin(val, len);
2037                 obfuscate_bitmap(tmp, len*8, TRUE);
2038
2039                 sfree(data.auxinfo);
2040                 data.auxinfo = snewn(len + 1, char);
2041                 memcpy(data.auxinfo, tmp, len);
2042                 data.auxinfo[len] = '\0';
2043                 sfree(tmp);
2044             } else if (!strcmp(key, "UI")) {
2045                 sfree(data.uistr);
2046                 data.uistr = val;
2047                 val = NULL;
2048             } else if (!strcmp(key, "TIME")) {
2049                 data.elapsed = (float)atof(val);
2050             } else if (!strcmp(key, "NSTATES")) {
2051                 data.nstates = atoi(val);
2052                 if (data.nstates <= 0) {
2053                     ret = "Number of states in save file was negative";
2054                     goto cleanup;
2055                 }
2056                 if (data.states) {
2057                     ret = "Two state counts provided in save file";
2058                     goto cleanup;
2059                 }
2060                 data.states = snewn(data.nstates, struct midend_state_entry);
2061                 for (i = 0; i < data.nstates; i++) {
2062                     data.states[i].state = NULL;
2063                     data.states[i].movestr = NULL;
2064                     data.states[i].movetype = NEWGAME;
2065                 }
2066             } else if (!strcmp(key, "STATEPOS")) {
2067                 data.statepos = atoi(val);
2068             } else if (!strcmp(key, "MOVE")) {
2069                 gotstates++;
2070                 data.states[gotstates].movetype = MOVE;
2071                 data.states[gotstates].movestr = val;
2072                 val = NULL;
2073             } else if (!strcmp(key, "SOLVE")) {
2074                 gotstates++;
2075                 data.states[gotstates].movetype = SOLVE;
2076                 data.states[gotstates].movestr = val;
2077                 val = NULL;
2078             } else if (!strcmp(key, "RESTART")) {
2079                 gotstates++;
2080                 data.states[gotstates].movetype = RESTART;
2081                 data.states[gotstates].movestr = val;
2082                 val = NULL;
2083             }
2084         }
2085
2086         sfree(val);
2087         val = NULL;
2088     }
2089
2090     data.params = me->ourgame->default_params();
2091     me->ourgame->decode_params(data.params, data.parstr);
2092     if (me->ourgame->validate_params(data.params, TRUE)) {
2093         ret = "Long-term parameters in save file are invalid";
2094         goto cleanup;
2095     }
2096     data.cparams = me->ourgame->default_params();
2097     me->ourgame->decode_params(data.cparams, data.cparstr);
2098     if (me->ourgame->validate_params(data.cparams, FALSE)) {
2099         ret = "Short-term parameters in save file are invalid";
2100         goto cleanup;
2101     }
2102     if (data.seed && me->ourgame->validate_params(data.cparams, TRUE)) {
2103         /*
2104          * The seed's no use with this version, but we can perfectly
2105          * well use the rest of the data.
2106          */
2107         sfree(data.seed);
2108         data.seed = NULL;
2109     }
2110     if (!data.desc) {
2111         ret = "Game description in save file is missing";
2112         goto cleanup;
2113     } else if (me->ourgame->validate_desc(data.cparams, data.desc)) {
2114         ret = "Game description in save file is invalid";
2115         goto cleanup;
2116     }
2117     if (data.privdesc &&
2118         me->ourgame->validate_desc(data.cparams, data.privdesc)) {
2119         ret = "Game private description in save file is invalid";
2120         goto cleanup;
2121     }
2122     if (data.statepos < 0 || data.statepos >= data.nstates) {
2123         ret = "Game position in save file is out of range";
2124     }
2125
2126     data.states[0].state = me->ourgame->new_game(
2127         me, data.cparams, data.privdesc ? data.privdesc : data.desc);
2128     for (i = 1; i < data.nstates; i++) {
2129         assert(data.states[i].movetype != NEWGAME);
2130         switch (data.states[i].movetype) {
2131           case MOVE:
2132           case SOLVE:
2133             data.states[i].state = me->ourgame->execute_move(
2134                 data.states[i-1].state, data.states[i].movestr);
2135             if (data.states[i].state == NULL) {
2136                 ret = "Save file contained an invalid move";
2137                 goto cleanup;
2138             }
2139             break;
2140           case RESTART:
2141             if (me->ourgame->validate_desc(
2142                     data.cparams, data.states[i].movestr)) {
2143                 ret = "Save file contained an invalid restart move";
2144                 goto cleanup;
2145             }
2146             data.states[i].state = me->ourgame->new_game(
2147                 me, data.cparams, data.states[i].movestr);
2148             break;
2149         }
2150     }
2151
2152     data.ui = me->ourgame->new_ui(data.states[0].state);
2153     me->ourgame->decode_ui(data.ui, data.uistr);
2154
2155     /*
2156      * Run the externally provided check function, and abort if it
2157      * returns an error message.
2158      */
2159     if (check && (ret = check(cctx, me, &data)) != NULL)
2160         goto cleanup;            /* error message is already in ret */
2161
2162     /*
2163      * Now we've run out of possible error conditions, so we're
2164      * ready to start overwriting the real data in the current
2165      * midend. We'll do this by swapping things with the local
2166      * variables, so that the same cleanup code will free the old
2167      * stuff.
2168      */
2169     {
2170         char *tmp;
2171
2172         tmp = me->desc;
2173         me->desc = data.desc;
2174         data.desc = tmp;
2175
2176         tmp = me->privdesc;
2177         me->privdesc = data.privdesc;
2178         data.privdesc = tmp;
2179
2180         tmp = me->seedstr;
2181         me->seedstr = data.seed;
2182         data.seed = tmp;
2183
2184         tmp = me->aux_info;
2185         me->aux_info = data.auxinfo;
2186         data.auxinfo = tmp;
2187     }
2188
2189     me->genmode = GOT_NOTHING;
2190
2191     me->statesize = data.nstates;
2192     data.nstates = me->nstates;
2193     me->nstates = me->statesize;
2194     {
2195         struct midend_state_entry *tmp;
2196         tmp = me->states;
2197         me->states = data.states;
2198         data.states = tmp;
2199     }
2200     me->statepos = data.statepos;
2201
2202     /*
2203      * Don't save the "new game undo" state.  So "new game" twice or
2204      * (in some environments) switching away and back, will make a
2205      * "new game" irreversible.  Maybe in the future we will have a
2206      * more sophisticated way to decide when to discard the previous
2207      * game state.
2208      */
2209     me->newgame_undo_len = 0;
2210
2211     {
2212         game_params *tmp;
2213
2214         tmp = me->params;
2215         me->params = data.params;
2216         data.params = tmp;
2217
2218         tmp = me->curparams;
2219         me->curparams = data.cparams;
2220         data.cparams = tmp;
2221     }
2222
2223     me->oldstate = NULL;
2224     me->anim_time = me->anim_pos = me->flash_time = me->flash_pos = 0.0F;
2225     me->dir = 0;
2226
2227     {
2228         game_ui *tmp;
2229
2230         tmp = me->ui;
2231         me->ui = data.ui;
2232         data.ui = tmp;
2233     }
2234
2235     me->elapsed = data.elapsed;
2236     me->pressed_mouse_button = 0;
2237
2238     midend_set_timer(me);
2239
2240     if (me->drawstate)
2241         me->ourgame->free_drawstate(me->drawing, me->drawstate);
2242     me->drawstate =
2243         me->ourgame->new_drawstate(me->drawing,
2244                                    me->states[me->statepos-1].state);
2245     midend_size_new_drawstate(me);
2246     if (me->game_id_change_notify_function)
2247         me->game_id_change_notify_function(me->game_id_change_notify_ctx);
2248
2249     ret = NULL;                        /* success! */
2250
2251     cleanup:
2252     sfree(val);
2253     sfree(data.seed);
2254     sfree(data.parstr);
2255     sfree(data.cparstr);
2256     sfree(data.desc);
2257     sfree(data.privdesc);
2258     sfree(data.auxinfo);
2259     sfree(data.uistr);
2260     if (data.params)
2261         me->ourgame->free_params(data.params);
2262     if (data.cparams)
2263         me->ourgame->free_params(data.cparams);
2264     if (data.ui)
2265         me->ourgame->free_ui(data.ui);
2266     if (data.states) {
2267         int i;
2268
2269         for (i = 0; i < data.nstates; i++) {
2270             if (data.states[i].state)
2271                 me->ourgame->free_game(data.states[i].state);
2272             sfree(data.states[i].movestr);
2273         }
2274         sfree(data.states);
2275     }
2276
2277     return ret;
2278 }
2279
2280 const char *midend_deserialise(
2281     midend *me, int (*read)(void *ctx, void *buf, int len), void *rctx)
2282 {
2283     return midend_deserialise_internal(me, read, rctx, NULL, NULL);
2284 }
2285
2286 /*
2287  * This function examines a saved game file just far enough to
2288  * determine which game type it contains. It returns NULL on success
2289  * and the game name string in 'name' (which will be dynamically
2290  * allocated and should be caller-freed), or an error message on
2291  * failure.
2292  */
2293 const char *identify_game(char **name,
2294                           int (*read)(void *ctx, void *buf, int len),
2295                           void *rctx)
2296 {
2297     int nstates = 0, statepos = -1, gotstates = 0;
2298     int started = FALSE;
2299
2300     char *val = NULL;
2301     /* Initially all errors give the same report */
2302     char *ret = "Data does not appear to be a saved game file";
2303
2304     *name = NULL;
2305
2306     /*
2307      * Loop round and round reading one key/value pair at a time from
2308      * the serialised stream, until we've found the game name.
2309      */
2310     while (nstates <= 0 || statepos < 0 || gotstates < nstates-1) {
2311         char key[9], c;
2312         int len;
2313
2314         do {
2315             if (!read(rctx, key, 1)) {
2316                 /* unexpected EOF */
2317                 goto cleanup;
2318             }
2319         } while (key[0] == '\r' || key[0] == '\n');
2320
2321         if (!read(rctx, key+1, 8)) {
2322             /* unexpected EOF */
2323             goto cleanup;
2324         }
2325
2326         if (key[8] != ':') {
2327             if (started)
2328                 ret = "Data was incorrectly formatted for a saved game file";
2329             goto cleanup;
2330         }
2331         len = strcspn(key, ": ");
2332         assert(len <= 8);
2333         key[len] = '\0';
2334
2335         len = 0;
2336         while (1) {
2337             if (!read(rctx, &c, 1)) {
2338                 /* unexpected EOF */
2339                 goto cleanup;
2340             }
2341
2342             if (c == ':') {
2343                 break;
2344             } else if (c >= '0' && c <= '9') {
2345                 len = (len * 10) + (c - '0');
2346             } else {
2347                 if (started)
2348                     ret = "Data was incorrectly formatted for a"
2349                     " saved game file";
2350                 goto cleanup;
2351             }
2352         }
2353
2354         val = snewn(len+1, char);
2355         if (!read(rctx, val, len)) {
2356             if (started)
2357             goto cleanup;
2358         }
2359         val[len] = '\0';
2360
2361         if (!started) {
2362             if (strcmp(key, "SAVEFILE") || strcmp(val, SERIALISE_MAGIC)) {
2363                 /* ret already has the right message in it */
2364                 goto cleanup;
2365             }
2366             /* Now most errors are this one, unless otherwise specified */
2367             ret = "Saved data ended unexpectedly";
2368             started = TRUE;
2369         } else {
2370             if (!strcmp(key, "VERSION")) {
2371                 if (strcmp(val, SERIALISE_VERSION)) {
2372                     ret = "Cannot handle this version of the saved game"
2373                         " file format";
2374                     goto cleanup;
2375                 }
2376             } else if (!strcmp(key, "GAME")) {
2377                 *name = dupstr(val);
2378                 ret = NULL;
2379                 goto cleanup;
2380             }
2381         }
2382
2383         sfree(val);
2384         val = NULL;
2385     }
2386
2387     cleanup:
2388     sfree(val);
2389     return ret;
2390 }
2391
2392 const char *midend_print_puzzle(midend *me, document *doc, int with_soln)
2393 {
2394     game_state *soln = NULL;
2395
2396     if (me->statepos < 1)
2397         return "No game set up to print";/* _shouldn't_ happen! */
2398
2399     if (with_soln) {
2400         const char *msg;
2401         char *movestr;
2402
2403         if (!me->ourgame->can_solve)
2404             return "This game does not support the Solve operation";
2405
2406         msg = "Solve operation failed";/* game _should_ overwrite on error */
2407         movestr = me->ourgame->solve(me->states[0].state,
2408                                      me->states[me->statepos-1].state,
2409                                      me->aux_info, &msg);
2410         if (!movestr)
2411             return msg;
2412         soln = me->ourgame->execute_move(me->states[me->statepos-1].state,
2413                                          movestr);
2414         assert(soln);
2415
2416         sfree(movestr);
2417     } else
2418         soln = NULL;
2419
2420     /*
2421      * This call passes over ownership of the two game_states and
2422      * the game_params. Hence we duplicate the ones we want to
2423      * keep, and we don't have to bother freeing soln if it was
2424      * non-NULL.
2425      */
2426     document_add_puzzle(doc, me->ourgame,
2427                         me->ourgame->dup_params(me->curparams),
2428                         me->ourgame->dup_game(me->states[0].state), soln);
2429
2430     return NULL;
2431 }