Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(save): versioned save/load with migration over Storage (T4)

yhh192aa99fccba
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.ts
index 1d4a02f38..96d51a243 100644
--- a/sdk/src/core-sys.ts
+++ b/sdk/src/core-sys.ts
@@ -39,6 +39,19 @@ export {
type PluralSelector,
} from './i18n';
+// =============================================================================
+// Save / load (versioned persistence with migration)
+// =============================================================================
+
+export {
+ SaveManager,
+ migrateSaveData,
+ type SaveEnvelope,
+ type SaveMigration,
+ type SaveStorage,
+ type SaveManagerOptions,
+} from './saveGame';
+
// =============================================================================
// Entity Utils
// =============================================================================
diff --git a/sdk/src/saveGame.ts b/sdk/src/saveGame.ts
new file mode 100644
index 000000000..861467305
--- /dev/null
+++ b/sdk/src/saveGame.ts
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file saveGame.ts
+ * @brief Versioned save/load with migration, over the Storage API. A save is a
+ * `{ version, data, savedAt }` envelope; on load, older saves are run
+ * forward through a migration chain to the current version — so a
+ * shipped game can evolve its save shape without bricking old saves.
+ */
+
+import { Storage } from './storage';
+
+export interface SaveEnvelope<T> {
+ /** Schema version the `data` was written at. */
+ version: number;
+ data: T;
+ /** Epoch ms the save was written. */
+ savedAt: number;
+}
+
+/** Migrates save data from version N to N+1. Keyed by the source version N. */
+export type SaveMigration = (data: unknown) => unknown;
+
+/**
+ * Bring `data` (written at `version`) forward to `currentVersion` by applying
+ * `migrations[version]`, `migrations[version+1]`, … in order. Pure.
+ * Throws if the save is newer than current (no downgrade) or a step is missing.
+ */
+export function migrateSaveData(
+ version: number,
+ data: unknown,
+ currentVersion: number,
+ migrations: Record<number, SaveMigration>,
+): unknown {
+ if (version > currentVersion) {
+ throw new Error(`save version ${version} is newer than the current version ${currentVersion}`);
+ }
+ let d = data;
+ for (let v = version; v < currentVersion; v++) {
+ const step = migrations[v];
+ if (!step) throw new Error(`missing save migration for version ${v} -> ${v + 1}`);
+ d = step(d);
+ }
+ return d;
+}
+
+/** The slice of the Storage API SaveManager needs (injectable for tests). */
+export interface SaveStorage {
+ getJSON<T>(key: string, defaultValue?: T): T | undefined;
+ setJSON<T>(key: string, value: T): void;
+ remove(key: string): void;
+ has(key: string): boolean;
+}
+
+export interface SaveManagerOptions {
+ /** Current save schema version. */
+ version: number;
+ /** Migration chain; `migrations[n]` upgrades version n → n+1. */
+ migrations?: Record<number, SaveMigration>;
+ /** Storage backend (defaults to the engine's Storage). */
+ storage?: SaveStorage;
+ /** Clock for `savedAt` (defaults to Date.now); inject for deterministic tests. */
+ now?: () => number;
+ /** Key prefix for slots (defaults to `save:`). */
+ keyPrefix?: string;
+}
+
+/**
+ * Named save slots with schema versioning + migration. `save(slot, data)` stamps
+ * the current version; `load(slot)` migrates an older save forward and returns
+ * its data (or null when the slot is empty / unreadable).
+ */
+export class SaveManager {
+ private readonly version: number;
+ private readonly migrations: Record<number, SaveMigration>;
+ private readonly storage: SaveStorage;
+ private readonly now: () => number;
+ private readonly prefix: string;
+
+ constructor(opts: SaveManagerOptions) {
+ this.version = opts.version;
+ this.migrations = opts.migrations ?? {};
+ this.storage = opts.storage ?? Storage;
+ this.now = opts.now ?? (() => Date.now());
+ this.prefix = opts.keyPrefix ?? 'save:';
+ }
+
+ save<T>(slot: string, data: T): void {
+ const env: SaveEnvelope<T> = { version: this.version, data, savedAt: this.now() };
+ this.storage.setJSON(this.key_(slot), env);
+ }
+
+ /** Load + migrate a slot's data, or null if empty/unreadable. */
+ load<T>(slot: string): T | null {
+ const env = this.storage.getJSON<SaveEnvelope<unknown>>(this.key_(slot));
+ if (!env || typeof env.version !== 'number') return null;
+ return migrateSaveData(env.version, env.data, this.version, this.migrations) as T;
+ }
+
+ has(slot: string): boolean {
+ return this.storage.has(this.key_(slot));
+ }
+
+ remove(slot: string): void {
+ this.storage.remove(this.key_(slot));
+ }
+
+ /** When the slot was written (epoch ms), or null if empty. */
+ savedAt(slot: string): number | null {
+ const env = this.storage.getJSON<SaveEnvelope<unknown>>(this.key_(slot));
+ return env && typeof env.savedAt === 'number' ? env.savedAt : null;
+ }
+
+ private key_(slot: string): string {
+ return this.prefix + slot;
+ }
+}
diff --git a/sdk/tests/saveGame.test.ts b/sdk/tests/saveGame.test.ts
new file mode 100644
index 000000000..ae13e1b3e
--- /dev/null
+++ b/sdk/tests/saveGame.test.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { SaveManager, migrateSaveData, type SaveStorage } from '../src/saveGame';
+
+describe('migrateSaveData', () => {
+ const migrations = {
+ 1: (d: any) => ({ ...d, level: d.stage ?? 1 }), // v1 -> v2: rename stage→level
+ 2: (d: any) => ({ ...d, coins: d.coins ?? 0 }), // v2 -> v3: add coins
+ };
+
+ it('applies the chain from the save version to current', () => {
+ const out = migrateSaveData(1, { stage: 5 }, 3, migrations) as any;
+ expect(out).toEqual({ stage: 5, level: 5, coins: 0 });
+ });
+
+ it('no-op when already current', () => {
+ expect(migrateSaveData(3, { coins: 9 }, 3, migrations)).toEqual({ coins: 9 });
+ });
+
+ it('runs only the needed tail of the chain', () => {
+ expect(migrateSaveData(2, { level: 2 }, 3, migrations)).toEqual({ level: 2, coins: 0 });
+ });
+
+ it('throws on a missing migration step', () => {
+ expect(() => migrateSaveData(1, {}, 3, { 2: (d) => d })).toThrow(/migration for version 1/);
+ });
+
+ it('throws when the save is newer than current (no downgrade)', () => {
+ expect(() => migrateSaveData(5, {}, 3, migrations)).toThrow(/newer than/);
+ });
+});
+
+function memStorage(): SaveStorage & { _map: Map<string, string> } {
+ const map = new Map<string, string>();
+ return {
+ _map: map,
+ getJSON<T>(key: string, def?: T): T | undefined {
+ const raw = map.get(key);
+ return raw === undefined ? def : (JSON.parse(raw) as T);
+ },
+ setJSON<T>(key: string, value: T): void { map.set(key, JSON.stringify(value)); },
+ remove(key: string): void { map.delete(key); },
+ has(key: string): boolean { return map.has(key); },
+ };
+}
+
+describe('SaveManager', () => {
+ it('round-trips data with version + savedAt', () => {
+ const storage = memStorage();
+ const mgr = new SaveManager({ version: 1, storage, now: () => 1234 });
+ mgr.save('slot0', { hp: 10 });
+ expect(mgr.load<{ hp: number }>('slot0')).toEqual({ hp: 10 });
+ expect(mgr.savedAt('slot0')).toBe(1234);
+ // envelope shape persisted under the prefixed key
+ expect(JSON.parse(storage._map.get('save:slot0')!)).toEqual({ version: 1, data: { hp: 10 }, savedAt: 1234 });
+ });
+
+ it('migrates an older save on load', () => {
+ const storage = memStorage();
+ // Write a v1 save directly.
+ new SaveManager({ version: 1, storage, now: () => 0 }).save('s', { stage: 3 });
+ // Load with a current-version-2 manager + migration.
+ const mgr = new SaveManager({
+ version: 2, storage,
+ migrations: { 1: (d: any) => ({ level: d.stage }) },
+ });
+ expect(mgr.load('s')).toEqual({ level: 3 });
+ });
+
+ it('has / remove / missing slot', () => {
+ const storage = memStorage();
+ const mgr = new SaveManager({ version: 1, storage });
+ expect(mgr.load('none')).toBeNull();
+ expect(mgr.savedAt('none')).toBeNull();
+ expect(mgr.has('none')).toBe(false);
+ mgr.save('a', { x: 1 });
+ expect(mgr.has('a')).toBe(true);
+ mgr.remove('a');
+ expect(mgr.has('a')).toBe(false);
+ });
+
+ it('honors a custom key prefix', () => {
+ const storage = memStorage();
+ new SaveManager({ version: 1, storage, keyPrefix: 'game/', now: () => 0 }).save('1', { a: 1 });
+ expect(storage._map.has('game/1')).toBe(true);
+ });
+});