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(hot-reload): state-preserving fast path — hot-swap system bodies (RC10 P3)
esenginee1208ef42ca1
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex f2696945e..99354a3f4 100644--- a/desktop/src/playHost.ts+++ b/desktop/src/playHost.ts@@ -14,7 +14,7 @@* Everything is same-origin estella:// (host, sdk, bundle, wasm, assets),* sidestepping the custom-scheme cross-fetch ban.*/-import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents } from 'esengine';+import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations } from 'esengine';import type { App, ESEngineModule, SceneData } from 'esengine';import { PLAY_PROTOCOL_VERSION } from './engine/playProtocol';import type { PlayOutbound, PlayInbound } from './engine/playProtocol';@@ -223,9 +223,39 @@ async function boot(msg: InitMessage): Promise<void> {* rebuilt bundle (cache-busted), then rebuilds the App from the play-start* snapshot. ~100ms vs a full realm reboot.*/+/**+ * State-preserving fast path for {@link reload}. Re-imports the rebuilt bundle into a+ * throwaway context (so the live registry is untouched) and, only if the user component+ * schemas are unchanged, hot-swaps the live App's user system bodies in place — keeping+ * the running World/entities. Returns true when the World was kept; false (or on any+ * throw, caught here) means the caller must do the full restart. Component identity is+ * interned by name, so the re-imported systems' queries resolve to the live storage.+ */+async function tryHotSwapReload(): Promise<boolean> {+ if (!app) return false;+ try {+ const liveFingerprint = getUserComponentFingerprint();+ const { fingerprint, pending } = await probeRegistrations(() =>+ import(/* @vite-ignore */ `${bundleUrl}?v=${++reloadSeq}`).then(() => undefined),+ );+ if (fingerprint !== liveFingerprint) return false; // a component's fields changed+ return app.hotSwapSystems(pending as Parameters<App['hotSwapSystems']>[0]);+ } catch {+ return false; // probe/import failure → safe full reload+ }+}+async function reload(): Promise<void> {if (!booted || !engineModule || !lastInit) return;try {+ // Fast path (RC10 P3): if only system logic changed (component schemas unchanged),+ // hot-swap the function bodies and keep the live World — runtime state survives. Any+ // structural change, a component-field edit, or a probe failure falls through to the+ // full restart below (which replays the play-start snapshot, always correct).+ if (app && (await tryHotSwapReload())) {+ post({ type: 'estella:play:ready' });+ return;+ }if (app) {const oldRegistry = app.world.getCppRegistry();app.quit({ keepRenderer: true });diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex dc3371634..0c40b288d 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -259,6 +259,59 @@ export class App {return this.addSystemToSchedule(Schedule.Startup, system);}+ /**+ * Hot-swap the project's (user-authored) system function bodies in place, keeping+ * the live World/Registry/entities — the state-preserving hot-reload fast path+ * (RC10 P3). `incoming` is the freshly re-imported bundle's drained systems.+ *+ * Returns false when the structure changed — a user system was added, removed, or+ * renamed, or a schedule's user-system count differs — because the running systems+ * then no longer line up with the new code, so the caller must full-reload instead.+ * Builtin/plugin systems (those with an owning subsystem) are never touched. The+ * match validates fully before mutating, so a rejected swap leaves the scheduler+ * untouched (no torn half-swap). Component identity is stable by name (see+ * component.ts), so the new functions' queries resolve to the live storage.+ */+ hotSwapSystems(incoming: ReadonlyArray<{ schedule: number; system: SystemDef }>): boolean {+ const bySchedule = new Map<Schedule, SystemDef[]>();+ for (const e of incoming) {+ const arr = bySchedule.get(e.schedule as Schedule);+ if (arr) arr.push(e.system);+ else bySchedule.set(e.schedule as Schedule, [e.system]);+ }+ const userEntries = (s: Schedule): SystemEntry[] =>+ (this.systems_.get(s) ?? []).filter((entry) => entry.subsystem === undefined);++ for (const [schedule, defs] of bySchedule) {+ const live = userEntries(schedule);+ if (live.length !== defs.length) return false;+ for (let i = 0; i < live.length; i++) {+ if (!App.systemNamesCompatible(live[i].system._name, defs[i]._name)) return false;+ }+ }+ // A schedule that had user systems the new bundle didn't re-add is structural.+ for (const [schedule, entries] of this.systems_) {+ if (!bySchedule.has(schedule) && entries.some((e) => e.subsystem === undefined)) return false;+ }++ for (const [schedule, defs] of bySchedule) {+ const live = userEntries(schedule);+ for (let i = 0; i < live.length; i++) {+ const cur = live[i].system;+ live[i].system = { _id: cur._id, _params: defs[i]._params, _fn: defs[i]._fn, _name: cur._name };+ }+ this.sortedSystemsCache_.delete(schedule);+ }+ return true;+ }++ /** A live (scoped) system name and a re-imported raw name refer to the same system+ * if the live one is an explicit name that matches, or both are auto-named (the+ * live `System_N` placeholder ⇔ an unnamed re-import). */+ private static systemNamesCompatible(liveName: string, rawName: string): boolean {+ return /^System_\d+$/.test(liveName) ? rawName === '' : rawName === liveName;+ }+/*** Register every system in `set` onto `schedule`. Each member inherits* the set's `runIf` (AND-combined with its own if supplied per-systemdiff --git a/sdk/src/component.ts b/sdk/src/component.tsindex 6850729b0..967596f39 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -347,6 +347,29 @@ export function getUserComponents(): Map<string, AnyComponentDef> {return userComponents();}+/**+ * A stable digest of the current context's user component schemas — each component's+ * name plus its default field shape (keys + value types, recursively). The hot-reload+ * fast path compares this across a project-bundle re-import: an unchanged digest means+ * only system logic changed (hot-swap, keep the live World); a changed digest means a+ * component's fields changed and the live data no longer matches the new schema, so the+ * realm must full-reload. Builtins are excluded (their C++-backed shape never changes).+ * Default *values* are intentionally not hashed — only the shape gates a rebuild.+ */+export function getUserComponentFingerprint(): string {+ const comps = userComponents();+ return [...comps.keys()].sort()+ .map((name) => `${name}:${fieldShape(comps.get(name)!._default)}`)+ .join('|');+}++function fieldShape(value: unknown): string {+ if (value === null || typeof value !== 'object') return typeof value;+ if (Array.isArray(value)) return `[${value.length ? fieldShape(value[0]) : ''}]`;+ const rec = value as Record<string, unknown>;+ return `{${Object.keys(rec).sort().map((k) => `${k}:${fieldShape(rec[k])}`).join(',')}}`;+}+export function getComponent(name: string): AnyComponentDef | undefined {return builtinRegistry.get(name) ?? userComponents().get(name);}diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 2c0a51f6f..73b7fc50c 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -72,6 +72,7 @@ export {getComponentRegistry,getAllRegisteredComponents,getUserComponents,+ getUserComponentFingerprint,enumOptions,type ComponentDef,type BuiltinComponentDef,@@ -355,3 +356,6 @@ export {} from './env';export type { RunCondition } from './app';++export { probeRegistrations } from './hotReload';+export type { ProbedRegistrations } from './hotReload';diff --git a/sdk/src/hotReload.ts b/sdk/src/hotReload.tsnew file mode 100644index 000000000..940e9cf3d--- /dev/null+++ b/sdk/src/hotReload.ts@@ -0,0 +1,38 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file hotReload.ts+ * @brief State-preserving hot-reload support (RC10 P3): collect a project bundle's+ * re-registrations in isolation so the editor can decide hot-swap vs reload.+ */+import { AppContext, getDefaultContext, setDefaultContext, type PendingSystemEntry } from './context';+import { getUserComponentFingerprint } from './component';++export interface ProbedRegistrations {+ /** Digest of the user component schemas the bundle declared (shape, not values). */+ fingerprint: string;+ /** The systems the bundle queued, to feed to {@link App.hotSwapSystems}. */+ pending: PendingSystemEntry[];+}++/**+ * Run `register` (a project-bundle re-import) inside a throwaway {@link AppContext}, so+ * its `defineComponent` / `addSystem` populate an isolated registry instead of the live+ * one — and return what it registered. The live context is always restored, even on+ * throw. The caller compares `fingerprint` to the live one (`getUserComponentFingerprint`+ * before calling) to choose hot-swap (unchanged → keep the World) vs full-reload, and+ * feeds `pending` to `App.hotSwapSystems`. Component identity is interned by name (see+ * component.ts), so the probe's component defs share the live `_id`s — the re-imported+ * systems' queries resolve to the live storage. See docs/REARCH_HOT_RELOAD.md.+ */+export async function probeRegistrations(register: () => Promise<void>): Promise<ProbedRegistrations> {+ const live = getDefaultContext();+ const probe = new AppContext();+ setDefaultContext(probe);+ try {+ await register();+ return { fingerprint: getUserComponentFingerprint(), pending: probe.drainPendingSystems() };+ } finally {+ setDefaultContext(live);+ }+}diff --git a/sdk/tests/hot-swap-systems.test.ts b/sdk/tests/hot-swap-systems.test.tsnew file mode 100644index 000000000..9aefd6b21--- /dev/null+++ b/sdk/tests/hot-swap-systems.test.ts@@ -0,0 +1,117 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { describe, it, expect, beforeEach } from 'vitest';+import { App } from '../src/app';+import { defineSystem, Schedule } from '../src/system';+import { defineComponent, clearUserComponents, getUserComponentFingerprint, getUserComponents } from '../src/component';+import { setDefaultContext, AppContext } from '../src/context';+import { addSystemToSchedule } from '../src/system';+import { probeRegistrations } from '../src/hotReload';++// RC10 P3: the state-preserving hot-reload core — App.hotSwapSystems replaces user+// system bodies in place (keeping the live World), and the component fingerprint gates+// hot-swap (logic-only) vs full-reload (a component's fields changed).+describe('App.hotSwapSystems', () => {+ let app: App;+ let log: string[];+ beforeEach(() => { app = App.new(); log = []; });++ async function runUpdate(): Promise<void> {+ (app as unknown as { runner_: unknown }).runner_ = { run: (sys: { _fn: () => void }) => sys._fn() };+ await (app as unknown as { runSchedule: (s: Schedule) => Promise<void> }).runSchedule(Schedule.Update);+ }++ it('swaps a named system body in place, keeping it scheduled', async () => {+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => log.push('old'), { name: 'S' }));+ await runUpdate();+ expect(log).toEqual(['old']);++ const ok = app.hotSwapSystems([+ { schedule: Schedule.Update, system: defineSystem([], () => log.push('new'), { name: 'S' }) },+ ]);+ expect(ok).toBe(true);++ log.length = 0;+ await runUpdate();+ expect(log).toEqual(['new']);+ });++ it('rejects an added system (count change) → caller full-reloads', () => {+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'S' }));+ expect(app.hotSwapSystems([+ { schedule: Schedule.Update, system: defineSystem([], () => {}, { name: 'S' }) },+ { schedule: Schedule.Update, system: defineSystem([], () => {}, { name: 'T' }) },+ ])).toBe(false);+ });++ it('rejects a rename → full-reload', () => {+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'S' }));+ expect(app.hotSwapSystems([+ { schedule: Schedule.Update, system: defineSystem([], () => {}, { name: 'Renamed' }) },+ ])).toBe(false);+ });++ it('matches unnamed systems positionally (System_N ⇔ unnamed)', async () => {+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => log.push('a-old')));+ app.addSystemToSchedule(Schedule.Update, defineSystem([], () => log.push('b-old')));+ expect(app.hotSwapSystems([+ { schedule: Schedule.Update, system: defineSystem([], () => log.push('a-new')) },+ { schedule: Schedule.Update, system: defineSystem([], () => log.push('b-new')) },+ ])).toBe(true);++ await runUpdate();+ expect(log.sort()).toEqual(['a-new', 'b-new']);+ });+});++describe('getUserComponentFingerprint', () => {+ beforeEach(() => setDefaultContext(new AppContext()));++ it('is stable when only default values change (logic-only edit)', () => {+ defineComponent('Patrol', { speed: 60, range: 120 });+ const before = getUserComponentFingerprint();+ clearUserComponents();+ defineComponent('Patrol', { speed: 80, range: 200 }); // values differ, shape same+ expect(getUserComponentFingerprint()).toBe(before);+ });++ it('changes when a field is added (schema change → must full-reload)', () => {+ defineComponent('Patrol', { speed: 60 });+ const before = getUserComponentFingerprint();+ clearUserComponents();+ defineComponent('Patrol', { speed: 60, accel: 5 });+ expect(getUserComponentFingerprint()).not.toBe(before);+ });++ it('is order-independent across components', () => {+ defineComponent('A', { x: 0 });+ defineComponent('B', { y: '' });+ const f1 = getUserComponentFingerprint();+ clearUserComponents();+ defineComponent('B', { y: '' });+ defineComponent('A', { x: 0 });+ expect(getUserComponentFingerprint()).toBe(f1);+ });+});++describe('probeRegistrations', () => {+ beforeEach(() => setDefaultContext(new AppContext()));++ it('collects a re-import\'s registrations in isolation and restores the live context', async () => {+ defineComponent('Live', { a: 0 });+ const liveBefore = [...getUserComponents().keys()];++ const { fingerprint, pending } = await probeRegistrations(async () => {+ defineComponent('Probe', { b: 0 });+ addSystemToSchedule(Schedule.Update, defineSystem([], () => {}, { name: 'PS' }));+ });++ expect(fingerprint).toContain('Probe');+ expect(pending).toHaveLength(1);+ expect((pending[0].system as { _name: string })._name).toBe('PS');++ // The probe registrations must NOT have leaked into the live context.+ expect([...getUserComponents().keys()]).toEqual(liveBefore);+ expect(getUserComponents().has('Probe')).toBe(false);+ });+});