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(hot-reload): state-preserving fast path — hot-swap system bodies (RC10 P3)

esenginee1208ef42ca1
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 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.ts
index 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-system
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});