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     const 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, const 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 const 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, const char *desc,
1324                                 const char *privdesc)
1325 {
1326     sfree(me->desc);
1327     sfree(me->privdesc);
1328     me->desc = dupstr(desc);
1329     me->privdesc = privdesc ? dupstr(privdesc) : NULL;
1330     if (me->game_id_change_notify_function)
1331         me->game_id_change_notify_function(me->game_id_change_notify_ctx);
1332 }
1333
1334 config_item *midend_get_config(midend *me, int which, char **wintitle)
1335 {
1336     char *titlebuf, *parstr;
1337     const char *rest;
1338     config_item *ret;
1339     char sep;
1340
1341     assert(wintitle);
1342     titlebuf = snewn(40 + strlen(me->ourgame->name), char);
1343
1344     switch (which) {
1345       case CFG_SETTINGS:
1346         sprintf(titlebuf, "%s configuration", me->ourgame->name);
1347         *wintitle = titlebuf;
1348         return me->ourgame->configure(me->params);
1349       case CFG_SEED:
1350       case CFG_DESC:
1351         if (!me->curparams) {
1352           sfree(titlebuf);
1353           return NULL;
1354         }
1355         sprintf(titlebuf, "%s %s selection", me->ourgame->name,
1356                 which == CFG_SEED ? "random" : "game");
1357         *wintitle = titlebuf;
1358
1359         ret = snewn(2, config_item);
1360
1361         ret[0].type = C_STRING;
1362         if (which == CFG_SEED)
1363             ret[0].name = "Game random seed";
1364         else
1365             ret[0].name = "Game ID";
1366         /*
1367          * For CFG_DESC the text going in here will be a string
1368          * encoding of the restricted parameters, plus a colon,
1369          * plus the game description. For CFG_SEED it will be the
1370          * full parameters, plus a hash, plus the random seed data.
1371          * Either of these is a valid full game ID (although only
1372          * the former is likely to persist across many code
1373          * changes).
1374          */
1375         parstr = me->ourgame->encode_params(me->curparams, which == CFG_SEED);
1376         assert(parstr);
1377         if (which == CFG_DESC) {
1378             rest = me->desc ? me->desc : "";
1379             sep = ':';
1380         } else {
1381             rest = me->seedstr ? me->seedstr : "";
1382             sep = '#';
1383         }
1384         ret[0].u.string.sval = snewn(strlen(parstr) + strlen(rest) + 2, char);
1385         sprintf(ret[0].u.string.sval, "%s%c%s", parstr, sep, rest);
1386         sfree(parstr);
1387
1388         ret[1].type = C_END;
1389         ret[1].name = NULL;
1390
1391         return ret;
1392     }
1393
1394     assert(!"We shouldn't be here");
1395     return NULL;
1396 }
1397
1398 static const char *midend_game_id_int(midend *me, const char *id, int defmode)
1399 {
1400     const char *error;
1401     char *par = NULL;
1402     const char *desc, *seed;
1403     game_params *newcurparams, *newparams, *oldparams1, *oldparams2;
1404     int free_params;
1405
1406     seed = strchr(id, '#');
1407     desc = strchr(id, ':');
1408
1409     if (desc && (!seed || desc < seed)) {
1410         /*
1411          * We have a colon separating parameters from game
1412          * description. So `par' now points to the parameters
1413          * string, and `desc' to the description string.
1414          */
1415         par = snewn(desc-id + 1, char);
1416         strncpy(par, id, desc-id);
1417         par[desc-id] = '\0';
1418         desc++;
1419         seed = NULL;
1420     } else if (seed && (!desc || seed < desc)) {
1421         /*
1422          * We have a hash separating parameters from random seed.
1423          * So `par' now points to the parameters string, and `seed'
1424          * to the seed string.
1425          */
1426         par = snewn(seed-id + 1, char);
1427         strncpy(par, id, seed-id);
1428         par[seed-id] = '\0';
1429         seed++;
1430         desc = NULL;
1431     } else {
1432         /*
1433          * We only have one string. Depending on `defmode', we take
1434          * it to be either parameters, seed or description.
1435          */
1436         if (defmode == DEF_SEED) {
1437             seed = id;
1438             par = NULL;
1439             desc = NULL;
1440         } else if (defmode == DEF_DESC) {
1441             desc = id;
1442             par = NULL;
1443             seed = NULL;
1444         } else {
1445             par = dupstr(id);
1446             seed = desc = NULL;
1447         }
1448     }
1449
1450     /*
1451      * We must be reasonably careful here not to modify anything in
1452      * `me' until we have finished validating things. This function
1453      * must either return an error and do nothing to the midend, or
1454      * return success and do everything; nothing in between is
1455      * acceptable.
1456      */
1457     newcurparams = newparams = oldparams1 = oldparams2 = NULL;
1458
1459     if (par) {
1460         /*
1461          * The params string may underspecify the game parameters, so
1462          * we must first initialise newcurparams with a full set of
1463          * params from somewhere else before we decode_params the
1464          * input string over the top.
1465          *
1466          * But which set? It depends on what other data we have.
1467          *
1468          * If we've been given a _descriptive_ game id, then that may
1469          * well underspecify by design, e.g. Solo game descriptions
1470          * often start just '3x3:' without specifying one of Solo's
1471          * difficulty settings, because it isn't necessary once a game
1472          * has been generated (and you might not even know it, if
1473          * you're manually transcribing a game description). In that
1474          * situation, I've always felt that the best thing to set the
1475          * difficulty to (for use if the user hits 'New Game' after
1476          * pasting in that game id) is whatever it was previously set
1477          * to. That is, we use whatever is already in me->params as
1478          * the basis for our decoding of this input string.
1479          *
1480          * A random-seed based game id, however, should use the real,
1481          * built-in default params, and not even check the
1482          * <game>_DEFAULT environment setting, because when people
1483          * paste each other random seeds - whether it's two users
1484          * arranging to generate the same game at the same time to
1485          * race solving them, or a user sending a bug report upstream
1486          * - the whole point is for the random game id to always be
1487          * interpreted the same way, even if it does underspecify.
1488          *
1489          * A parameter string typed in on its own, with no seed _or_
1490          * description, gets treated the same way as a random seed,
1491          * because again I think the most likely reason for doing that
1492          * is to have a portable representation of a set of params.
1493          */
1494         if (desc) {
1495             newcurparams = me->ourgame->dup_params(me->params);
1496         } else {
1497             newcurparams = me->ourgame->default_params();
1498         }
1499         me->ourgame->decode_params(newcurparams, par);
1500         error = me->ourgame->validate_params(newcurparams, desc == NULL);
1501         if (error) {
1502             me->ourgame->free_params(newcurparams);
1503             return error;
1504         }
1505         oldparams1 = me->curparams;
1506
1507         /*
1508          * Now filter only the persistent parts of this state into
1509          * the long-term params structure, unless we've _only_
1510          * received a params string in which case the whole lot is
1511          * persistent.
1512          */
1513         oldparams2 = me->params;
1514         if (seed || desc) {
1515             char *tmpstr;
1516
1517             newparams = me->ourgame->dup_params(me->params);
1518
1519             tmpstr = me->ourgame->encode_params(newcurparams, FALSE);
1520             me->ourgame->decode_params(newparams, tmpstr);
1521
1522             sfree(tmpstr);
1523         } else {
1524             newparams = me->ourgame->dup_params(newcurparams);
1525         }
1526         free_params = TRUE;
1527     } else {
1528         newcurparams = me->curparams;
1529         newparams = me->params;
1530         free_params = FALSE;
1531     }
1532
1533     if (desc) {
1534         error = me->ourgame->validate_desc(newparams, desc);
1535         if (error) {
1536             if (free_params) {
1537                 if (newcurparams)
1538                     me->ourgame->free_params(newcurparams);
1539                 if (newparams)
1540                     me->ourgame->free_params(newparams);
1541             }
1542             return error;
1543         }
1544     }
1545
1546     /*
1547      * Now we've got past all possible error points. Update the
1548      * midend itself.
1549      */
1550     me->params = newparams;
1551     me->curparams = newcurparams;
1552     if (oldparams1)
1553         me->ourgame->free_params(oldparams1);
1554     if (oldparams2)
1555         me->ourgame->free_params(oldparams2);
1556
1557     sfree(me->desc);
1558     sfree(me->privdesc);
1559     me->desc = me->privdesc = NULL;
1560     sfree(me->seedstr);
1561     me->seedstr = NULL;
1562
1563     if (desc) {
1564         me->desc = dupstr(desc);
1565         me->genmode = GOT_DESC;
1566         sfree(me->aux_info);
1567         me->aux_info = NULL;
1568     }
1569
1570     if (seed) {
1571         me->seedstr = dupstr(seed);
1572         me->genmode = GOT_SEED;
1573     }
1574
1575     sfree(par);
1576
1577     return NULL;
1578 }
1579
1580 const char *midend_game_id(midend *me, const char *id)
1581 {
1582     return midend_game_id_int(me, id, DEF_PARAMS);
1583 }
1584
1585 char *midend_get_game_id(midend *me)
1586 {
1587     char *parstr, *ret;
1588
1589     parstr = me->ourgame->encode_params(me->curparams, FALSE);
1590     assert(parstr);
1591     assert(me->desc);
1592     ret = snewn(strlen(parstr) + strlen(me->desc) + 2, char);
1593     sprintf(ret, "%s:%s", parstr, me->desc);
1594     sfree(parstr);
1595     return ret;
1596 }
1597
1598 char *midend_get_random_seed(midend *me)
1599 {
1600     char *parstr, *ret;
1601
1602     if (!me->seedstr)
1603         return NULL;
1604
1605     parstr = me->ourgame->encode_params(me->curparams, TRUE);
1606     assert(parstr);
1607     ret = snewn(strlen(parstr) + strlen(me->seedstr) + 2, char);
1608     sprintf(ret, "%s#%s", parstr, me->seedstr);
1609     sfree(parstr);
1610     return ret;
1611 }
1612
1613 const char *midend_set_config(midend *me, int which, config_item *cfg)
1614 {
1615     const char *error;
1616     game_params *params;
1617
1618     switch (which) {
1619       case CFG_SETTINGS:
1620         params = me->ourgame->custom_params(cfg);
1621         error = me->ourgame->validate_params(params, TRUE);
1622
1623         if (error) {
1624             me->ourgame->free_params(params);
1625             return error;
1626         }
1627
1628         me->ourgame->free_params(me->params);
1629         me->params = params;
1630         break;
1631
1632       case CFG_SEED:
1633       case CFG_DESC:
1634         error = midend_game_id_int(me, cfg[0].u.string.sval,
1635                                    (which == CFG_SEED ? DEF_SEED : DEF_DESC));
1636         if (error)
1637             return error;
1638         break;
1639     }
1640
1641     return NULL;
1642 }
1643
1644 int midend_can_format_as_text_now(midend *me)
1645 {
1646     if (me->ourgame->can_format_as_text_ever)
1647         return me->ourgame->can_format_as_text_now(me->params);
1648     else
1649         return FALSE;
1650 }
1651
1652 char *midend_text_format(midend *me)
1653 {
1654     if (me->ourgame->can_format_as_text_ever && me->statepos > 0 &&
1655         me->ourgame->can_format_as_text_now(me->params))
1656         return me->ourgame->text_format(me->states[me->statepos-1].state);
1657     else
1658         return NULL;
1659 }
1660
1661 const char *midend_solve(midend *me)
1662 {
1663     game_state *s;
1664     const char *msg;
1665     char *movestr;
1666
1667     if (!me->ourgame->can_solve)
1668         return "This game does not support the Solve operation";
1669
1670     if (me->statepos < 1)
1671         return "No game set up to solve";   /* _shouldn't_ happen! */
1672
1673     msg = NULL;
1674     movestr = me->ourgame->solve(me->states[0].state,
1675                                  me->states[me->statepos-1].state,
1676                                  me->aux_info, &msg);
1677     assert(movestr != UI_UPDATE);
1678     if (!movestr) {
1679         if (!msg)
1680             msg = "Solve operation failed";   /* _shouldn't_ happen, but can */
1681         return msg;
1682     }
1683     s = me->ourgame->execute_move(me->states[me->statepos-1].state, movestr);
1684     assert(s);
1685
1686     /*
1687      * Now enter the solved state as the next move.
1688      */
1689     midend_stop_anim(me);
1690     midend_purge_states(me);
1691     ensure(me);
1692     me->states[me->nstates].state = s;
1693     me->states[me->nstates].movestr = movestr;
1694     me->states[me->nstates].movetype = SOLVE;
1695     me->statepos = ++me->nstates;
1696     if (me->ui)
1697         me->ourgame->changed_state(me->ui,
1698                                    me->states[me->statepos-2].state,
1699                                    me->states[me->statepos-1].state);
1700     me->dir = +1;
1701     if (me->ourgame->flags & SOLVE_ANIMATES) {
1702         me->oldstate = me->ourgame->dup_game(me->states[me->statepos-2].state);
1703         me->anim_time =
1704             me->ourgame->anim_length(me->states[me->statepos-2].state,
1705                                      me->states[me->statepos-1].state,
1706                                      +1, me->ui);
1707         me->anim_pos = 0.0;
1708     } else {
1709         me->anim_time = 0.0;
1710         midend_finish_move(me);
1711     }
1712     if (me->drawing)
1713         midend_redraw(me);
1714     midend_set_timer(me);
1715     return NULL;
1716 }
1717
1718 int midend_status(midend *me)
1719 {
1720     /*
1721      * We should probably never be called when the state stack has no
1722      * states on it at all - ideally, midends should never be left in
1723      * that state for long enough to get put down and forgotten about.
1724      * But if we are, I think we return _true_ - pedantically speaking
1725      * a midend in that state is 'vacuously solved', and more
1726      * practically, a user whose midend has been left in that state
1727      * probably _does_ want the 'new game' option to be prominent.
1728      */
1729     if (me->statepos == 0)
1730         return +1;
1731
1732     return me->ourgame->status(me->states[me->statepos-1].state);
1733 }
1734
1735 char *midend_rewrite_statusbar(midend *me, const char *text)
1736 {
1737     /*
1738      * An important special case is that we are occasionally called
1739      * with our own laststatus, to update the timer.
1740      */
1741     if (me->laststatus != text) {
1742         sfree(me->laststatus);
1743         me->laststatus = dupstr(text);
1744     }
1745
1746     if (me->ourgame->is_timed) {
1747         char timebuf[100], *ret;
1748         int min, sec;
1749
1750         sec = (int)me->elapsed;
1751         min = sec / 60;
1752         sec %= 60;
1753         sprintf(timebuf, "[%d:%02d] ", min, sec);
1754
1755         ret = snewn(strlen(timebuf) + strlen(text) + 1, char);
1756         strcpy(ret, timebuf);
1757         strcat(ret, text);
1758         return ret;
1759
1760     } else {
1761         return dupstr(text);
1762     }
1763 }
1764
1765 #define SERIALISE_MAGIC "Simon Tatham's Portable Puzzle Collection"
1766 #define SERIALISE_VERSION "1"
1767
1768 void midend_serialise(midend *me,
1769                       void (*write)(void *ctx, const void *buf, int len),
1770                       void *wctx)
1771 {
1772     int i;
1773
1774     /*
1775      * Each line of the save file contains three components. First
1776      * exactly 8 characters of header word indicating what type of
1777      * data is contained on the line; then a colon followed by a
1778      * decimal integer giving the length of the main string on the
1779      * line; then a colon followed by the string itself (exactly as
1780      * many bytes as previously specified, no matter what they
1781      * contain). Then a newline (of reasonably flexible form).
1782      */
1783 #define wr(h,s) do { \
1784     char hbuf[80]; \
1785     const char *str = (s); \
1786     char lbuf[9];                               \
1787     copy_left_justified(lbuf, sizeof(lbuf), h); \
1788     sprintf(hbuf, "%s:%d:", lbuf, (int)strlen(str)); \
1789     write(wctx, hbuf, strlen(hbuf)); \
1790     write(wctx, str, strlen(str)); \
1791     write(wctx, "\n", 1); \
1792 } while (0)
1793
1794     /*
1795      * Magic string identifying the file, and version number of the
1796      * file format.
1797      */
1798     wr("SAVEFILE", SERIALISE_MAGIC);
1799     wr("VERSION", SERIALISE_VERSION);
1800
1801     /*
1802      * The game name. (Copied locally to avoid const annoyance.)
1803      */
1804     {
1805         char *s = dupstr(me->ourgame->name);
1806         wr("GAME", s);
1807         sfree(s);
1808     }
1809
1810     /*
1811      * The current long-term parameters structure, in full.
1812      */
1813     if (me->params) {
1814         char *s = me->ourgame->encode_params(me->params, TRUE);
1815         wr("PARAMS", s);
1816         sfree(s);
1817     }
1818
1819     /*
1820      * The current short-term parameters structure, in full.
1821      */
1822     if (me->curparams) {
1823         char *s = me->ourgame->encode_params(me->curparams, TRUE);
1824         wr("CPARAMS", s);
1825         sfree(s);
1826     }
1827
1828     /*
1829      * The current game description, the privdesc, and the random seed.
1830      */
1831     if (me->seedstr)
1832         wr("SEED", me->seedstr);
1833     if (me->desc)
1834         wr("DESC", me->desc);
1835     if (me->privdesc)
1836         wr("PRIVDESC", me->privdesc);
1837
1838     /*
1839      * The game's aux_info. We obfuscate this to prevent spoilers
1840      * (people are likely to run `head' or similar on a saved game
1841      * file simply to find out what it is, and don't necessarily
1842      * want to be told the answer to the puzzle!)
1843      */
1844     if (me->aux_info) {
1845         unsigned char *s1;
1846         char *s2;
1847         int len;
1848
1849         len = strlen(me->aux_info);
1850         s1 = snewn(len, unsigned char);
1851         memcpy(s1, me->aux_info, len);
1852         obfuscate_bitmap(s1, len*8, FALSE);
1853         s2 = bin2hex(s1, len);
1854
1855         wr("AUXINFO", s2);
1856
1857         sfree(s2);
1858         sfree(s1);
1859     }
1860
1861     /*
1862      * Any required serialisation of the game_ui.
1863      */
1864     if (me->ui) {
1865         char *s = me->ourgame->encode_ui(me->ui);
1866         if (s) {
1867             wr("UI", s);
1868             sfree(s);
1869         }
1870     }
1871
1872     /*
1873      * The game time, if it's a timed game.
1874      */
1875     if (me->ourgame->is_timed) {
1876         char buf[80];
1877         sprintf(buf, "%g", me->elapsed);
1878         wr("TIME", buf);
1879     }
1880
1881     /*
1882      * The length of, and position in, the states list.
1883      */
1884     {
1885         char buf[80];
1886         sprintf(buf, "%d", me->nstates);
1887         wr("NSTATES", buf);
1888         sprintf(buf, "%d", me->statepos);
1889         wr("STATEPOS", buf);
1890     }
1891
1892     /*
1893      * For each state after the initial one (which we know is
1894      * constructed from either privdesc or desc), enough
1895      * information for execute_move() to reconstruct it from the
1896      * previous one.
1897      */
1898     for (i = 1; i < me->nstates; i++) {
1899         assert(me->states[i].movetype != NEWGAME);   /* only state 0 */
1900         switch (me->states[i].movetype) {
1901           case MOVE:
1902             wr("MOVE", me->states[i].movestr);
1903             break;
1904           case SOLVE:
1905             wr("SOLVE", me->states[i].movestr);
1906             break;
1907           case RESTART:
1908             wr("RESTART", me->states[i].movestr);
1909             break;
1910         }
1911     }
1912
1913 #undef wr
1914 }
1915
1916 /*
1917  * Internal version of midend_deserialise, taking an extra check
1918  * function to be called just before beginning to install things in
1919  * the midend.
1920  *
1921  * Like midend_deserialise proper, this function returns NULL on
1922  * success, or an error message.
1923  */
1924 static const char *midend_deserialise_internal(
1925     midend *me, int (*read)(void *ctx, void *buf, int len), void *rctx,
1926     const char *(*check)(void *ctx, midend *, const struct deserialise_data *),
1927     void *cctx)
1928 {
1929     struct deserialise_data data;
1930     int gotstates = 0;
1931     int started = FALSE;
1932     int i;
1933
1934     char *val = NULL;
1935     /* Initially all errors give the same report */
1936     const char *ret = "Data does not appear to be a saved game file";
1937
1938     data.seed = data.parstr = data.desc = data.privdesc = NULL;
1939     data.auxinfo = data.uistr = data.cparstr = NULL;
1940     data.elapsed = 0.0F;
1941     data.params = data.cparams = NULL;
1942     data.ui = NULL;
1943     data.states = NULL;
1944     data.nstates = 0;
1945     data.statepos = -1;
1946
1947     /*
1948      * Loop round and round reading one key/value pair at a time
1949      * from the serialised stream, until we have enough game states
1950      * to finish.
1951      */
1952     while (data.nstates <= 0 || data.statepos < 0 ||
1953            gotstates < data.nstates-1) {
1954         char key[9], c;
1955         int len;
1956
1957         do {
1958             if (!read(rctx, key, 1)) {
1959                 /* unexpected EOF */
1960                 goto cleanup;
1961             }
1962         } while (key[0] == '\r' || key[0] == '\n');
1963
1964         if (!read(rctx, key+1, 8)) {
1965             /* unexpected EOF */
1966             goto cleanup;
1967         }
1968
1969         if (key[8] != ':') {
1970             if (started)
1971                 ret = "Data was incorrectly formatted for a saved game file";
1972             goto cleanup;
1973         }
1974         len = strcspn(key, ": ");
1975         assert(len <= 8);
1976         key[len] = '\0';
1977
1978         len = 0;
1979         while (1) {
1980             if (!read(rctx, &c, 1)) {
1981                 /* unexpected EOF */
1982                 goto cleanup;
1983             }
1984
1985             if (c == ':') {
1986                 break;
1987             } else if (c >= '0' && c <= '9') {
1988                 len = (len * 10) + (c - '0');
1989             } else {
1990                 if (started)
1991                     ret = "Data was incorrectly formatted for a"
1992                     " saved game file";
1993                 goto cleanup;
1994             }
1995         }
1996
1997         val = snewn(len+1, char);
1998         if (!read(rctx, val, len)) {
1999             if (started)
2000             goto cleanup;
2001         }
2002         val[len] = '\0';
2003
2004         if (!started) {
2005             if (strcmp(key, "SAVEFILE") || strcmp(val, SERIALISE_MAGIC)) {
2006                 /* ret already has the right message in it */
2007                 goto cleanup;
2008             }
2009             /* Now most errors are this one, unless otherwise specified */
2010             ret = "Saved data ended unexpectedly";
2011             started = TRUE;
2012         } else {
2013             if (!strcmp(key, "VERSION")) {
2014                 if (strcmp(val, SERIALISE_VERSION)) {
2015                     ret = "Cannot handle this version of the saved game"
2016                         " file format";
2017                     goto cleanup;
2018                 }
2019             } else if (!strcmp(key, "GAME")) {
2020                 if (strcmp(val, me->ourgame->name)) {
2021                     ret = "Save file is from a different game";
2022                     goto cleanup;
2023                 }
2024             } else if (!strcmp(key, "PARAMS")) {
2025                 sfree(data.parstr);
2026                 data.parstr = val;
2027                 val = NULL;
2028             } else if (!strcmp(key, "CPARAMS")) {
2029                 sfree(data.cparstr);
2030                 data.cparstr = val;
2031                 val = NULL;
2032             } else if (!strcmp(key, "SEED")) {
2033                 sfree(data.seed);
2034                 data.seed = val;
2035                 val = NULL;
2036             } else if (!strcmp(key, "DESC")) {
2037                 sfree(data.desc);
2038                 data.desc = val;
2039                 val = NULL;
2040             } else if (!strcmp(key, "PRIVDESC")) {
2041                 sfree(data.privdesc);
2042                 data.privdesc = val;
2043                 val = NULL;
2044             } else if (!strcmp(key, "AUXINFO")) {
2045                 unsigned char *tmp;
2046                 int len = strlen(val) / 2;   /* length in bytes */
2047                 tmp = hex2bin(val, len);
2048                 obfuscate_bitmap(tmp, len*8, TRUE);
2049
2050                 sfree(data.auxinfo);
2051                 data.auxinfo = snewn(len + 1, char);
2052                 memcpy(data.auxinfo, tmp, len);
2053                 data.auxinfo[len] = '\0';
2054                 sfree(tmp);
2055             } else if (!strcmp(key, "UI")) {
2056                 sfree(data.uistr);
2057                 data.uistr = val;
2058                 val = NULL;
2059             } else if (!strcmp(key, "TIME")) {
2060                 data.elapsed = (float)atof(val);
2061             } else if (!strcmp(key, "NSTATES")) {
2062                 data.nstates = atoi(val);
2063                 if (data.nstates <= 0) {
2064                     ret = "Number of states in save file was negative";
2065                     goto cleanup;
2066                 }
2067                 if (data.states) {
2068                     ret = "Two state counts provided in save file";
2069                     goto cleanup;
2070                 }
2071                 data.states = snewn(data.nstates, struct midend_state_entry);
2072                 for (i = 0; i < data.nstates; i++) {
2073                     data.states[i].state = NULL;
2074                     data.states[i].movestr = NULL;
2075                     data.states[i].movetype = NEWGAME;
2076                 }
2077             } else if (!strcmp(key, "STATEPOS")) {
2078                 data.statepos = atoi(val);
2079             } else if (!strcmp(key, "MOVE")) {
2080                 gotstates++;
2081                 data.states[gotstates].movetype = MOVE;
2082                 data.states[gotstates].movestr = val;
2083                 val = NULL;
2084             } else if (!strcmp(key, "SOLVE")) {
2085                 gotstates++;
2086                 data.states[gotstates].movetype = SOLVE;
2087                 data.states[gotstates].movestr = val;
2088                 val = NULL;
2089             } else if (!strcmp(key, "RESTART")) {
2090                 gotstates++;
2091                 data.states[gotstates].movetype = RESTART;
2092                 data.states[gotstates].movestr = val;
2093                 val = NULL;
2094             }
2095         }
2096
2097         sfree(val);
2098         val = NULL;
2099     }
2100
2101     data.params = me->ourgame->default_params();
2102     me->ourgame->decode_params(data.params, data.parstr);
2103     if (me->ourgame->validate_params(data.params, TRUE)) {
2104         ret = "Long-term parameters in save file are invalid";
2105         goto cleanup;
2106     }
2107     data.cparams = me->ourgame->default_params();
2108     me->ourgame->decode_params(data.cparams, data.cparstr);
2109     if (me->ourgame->validate_params(data.cparams, FALSE)) {
2110         ret = "Short-term parameters in save file are invalid";
2111         goto cleanup;
2112     }
2113     if (data.seed && me->ourgame->validate_params(data.cparams, TRUE)) {
2114         /*
2115          * The seed's no use with this version, but we can perfectly
2116          * well use the rest of the data.
2117          */
2118         sfree(data.seed);
2119         data.seed = NULL;
2120     }
2121     if (!data.desc) {
2122         ret = "Game description in save file is missing";
2123         goto cleanup;
2124     } else if (me->ourgame->validate_desc(data.cparams, data.desc)) {
2125         ret = "Game description in save file is invalid";
2126         goto cleanup;
2127     }
2128     if (data.privdesc &&
2129         me->ourgame->validate_desc(data.cparams, data.privdesc)) {
2130         ret = "Game private description in save file is invalid";
2131         goto cleanup;
2132     }
2133     if (data.statepos < 0 || data.statepos >= data.nstates) {
2134         ret = "Game position in save file is out of range";
2135     }
2136
2137     data.states[0].state = me->ourgame->new_game(
2138         me, data.cparams, data.privdesc ? data.privdesc : data.desc);
2139     for (i = 1; i < data.nstates; i++) {
2140         assert(data.states[i].movetype != NEWGAME);
2141         switch (data.states[i].movetype) {
2142           case MOVE:
2143           case SOLVE:
2144             data.states[i].state = me->ourgame->execute_move(
2145                 data.states[i-1].state, data.states[i].movestr);
2146             if (data.states[i].state == NULL) {
2147                 ret = "Save file contained an invalid move";
2148                 goto cleanup;
2149             }
2150             break;
2151           case RESTART:
2152             if (me->ourgame->validate_desc(
2153                     data.cparams, data.states[i].movestr)) {
2154                 ret = "Save file contained an invalid restart move";
2155                 goto cleanup;
2156             }
2157             data.states[i].state = me->ourgame->new_game(
2158                 me, data.cparams, data.states[i].movestr);
2159             break;
2160         }
2161     }
2162
2163     data.ui = me->ourgame->new_ui(data.states[0].state);
2164     me->ourgame->decode_ui(data.ui, data.uistr);
2165
2166     /*
2167      * Run the externally provided check function, and abort if it
2168      * returns an error message.
2169      */
2170     if (check && (ret = check(cctx, me, &data)) != NULL)
2171         goto cleanup;            /* error message is already in ret */
2172
2173     /*
2174      * Now we've run out of possible error conditions, so we're
2175      * ready to start overwriting the real data in the current
2176      * midend. We'll do this by swapping things with the local
2177      * variables, so that the same cleanup code will free the old
2178      * stuff.
2179      */
2180     {
2181         char *tmp;
2182
2183         tmp = me->desc;
2184         me->desc = data.desc;
2185         data.desc = tmp;
2186
2187         tmp = me->privdesc;
2188         me->privdesc = data.privdesc;
2189         data.privdesc = tmp;
2190
2191         tmp = me->seedstr;
2192         me->seedstr = data.seed;
2193         data.seed = tmp;
2194
2195         tmp = me->aux_info;
2196         me->aux_info = data.auxinfo;
2197         data.auxinfo = tmp;
2198     }
2199
2200     me->genmode = GOT_NOTHING;
2201
2202     me->statesize = data.nstates;
2203     data.nstates = me->nstates;
2204     me->nstates = me->statesize;
2205     {
2206         struct midend_state_entry *tmp;
2207         tmp = me->states;
2208         me->states = data.states;
2209         data.states = tmp;
2210     }
2211     me->statepos = data.statepos;
2212
2213     /*
2214      * Don't save the "new game undo" state.  So "new game" twice or
2215      * (in some environments) switching away and back, will make a
2216      * "new game" irreversible.  Maybe in the future we will have a
2217      * more sophisticated way to decide when to discard the previous
2218      * game state.
2219      */
2220     me->newgame_undo_len = 0;
2221
2222     {
2223         game_params *tmp;
2224
2225         tmp = me->params;
2226         me->params = data.params;
2227         data.params = tmp;
2228
2229         tmp = me->curparams;
2230         me->curparams = data.cparams;
2231         data.cparams = tmp;
2232     }
2233
2234     me->oldstate = NULL;
2235     me->anim_time = me->anim_pos = me->flash_time = me->flash_pos = 0.0F;
2236     me->dir = 0;
2237
2238     {
2239         game_ui *tmp;
2240
2241         tmp = me->ui;
2242         me->ui = data.ui;
2243         data.ui = tmp;
2244     }
2245
2246     me->elapsed = data.elapsed;
2247     me->pressed_mouse_button = 0;
2248
2249     midend_set_timer(me);
2250
2251     if (me->drawstate)
2252         me->ourgame->free_drawstate(me->drawing, me->drawstate);
2253     me->drawstate =
2254         me->ourgame->new_drawstate(me->drawing,
2255                                    me->states[me->statepos-1].state);
2256     midend_size_new_drawstate(me);
2257     if (me->game_id_change_notify_function)
2258         me->game_id_change_notify_function(me->game_id_change_notify_ctx);
2259
2260     ret = NULL;                        /* success! */
2261
2262     cleanup:
2263     sfree(val);
2264     sfree(data.seed);
2265     sfree(data.parstr);
2266     sfree(data.cparstr);
2267     sfree(data.desc);
2268     sfree(data.privdesc);
2269     sfree(data.auxinfo);
2270     sfree(data.uistr);
2271     if (data.params)
2272         me->ourgame->free_params(data.params);
2273     if (data.cparams)
2274         me->ourgame->free_params(data.cparams);
2275     if (data.ui)
2276         me->ourgame->free_ui(data.ui);
2277     if (data.states) {
2278         int i;
2279
2280         for (i = 0; i < data.nstates; i++) {
2281             if (data.states[i].state)
2282                 me->ourgame->free_game(data.states[i].state);
2283             sfree(data.states[i].movestr);
2284         }
2285         sfree(data.states);
2286     }
2287
2288     return ret;
2289 }
2290
2291 const char *midend_deserialise(
2292     midend *me, int (*read)(void *ctx, void *buf, int len), void *rctx)
2293 {
2294     return midend_deserialise_internal(me, read, rctx, NULL, NULL);
2295 }
2296
2297 /*
2298  * This function examines a saved game file just far enough to
2299  * determine which game type it contains. It returns NULL on success
2300  * and the game name string in 'name' (which will be dynamically
2301  * allocated and should be caller-freed), or an error message on
2302  * failure.
2303  */
2304 const char *identify_game(char **name,
2305                           int (*read)(void *ctx, void *buf, int len),
2306                           void *rctx)
2307 {
2308     int nstates = 0, statepos = -1, gotstates = 0;
2309     int started = FALSE;
2310
2311     char *val = NULL;
2312     /* Initially all errors give the same report */
2313     const char *ret = "Data does not appear to be a saved game file";
2314
2315     *name = NULL;
2316
2317     /*
2318      * Loop round and round reading one key/value pair at a time from
2319      * the serialised stream, until we've found the game name.
2320      */
2321     while (nstates <= 0 || statepos < 0 || gotstates < nstates-1) {
2322         char key[9], c;
2323         int len;
2324
2325         do {
2326             if (!read(rctx, key, 1)) {
2327                 /* unexpected EOF */
2328                 goto cleanup;
2329             }
2330         } while (key[0] == '\r' || key[0] == '\n');
2331
2332         if (!read(rctx, key+1, 8)) {
2333             /* unexpected EOF */
2334             goto cleanup;
2335         }
2336
2337         if (key[8] != ':') {
2338             if (started)
2339                 ret = "Data was incorrectly formatted for a saved game file";
2340             goto cleanup;
2341         }
2342         len = strcspn(key, ": ");
2343         assert(len <= 8);
2344         key[len] = '\0';
2345
2346         len = 0;
2347         while (1) {
2348             if (!read(rctx, &c, 1)) {
2349                 /* unexpected EOF */
2350                 goto cleanup;
2351             }
2352
2353             if (c == ':') {
2354                 break;
2355             } else if (c >= '0' && c <= '9') {
2356                 len = (len * 10) + (c - '0');
2357             } else {
2358                 if (started)
2359                     ret = "Data was incorrectly formatted for a"
2360                     " saved game file";
2361                 goto cleanup;
2362             }
2363         }
2364
2365         val = snewn(len+1, char);
2366         if (!read(rctx, val, len)) {
2367             if (started)
2368             goto cleanup;
2369         }
2370         val[len] = '\0';
2371
2372         if (!started) {
2373             if (strcmp(key, "SAVEFILE") || strcmp(val, SERIALISE_MAGIC)) {
2374                 /* ret already has the right message in it */
2375                 goto cleanup;
2376             }
2377             /* Now most errors are this one, unless otherwise specified */
2378             ret = "Saved data ended unexpectedly";
2379             started = TRUE;
2380         } else {
2381             if (!strcmp(key, "VERSION")) {
2382                 if (strcmp(val, SERIALISE_VERSION)) {
2383                     ret = "Cannot handle this version of the saved game"
2384                         " file format";
2385                     goto cleanup;
2386                 }
2387             } else if (!strcmp(key, "GAME")) {
2388                 *name = dupstr(val);
2389                 ret = NULL;
2390                 goto cleanup;
2391             }
2392         }
2393
2394         sfree(val);
2395         val = NULL;
2396     }
2397
2398     cleanup:
2399     sfree(val);
2400     return ret;
2401 }
2402
2403 const char *midend_print_puzzle(midend *me, document *doc, int with_soln)
2404 {
2405     game_state *soln = NULL;
2406
2407     if (me->statepos < 1)
2408         return "No game set up to print";/* _shouldn't_ happen! */
2409
2410     if (with_soln) {
2411         const char *msg;
2412         char *movestr;
2413
2414         if (!me->ourgame->can_solve)
2415             return "This game does not support the Solve operation";
2416
2417         msg = "Solve operation failed";/* game _should_ overwrite on error */
2418         movestr = me->ourgame->solve(me->states[0].state,
2419                                      me->states[me->statepos-1].state,
2420                                      me->aux_info, &msg);
2421         if (!movestr)
2422             return msg;
2423         soln = me->ourgame->execute_move(me->states[me->statepos-1].state,
2424                                          movestr);
2425         assert(soln);
2426
2427         sfree(movestr);
2428     } else
2429         soln = NULL;
2430
2431     /*
2432      * This call passes over ownership of the two game_states and
2433      * the game_params. Hence we duplicate the ones we want to
2434      * keep, and we don't have to bother freeing soln if it was
2435      * non-NULL.
2436      */
2437     document_add_puzzle(doc, me->ourgame,
2438                         me->ourgame->dup_params(me->curparams),
2439                         me->ourgame->dup_game(me->states[0].state), soln);
2440
2441     return NULL;
2442 }