feat(replay): "Continue game from here" in Replay Viewer (fixes #5647)

docs/Replays.md

@@ -107,11 +107,18 @@ You need a game record. Either:
   hash mismatch if the core has changed since.
 
 ```bash
-GAME=dqKzit4cWu # the game's ID
-mkdir -p /tmp/records && cp "$GAME.json" /tmp/records/
-# The dev client expects its API on 8787. Other API calls will 404.
-npx tsx scripts/replay/stub-game-api.mts /tmp/records 8787
-npm run dev
+# Generate a demo record:
+npm run replay:demo
+
+# Run client, server, and replay stub API concurrently:
+npm run dev:all
+```
+
+Then open `http://localhost:9000/#replay-viewer=demoGame1`.
+You can also test with real games from production using:
+
+```bash
+npm run dev:prod
 ```
 
 Then open `http://localhost:9000/#replay-viewer=<gameID>`.

package.json

@@ -15,9 +15,12 @@
     "start:server": "tsx src/server/Server.ts",
     "start:server-dev": "cross-env GAME_ENV=dev TURNSTILE_SITE_KEY=1x00000000000000000000AA API_KEY=WARNING_DEV_API_KEY_DO_NOT_USE_IN_PRODUCTION ADMIN_BOT_API_KEY=WARNING_DEV_ADMIN_BOT_KEY_DO_NOT_USE_IN_PRODUCTION DOMAIN=localhost GIT_COMMIT=DEV tsx src/server/Server.ts",
     "dev": "cross-env GAME_ENV=dev concurrently \"npm run start:client\" \"npm run start:server-dev\"",
+    "dev:all": "cross-env GAME_ENV=dev concurrently \"npm run start:client\" \"npm run start:server-dev\" \"npm run replay:api\"",
     "dev:host": "cross-env GAME_ENV=dev VITE_HOST=lan concurrently \"npm run start:client\" \"npm run start:server-dev\"",
     "dev:staging": "cross-env GAME_ENV=dev API_DOMAIN=api.openfront.dev concurrently \"npm run start:client\" \"npm run start:server-dev\"",
     "dev:prod": "cross-env GAME_ENV=dev API_DOMAIN=api.openfront.io concurrently \"npm run start:client\" \"npm run start:server-dev\"",
+    "replay:api": "tsx scripts/replay/stub-game-api.mts records 8787",
+    "replay:demo": "tsx scripts/replay/record-demo.mts records/demoGame1.json 1500 demoGame1",
     "docs:map-generator": "cd map-generator && go doc -cmd -u -all",
     "tunnel": "npm run build-prod && npm run start:server",
     "test": "vitest run",

packages/engine-api/src/game/GameUpdates.ts

@@ -142,6 +142,16 @@ export type GameUpdate =
   | GamePausedUpdate
   | DonateEventUpdate;
 
+export function createGameUpdatesMap(): GameUpdates {
+  const map = {} as GameUpdates;
+  Object.values(GameUpdateType)
+    .filter((key) => !isNaN(Number(key)))
+    .forEach((key) => {
+      map[key as GameUpdateType] = [];
+    });
+  return map;
+}
+
 export interface BonusEventUpdate {
   type: GameUpdateType.BonusEvent;
   player: PlayerID;

packages/engine-api/src/worker/WorkerMessages.ts

@@ -1,6 +1,7 @@
 import { TileRef } from "../game/GameMap";
 import {
   BuildableUnit,
+  Difficulty,
   HumanStatsSnapshot,
   PlayerActions,
   PlayerBorderTiles,
@@ -38,6 +39,9 @@ export type WorkerMessageType =
   | "transport_ship_spawn_result"
   | "snapshot"
   | "snapshot_result"
+  | "extract_snapshot"
+  | "extract_snapshot_result"
+  | "extract_snapshot_error"
   | "human_stats"
   | "human_stats_result";
 
@@ -86,6 +90,7 @@ export interface RunTurnsMessage extends BaseWorkerMessage {
 // Messages from worker to main thread
 export interface InitializedMessage extends BaseWorkerMessage {
   type: "initialized";
+  initialUpdate?: GameUpdateViewData;
 }
 
 /** The game couldn't be started; `error` says why. */
@@ -201,6 +206,31 @@ export interface SnapshotResultMessage extends BaseWorkerMessage {
   type: "snapshot_result";
   /** Uncompressed; null if the snapshot failed (see the worker log). */
   snapshot: Uint8Array | null;
+  tick: number;
+}
+
+export interface ExtractSnapshotMessage extends BaseWorkerMessage {
+  type: "extract_snapshot";
+  gameStartInfo: GameStartInfo;
+  turns: Turn[];
+  map: MapFiles;
+  targetTick: number;
+  chosenPlayerID: PlayerID;
+  localClientID: ClientID;
+  difficulty?: Difficulty;
+  newGameID?: string;
+}
+
+export interface ExtractSnapshotResultMessage extends BaseWorkerMessage {
+  type: "extract_snapshot_result";
+  snapshot: Uint8Array;
+  gameStartInfo: GameStartInfo;
+  tick: number;
+}
+
+export interface ExtractSnapshotErrorMessage extends BaseWorkerMessage {
+  type: "extract_snapshot_error";
+  error: string;
 }
 
 export interface HumanStatsMessage extends BaseWorkerMessage {
@@ -225,6 +255,7 @@ export type MainThreadMessage =
   | AttackClusteredPositionsMessage
   | TransportShipSpawnMessage
   | SnapshotMessage
+  | ExtractSnapshotMessage
   | HumanStatsMessage;
 
 // Message send from worker
@@ -243,4 +274,6 @@ export type WorkerMessage =
   | AttackClusteredPositionsResultMessage
   | TransportShipSpawnResultMessage
   | SnapshotResultMessage
+  | ExtractSnapshotResultMessage
+  | ExtractSnapshotErrorMessage
   | HumanStatsResultMessage;

packages/engine-lib/package.json

@@ -8,6 +8,7 @@
   },
   "dependencies": {
     "@openfront/engine-api": "0.0.0",
+    "@openfront/zbin": "0.0.0",
     "zod": "^4.4.2"
   }
 }

packages/engine-lib/src/snapshot/MapSnapshot.ts

@@ -0,0 +1,169 @@
+import { GameMap } from "@openfront/engine-api/game/GameMap";
+import { GameConfig, GameConfigSchema } from "@openfront/engine-api/Schemas";
+import { z } from "zod";
+import { GameMapImpl, GameMapSnapshot } from "../game/GameMapImpl";
+import { decodeSnapshotValue } from "./SnapshotCodec";
+import {
+  readVersioned,
+  SnapshotError,
+  VersionedSchema,
+  zInt,
+  zTiles,
+} from "./SnapshotType";
+
+export const SNAPSHOT_MAGIC = "OpenFrontGameSnapshot";
+
+/**
+ * Version of the root layout below. Everything inside it carries its own
+ * record version, so this only moves when the root itself changes.
+ */
+export const SNAPSHOT_FORMAT_VERSION = 1;
+
+export const ExecRecordSchema = z.object({
+  t: z.string(),
+  v: z.number().int(),
+  d: z.unknown(),
+});
+
+export const RootSchema = z.object({
+  magic: z.literal(SNAPSHOT_MAGIC),
+  format: z.number().int(),
+  /** Build that wrote the snapshot. Informational: any build can read it. */
+  gitCommit: z.string(),
+  gameID: z.string().nullable(),
+  tick: z.number().int(),
+  gameConfig: z.unknown(),
+  game: VersionedSchema,
+  map: VersionedSchema,
+  miniMap: VersionedSchema,
+  players: z.array(VersionedSchema),
+  units: z.array(VersionedSchema),
+  attacks: z.array(VersionedSchema),
+  alliances: z.array(VersionedSchema),
+  allianceRequests: z.array(VersionedSchema),
+  stations: z.array(VersionedSchema),
+  railroads: z.array(VersionedSchema),
+  clusters: z.array(VersionedSchema),
+  execs: z.array(ExecRecordSchema),
+});
+export type Root = z.infer<typeof RootSchema>;
+
+export function decodeRoot(bytes: Uint8Array): Root {
+  let raw: unknown;
+  try {
+    raw = decodeSnapshotValue(bytes);
+  } catch (e) {
+    throw new SnapshotError(`not a game snapshot: ${String(e)}`);
+  }
+  if (
+    typeof raw !== "object" ||
+    raw === null ||
+    (raw as { magic?: unknown }).magic !== SNAPSHOT_MAGIC
+  ) {
+    throw new SnapshotError("not a game snapshot");
+  }
+  const format = (raw as { format?: unknown }).format;
+  if (typeof format !== "number" || !Number.isInteger(format) || format < 1) {
+    throw new SnapshotError(`invalid snapshot format: ${String(format)}`);
+  }
+  if (format > SNAPSHOT_FORMAT_VERSION) {
+    throw new SnapshotError(
+      `snapshot format ${String(format)} is newer than this build supports (${SNAPSHOT_FORMAT_VERSION})`,
+    );
+  }
+  const root = RootSchema.safeParse(raw);
+  if (!root.success) {
+    throw new SnapshotError(`malformed snapshot: ${root.error.message}`);
+  }
+  return root.data;
+}
+
+export function readStartTick(d: unknown): number | null {
+  if (typeof d !== "object" || d === null) return null;
+  const v = (d as { startTick?: unknown }).startTick;
+  return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
+
+export interface SnapshotHeader {
+  format: number;
+  gitCommit: string;
+  gameID: string | null;
+  tick: number;
+  gameConfig: GameConfig;
+  startTick?: number | null;
+}
+
+/** Reads what a restore needs to load first: the config and the map. */
+export function readSnapshotHeader(bytes: Uint8Array): SnapshotHeader {
+  const root = decodeRoot(bytes);
+  return {
+    format: root.format,
+    gitCommit: root.gitCommit,
+    gameID: root.gameID,
+    tick: root.tick,
+    gameConfig: GameConfigSchema.parse(root.gameConfig),
+    startTick: readStartTick(root.game?.d),
+  };
+}
+
+const PlayerTilesSchema = z
+  .object({
+    smallID: zInt(),
+    info: z.object({
+      id: z.string(),
+    }),
+    tiles: zTiles(),
+  })
+  .passthrough();
+
+export interface RestoredMapsResult {
+  tick: number;
+  startTick: number | null;
+}
+
+/**
+ * Restores map edits (water nukes, fallout, defense) and tile ownership from a
+ * snapshot onto freshly loaded map instances. Used on the client so GameView's
+ * local maps match the simulation state without waiting for per-tile deltas.
+ */
+export function restoreMapsFromSnapshot(
+  bytes: Uint8Array,
+  gameMap: GameMap,
+  miniGameMap?: GameMap,
+): RestoredMapsResult {
+  const root = decodeRoot(bytes);
+  (gameMap as GameMapImpl).restoreSnapshot(
+    readVersioned(GameMapSnapshot, root.map),
+  );
+  if (miniGameMap) {
+    (miniGameMap as GameMapImpl).restoreSnapshot(
+      readVersioned(GameMapSnapshot, root.miniMap),
+    );
+  }
+  const players = root.players.map((p) => {
+    const parsed = PlayerTilesSchema.safeParse(p.d);
+    if (!parsed.success) {
+      throw new SnapshotError(
+        `Player v${p.v}: invalid data: ${parsed.error.message}`,
+      );
+    }
+    return parsed.data;
+  });
+  for (const p of players) {
+    const id = p.smallID;
+    const tiles = p.tiles;
+    for (let i = 0; i < tiles.length; i++) {
+      const tile = tiles[i];
+      if (!gameMap.isValidRef(tile)) {
+        throw new SnapshotError(
+          `invalid tile ref ${tile} for player ${p.info.id}`,
+        );
+      }
+      gameMap.setOwnerID(tile, id);
+    }
+  }
+  return {
+    tick: root.tick,
+    startTick: readStartTick(root.game?.d),
+  };
+}