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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { PlatformAdapter } from 'esengine';
interface SerializedStorage {
load(): Promise<string>;
save(data: string): Promise<void>;
}
interface AsyncStorageOptions {
maxBytes: number;
/** Best-effort milestone writes; callers await flushStorage for a result. */
autoSave?: boolean;
warn?(error: unknown): void;
}
type StorageAdapter = Pick<PlatformAdapter, 'getStorageItem' | 'setStorageItem' | 'removeStorageItem' | 'clearStorage' | 'flushStorage'>;
/** Loaded state remains local to this realm; only the host owns persistence. */
export function createAsyncStorage(source: SerializedStorage, options: AsyncStorageOptions) {
let loaded = false;
let loading: Promise<void> | null = null;
let values: Record<string, string> = Object.create(null);
let revision = 0, savedRevision = 0;
let inFlight: Promise<void> | null = null;
let autoSaving = false;
const requireLoaded = () => { if (!loaded) throw new Error('Async storage unavailable: load must succeed before reading or writing'); };
const encode = (items: Record<string, string>) => {
const data = JSON.stringify({ version: 1, items });
if (new TextEncoder().encode(data).byteLength > options.maxBytes) throw new Error('Async storage exceeds the host byte limit');
return data;
};
async function flush(): Promise<void> {
requireLoaded();
const target = revision;
while (savedRevision < target) {
if (!inFlight) {
const writingRevision = revision, data = encode(values);
// Defer the host call until the shared promise is installed, even if it throws synchronously.
inFlight = Promise.resolve().then(() => source.save(data)).then(() => {
savedRevision = writingRevision;
}).finally(() => { inFlight = null; });
}
await inFlight;
}
}
function schedule(): void {
if (!options.autoSave || autoSaving) return;
autoSaving = true;
let succeeded = false;
void Promise.resolve().then(flush).then(() => { succeeded = true; }, error => {
try { options.warn?.(error); } catch { /* diagnostics cannot create unhandled save rejections */ }
}).finally(() => {
autoSaving = false;
// Never spin on a failed save; a later mutation or explicit flush retries it.
if (succeeded && revision > savedRevision) schedule();
});
}
function mutate(change: (next: Record<string, string>) => boolean): void {
requireLoaded();
const next: Record<string, string> = Object.assign(Object.create(null), values);
if (!change(next)) return;
encode(next); values = next; revision++; schedule();
}
const adapter: StorageAdapter = {
getStorageItem(key) { requireLoaded(); return values[key] ?? null; },
setStorageItem(key, value) {
if (typeof value !== 'string') throw new Error('Storage values must be strings');
mutate(next => { if (next[key] === value) return false; next[key] = value; return true; });
},
removeStorageItem(key) { mutate(next => { if (!Object.hasOwn(next, key)) return false; delete next[key]; return true; }); },
clearStorage(prefix) { mutate(next => {
let changed = false;
for (const key of Object.keys(next)) if (key.startsWith(prefix)) { delete next[key]; changed = true; }
return changed;
}); },
flushStorage: flush,
};
return {
adapter,
get dirty(): boolean { return revision > savedRevision; },
load(): Promise<void> {
if (loaded) return Promise.resolve();
if (loading) return loading;
loading = Promise.resolve().then(() => source.load()).then(raw => {
const parsed: unknown = raw === '' ? { version: 1, items: {} } : JSON.parse(raw);
if (!parsed || typeof parsed !== 'object' || !('version' in parsed) || parsed.version !== 1
|| Object.keys(parsed).some(key => key !== 'version' && key !== 'items')
|| !('items' in parsed) || !parsed.items || typeof parsed.items !== 'object' || Array.isArray(parsed.items)
|| Object.values(parsed.items).some(value => typeof value !== 'string')) {
throw new Error('Unsupported async storage envelope; existing host data was preserved');
}
const next: Record<string, string> = Object.assign(Object.create(null), parsed.items);
encode(next); values = next; loaded = true;
}).finally(() => { loading = null; });
return loading;
},
};
}