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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(save): versioned save/load with migration over Storage (T4)
yhh192aa99fccba
diff --git a/sdk/src/core-sys.ts b/sdk/src/core-sys.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ });+});