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.

fix(assets): a hot update rebinds every field that declares an asset

esengine6d0885357e90
diff --git a/sdk/src/asset/liveAssetBindings.ts b/sdk/src/asset/liveAssetBindings.ts
new file mode 100644
index 000000000..90401ced8
--- /dev/null
+++ b/sdk/src/asset/liveAssetBindings.ts
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file liveAssetBindings.ts
+ * @brief Which live components are bound to one asset value, right now.
+ *
+ * @details Derived when it is asked for, never maintained. `sprite.texture = h`
+ * is an ordinary field write, so a registry kept alongside the World
+ * would be a second source of truth that game code silently
+ * invalidates. Asset replacement is rare enough to pay for the walk.
+ *
+ * The walk is over `component.assetFields` — the same declaration that
+ * drives discovery, cook inclusion and `@uuid` resolution. A
+ * hand-written list of components would answer for the ones its author
+ * remembered: the built-in rebinder knew two of the seven fields that
+ * carry a texture, and no plugin or project component at all.
+ */
+import type { World } from '../ecs/world';
+import type { Entity } from '../types';
+import { getComponentRegistry, type AnyComponentDef } from '../ecs/component';
+import type { AssetFieldType } from '../scene/scene';
+
+/** One field of one live component, bound to the asset being replaced. */
+export interface LiveAssetBinding {
+ readonly entity: Entity;
+ readonly component: AnyComponentDef;
+ readonly field: string;
+}
+
+/** Component names carrying at least one field of this asset type — what a
+ * system walking those bindings reaches for, from the same declaration. */
+export function componentsBindingAssetType(type: AssetFieldType): string[] {
+ const names: string[] = [];
+ for (const [name, component] of getComponentRegistry()) {
+ if (component.assetFields.some((f) => f.type === type)) names.push(name);
+ }
+ return names;
+}
+
+/**
+ * Every live binding of `value` — the asset a replacement is about to migrate.
+ *
+ * An empty value (0 / '') is refused rather than matched: it is what an UNBOUND
+ * field holds, so matching it would hand back every field of every entity that
+ * never referenced the asset at all.
+ */
+export function findLiveAssetBindings(
+ world: World, type: AssetFieldType, value: unknown,
+): LiveAssetBinding[] {
+ const found: LiveAssetBinding[] = [];
+ if (value === 0 || value === '' || value === null || value === undefined) return found;
+
+ for (const component of getComponentRegistry().values()) {
+ const fields = component.assetFields.filter((f) => f.type === type);
+ if (fields.length === 0) continue;
+ for (const entity of world.getEntitiesWithComponents([component])) {
+ const data = world.get(entity, component) as Record<string, unknown>;
+ for (const { field } of fields) {
+ if (data[field] === value) found.push({ entity, component, field });
+ }
+ }
+ }
+ return found;
+}
+
+/** Read one binding's current value — what a rollback has to put back. */
+export function readLiveAssetBinding(world: World, binding: LiveAssetBinding): unknown {
+ return (world.get(binding.entity, binding.component) as Record<string, unknown>)[binding.field];
+}
+
+/**
+ * Point one binding at another asset.
+ *
+ * Through `world.set` rather than a mutation: an engine-backed component answers
+ * a fresh object per `get`, so writing to that object stores nothing.
+ */
+export function writeLiveAssetBinding(
+ world: World, binding: LiveAssetBinding, value: unknown,
+): void {
+ const data = world.get(binding.entity, binding.component) as Record<string, unknown>;
+ data[binding.field] = value;
+ world.set(binding.entity, binding.component, data as never);
+}
diff --git a/sdk/src/hotUpdateRebind.ts b/sdk/src/hotUpdateRebind.ts
index f413bf8c5..e9c713338 100644
--- a/sdk/src/hotUpdateRebind.ts
+++ b/sdk/src/hotUpdateRebind.ts
@@ -4,19 +4,23 @@
* @file hotUpdateRebind.ts
* @brief Built-in hot-update rebinder — makes a hot update transparent to game
* code. When applyUpdate / invalidate drops an asset it reports the
- * texture handle that was bound; this reloads the ref (now resolved to
- * the fresh content) and swaps old→new in every live texture-bearing
- * component, so a scene that references an asset by @uuid updates on
- * screen with ZERO game code.
+ * value that was bound; this reloads the ref (now resolved to the fresh
+ * content) and swaps old→new in every live component that declares a
+ * field of that asset type, so a scene that references an asset by
+ * @uuid updates on screen with ZERO game code.
+ *
+ * Which fields those are comes from `component.assetFields` — see
+ * liveAssetBindings.ts for why it cannot be a list kept here.
*
* Registered once per App (initRuntime). State lives in this closure —
* per install, not module-global — so realms don't share queues.
*/
import type { App } from './app/app';
-import { Schedule, defineSystem } from './ecs/system';
-import { Query, Mut } from './ecs/query';
-import { Sprite, MeshRenderer } from './ecs/component';
+import { Schedule, defineSystem, GetWorld } from './ecs/system';
import type { Assets } from './asset/Assets';
+import {
+ componentsBindingAssetType, findLiveAssetBindings, writeLiveAssetBinding,
+} from './asset/liveAssetBindings';
export function installHotUpdateRebind(app: App, assets: Assets): void {
// Refs whose asset was invalidated (with the handle bound before the drop),
@@ -29,8 +33,8 @@ export function installHotUpdateRebind(app: App, assets: Assets): void {
});
app.addSystemToSchedule(Schedule.Update, defineSystem(
- [Query(Mut(Sprite)), Query(Mut(MeshRenderer))],
- (sprites, meshes) => {
+ [GetWorld()],
+ (world) => {
// Kick a reload for each newly-invalidated ref; the async result (the
// new handle) lands in `swaps` a frame or two later.
while (pending.length > 0) {
@@ -39,18 +43,19 @@ export function installHotUpdateRebind(app: App, assets: Assets): void {
if (tex.handle !== oldHandle) swaps.push({ oldHandle, newHandle: tex.handle });
});
}
- if (swaps.length === 0) return;
- // Swap old→new in every live sprite / mesh (each query iterated once).
- for (const [, sprite] of sprites) {
- const s = swaps.find((x) => x.oldHandle === sprite.texture);
- if (s) sprite.texture = s.newHandle;
- }
- for (const [, mesh] of meshes) {
- const s = swaps.find((x) => x.oldHandle === mesh.texture);
- if (s) mesh.texture = s.newHandle;
+ while (swaps.length > 0) {
+ const { oldHandle, newHandle } = swaps.shift()!;
+ for (const binding of findLiveAssetBindings(world, 'texture', oldHandle)) {
+ writeLiveAssetBinding(world, binding, newHandle);
+ }
}
- swaps.length = 0;
},
- { name: 'HotUpdateRebindSystem' },
+ {
+ name: 'HotUpdateRebindSystem',
+ // The reach is every component declaring a texture field, read from
+ // the registry at access time — a project component registered after
+ // this system was installed binds textures too.
+ touches: () => ({ writes: componentsBindingAssetType('texture') }),
+ },
));
}
diff --git a/sdk/tests/hot-update-rebind.test.ts b/sdk/tests/hot-update-rebind.test.ts
new file mode 100644
index 000000000..ee937d916
--- /dev/null
+++ b/sdk/tests/hot-update-rebind.test.ts
@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file hot-update-rebind.test.ts
+ * @brief A hot update reaches every field that declares an asset, not the two
+ * the rebinder's author remembered.
+ *
+ * @details Seven built-in fields carry a texture; the rebinder knew `Sprite.texture`
+ * and `MeshRenderer.texture`. The other five — and every project or plugin
+ * component — kept rendering the pre-update image with nothing reporting a
+ * failure. The cases here are DERIVED from `component.assetFields`, so a
+ * field added tomorrow is covered tomorrow rather than when someone
+ * remembers to extend a list.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { App } from '../src/app/app';
+import { World } from '../src/ecs/world';
+import { defineComponent, getComponentRegistry, type AnyComponentDef } from '../src/ecs/component';
+import { COMPONENT_META } from '../src/ecs/component.generated';
+import { Assets } from '../src/asset/Assets';
+import type { Backend } from '../src/asset/Backend';
+import type { CppRegistry } from '../src/wasm';
+import type { Entity } from '../src/types';
+import { registerComponent } from '../src/ecs/component';
+import { UIVisual } from '../src/ui/core/ui-visual';
+import { installHotUpdateRebind } from '../src/hotUpdateRebind';
+import { findLiveAssetBindings } from '../src/asset/liveAssetBindings';
+
+// ---------------------------------------------------------------------------
+// The C++ side, modelled: a component store that add/get/has/remove really move.
+// ---------------------------------------------------------------------------
+
+function connectFakeCpp(world: World): void {
+ let nextEntity = 1;
+ const registry: Record<string, unknown> = {
+ create: () => nextEntity++,
+ destroy: () => {},
+ hasParent: () => false,
+ setParent: () => {},
+ };
+ for (const name of Object.keys(COMPONENT_META)) {
+ const rows = new Map<number, Record<string, unknown>>();
+ registry[`add${name}`] = (e: number, data: Record<string, unknown>) => { rows.set(e, { ...data }); };
+ registry[`get${name}`] = (e: number) => rows.get(e);
+ registry[`has${name}`] = (e: number) => rows.has(e);
+ registry[`remove${name}`] = (e: number) => { rows.delete(e); };
+ }
+ world.connectCpp(registry as unknown as CppRegistry);
+}
+
+/** The pool, modelled: every decode mints a handle, invalidate severs revival. */
+function createPoolFake() {
+ const byPath = new Map<string, number>();
+ let next = 1;
+ return {
+ budget: 0,
+ createTexture: vi.fn((): number => next++),
+ registerTextureWithPath: vi.fn((handle: number, path: string) => { byPath.set(path, handle); }),
+ acquireTextureByPath: vi.fn((path: string): number => byPath.get(path) ?? 0),
+ invalidateTexturePath: vi.fn((path: string): boolean => byPath.delete(path)),
+ releaseTexture: vi.fn(),
+ getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),
+ getTextureGLId: vi.fn(() => 1),
+ setTextureMetadata: vi.fn(),
+ };
+}
+
+let pool = createPoolFake();
+vi.mock('../src/wasm/resourceManager', () => ({
+ requireResourceManager: () => pool,
+ getResourceManager: () => pool,
+ evictTextureDimensions: vi.fn(),
+}));
+
+const platformFactory = vi.hoisted(() => () => ({
+ platformCreateCanvas: () => ({
+ width: 64, height: 64,
+ getContext: () => ({
+ clearRect: vi.fn(), drawImage: vi.fn(),
+ getImageData: () => ({ data: { buffer: new ArrayBuffer(64 * 64 * 4) } }),
+ }),
+ }),
+ platformCreateImage: () => {
+ const img: { width?: number; height?: number; onload?: () => void } = {};
+ setTimeout(() => { img.width = 64; img.height = 64; img.onload?.(); }, 0);
+ return img;
+ },
+ platformFetch: vi.fn(),
+ platformReadFile: vi.fn(),
+ platformReadTextFile: vi.fn(),
+ platformFileExists: vi.fn(),
+ platformLoadSubpackage: vi.fn(async () => {}),
+ platformGetStorageItem: () => null,
+ platformSetStorageItem: vi.fn(),
+ platformWriteCacheFile: vi.fn(async () => {}),
+}));
+vi.mock('../src/platform', platformFactory);
+vi.mock('../src/platform/base', platformFactory);
+
+function buildAssets(): Assets {
+ return Assets.create({
+ backend: {
+ fetchBinary: vi.fn(async () => new ArrayBuffer(8)),
+ fetchText: vi.fn(async () => '{}'),
+ resolveUrl: (p: string) => `http://test/${p}`,
+ } as unknown as Backend,
+ module: { _malloc: vi.fn(() => 0), _free: vi.fn(), HEAPU8: new Uint8Array(1 << 16), GL: null, FS: null } as never,
+ });
+}
+
+/** UIVisual is registered by the UI plugin, whose build() this test does not run.
+ * Registering it by hand is what that plugin does, and the completeness check
+ * below refuses to pass while any C++-declared texture field is missing. */
+registerComponent('UIVisual', UIVisual);
+
+/** Every (component, field) in the live registry that binds a texture. */
+function declaredTextureFields(): Array<{ component: AnyComponentDef; field: string }> {
+ const out: Array<{ component: AnyComponentDef; field: string }> = [];
+ for (const component of getComponentRegistry().values()) {
+ for (const f of component.assetFields) {
+ if (f.type === 'texture') out.push({ component, field: f.field });
+ }
+ }
+ return out;
+}
+
+/** Run frames until the reload's promise has landed and its swap been applied. */
+async function settle(app: App, frames = 4): Promise<void> {
+ for (let i = 0; i < frames; i++) {
+ await app.tick(1 / 60);
+ await Promise.resolve();
+ await new Promise((r) => setTimeout(r, 0));
+ }
+}
+
+describe('the hot-update rebinder reaches every declared texture field', () => {
+ beforeEach(() => { pool = createPoolFake(); });
+
+ it('rebinds all of them, including a component the project declared', async () => {
+ // A project component is the case a hand-written list can never cover.
+ const CustomVisual = defineComponent(
+ 'HotUpdateRebindTestVisual',
+ { icon: 0, tint: 1 },
+ { assetFields: [{ field: 'icon', type: 'texture' }] },
+ );
+
+ const app = App.new();
+ connectFakeCpp(app.world);
+ const assets = buildAssets();
+ installHotUpdateRebind(app, assets);
+
+ const before = await assets.loadTexture('hero.png');
+ const fields = declaredTextureFields();
+ // Completeness, against the engine's own declaration rather than a list
+ // kept here: a texture field added to a C++ component and not covered
+ // below fails this, instead of quietly going unrebound.
+ const covered = new Set(fields.map((f) => `${f.component._name}.${f.field}`));
+ const engineDeclared = Object.entries(COMPONENT_META).flatMap(([name, meta]) =>
+ (meta.assetFields ?? [])
+ .filter((f) => f.type === 'texture')
+ .map((f) => `${name}.${f.field}`));
+ expect(engineDeclared.length).toBeGreaterThanOrEqual(7); // never vacuous
+ expect([...covered]).toEqual(expect.arrayContaining(engineDeclared));
+ expect(covered.has('HotUpdateRebindTestVisual.icon')).toBe(true);
+
+ const bound: Array<{ entity: Entity; component: AnyComponentDef; field: string }> = [];
+ for (const { component, field } of fields) {
+ const entity = app.world.spawn();
+ app.world.insert(entity, component, { [field]: before.handle } as never);
+ bound.push({ entity, component, field });
+ }
+ // And one field of each kind left unbound, which a swap must not touch.
+ const untouched = app.world.spawn();
+ app.world.insert(untouched, CustomVisual, {});
+
+ assets.invalidate('hero.png');
+ await settle(app);
+
+ const after = assets.getTexture('hero.png');
+ expect(after).toBeDefined();
+ expect(after!.handle).not.toBe(before.handle);
+
+ for (const { entity, component, field } of bound) {
+ const data = app.world.get(entity, component) as Record<string, unknown>;
+ expect(`${component._name}.${field} = ${String(data[field])}`)
+ .toBe(`${component._name}.${field} = ${after!.handle}`);
+ }
+ expect((app.world.get(untouched, CustomVisual) as { icon: number }).icon).toBe(0);
+ });
+
+ it('an unbound field is not a binding of the asset being replaced', () => {
+ // 0 is what an unbound field holds; matching it would rebind the whole world.
+ const world = new World();
+ connectFakeCpp(world);
+ const Widget = defineComponent(
+ 'HotUpdateRebindTestWidget', { icon: 0 },
+ { assetFields: [{ field: 'icon', type: 'texture' }] },
+ );
+ const e = world.spawn();
+ world.insert(e, Widget, {});
+
+ expect(findLiveAssetBindings(world, 'texture', 0)).toEqual([]);
+ expect(findLiveAssetBindings(world, 'texture', 7)).toEqual([]);
+ world.insert(e, Widget, { icon: 7 });
+ expect(findLiveAssetBindings(world, 'texture', 7)).toHaveLength(1);
+ });
+});
diff --git a/tools/check-live-asset-rebind.mjs b/tools/check-live-asset-rebind.mjs
new file mode 100644
index 000000000..7cbb66f26
--- /dev/null
+++ b/tools/check-live-asset-rebind.mjs
@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-live-asset-rebind.mjs — hot update reads the declaration, not a list.
+ *
+ * `component.assetFields` is what says a field carries an asset: discovery,
+ * cook inclusion and `@uuid` resolution all read it. The rebinder did not — it
+ * named Sprite and MeshRenderer — so five of the seven built-in texture fields
+ * were never swapped on a hot update, and no project or plugin component was
+ * either. Nothing failed; the game just kept drawing the old image.
+ *
+ * A list like that cannot be kept correct, because the thing it must agree with
+ * is authored somewhere else (a C++ ES_PROPERTY, a project's defineComponent).
+ * So the rule guarded here is that there is no list:
+ *
+ * 1. No file on the rebind path names an asset-bearing component type.
+ * 2. The walk goes through the registry and reads `assetFields`.
+ *
+ * Run: node tools/check-live-asset-rebind.mjs (exit 1 on violation)
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** The files that answer "which live fields hold this asset?". */
+const REBIND_PATH = [
+ 'sdk/src/asset/liveAssetBindings.ts',
+ 'sdk/src/hotUpdateRebind.ts',
+];
+
+const GENERATED = 'sdk/src/ecs/component.generated.ts';
+
+const missing = [...REBIND_PATH, GENERATED].filter((f) => !existsSync(path.join(ROOT, f)));
+if (missing.length) {
+ console.error(`check-live-asset-rebind is stale: ${missing.join(', ')} does not exist.`);
+ process.exit(1);
+}
+
+/** Comments out, line numbers intact — a finding names a line someone reads. */
+const stripComments = (text) =>
+ text
+ .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+ .replace(/\/\/[^\n]*/g, '');
+
+/**
+ * Components that declare an asset field, from the two places they are authored:
+ * the generated C++ metadata, and `defineComponent` in the SDK. These are the
+ * names a rebinder is tempted to write down.
+ */
+function assetBearingComponents() {
+ const names = new Set();
+ const generated = readFileSync(path.join(ROOT, GENERATED), 'utf8');
+ const entry = /^ {4}([A-Za-z0-9_]+): \{$/gm;
+ let m;
+ const marks = [];
+ while ((m = entry.exec(generated))) marks.push({ name: m[1], at: m.index });
+ for (let i = 0; i < marks.length; i++) {
+ const body = generated.slice(marks[i].at, marks[i + 1]?.at ?? generated.length);
+ if (/assetFields: \[\s*\{/.test(body)) names.add(marks[i].name);
+ }
+ // SDK-side components declare theirs at the defineComponent call.
+ const src = readFileSync(path.join(ROOT, 'sdk/src/ecs/component.ts'), 'utf8');
+ const call = /defineComponent<[^>]*>\(\s*'([A-Za-z0-9_]+)'([\s\S]{0,2000}?)\n\}\);/g;
+ while ((m = call.exec(src))) {
+ if (m[2].includes('assetFields')) names.add(m[1]);
+ }
+ return names;
+}
+
+const components = assetBearingComponents();
+// An empty set would pass every check below without reading a thing.
+if (components.size < 6) {
+ console.error(`check-live-asset-rebind: found only ${components.size} asset-bearing component(s) — the parser no longer matches how they are declared.`);
+ process.exit(1);
+}
+
+const findings = [];
+for (const file of REBIND_PATH) {
+ const text = readFileSync(path.join(ROOT, file), 'utf8');
+ const code = stripComments(text);
+ for (const name of components) {
+ const hit = new RegExp(`\\b${name}\\b`).exec(code);
+ if (!hit) continue;
+ const line = code.slice(0, hit.index).split('\n').length;
+ findings.push(`${file}:${line} names the component type "${name}".`);
+ }
+}
+
+/** One exported function's body, braces balanced. */
+function functionBody(text, name) {
+ const m = new RegExp(`export function ${name}\\b`).exec(text);
+ if (!m) return null;
+ let i = text.indexOf('{', m.index);
+ if (i < 0) return null;
+ const start = i;
+ for (let depth = 0; i < text.length; i++) {
+ if (text[i] === '{') depth++;
+ else if (text[i] === '}' && --depth === 0) break;
+ }
+ return text.slice(start + 1, i);
+}
+
+// Per function, not per file: the file kept the word `assetFields` in a
+// neighbouring helper while the walk itself had been replaced by a literal.
+const discovery = stripComments(readFileSync(path.join(ROOT, REBIND_PATH[0]), 'utf8'));
+for (const fn of ['findLiveAssetBindings', 'componentsBindingAssetType']) {
+ const body = functionBody(discovery, fn);
+ if (body === null) {
+ findings.push(`${REBIND_PATH[0]} ${fn}() is gone — the rebind path's only door to the declaration.`);
+ continue;
+ }
+ if (!/getComponentRegistry\(/.test(body) || !/\.assetFields\b/.test(body)) {
+ findings.push(`${REBIND_PATH[0]} ${fn}() no longer walks getComponentRegistry() reading assetFields — the declaration is the only thing that knows which fields carry an asset.`);
+ }
+}
+
+if (findings.length === 0) {
+ console.log(`check-live-asset-rebind: the rebind path names none of the ${components.size} asset-bearing components, and reads the declaration.`);
+ process.exit(0);
+}
+for (const f of findings) console.error(f);
+console.error('\nRebinding is per DECLARED asset field. Widen the walk instead of adding a case.');
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 4c3646a4b..4116da8f2 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -108,6 +108,9 @@ export const GATES = [
{ id: 'capabilities', run: 'node tools/check-capabilities.mjs', needs: 'editor' },
{ id: 'inspector-door', run: 'node tools/check-inspector-door.mjs', needs: 'editor' },
{ id: 'component-fields', run: 'node tools/check-component-fields.mjs' },
+ // A field declares that it carries an asset in one place; everything that acts
+ // on live assets has to read THAT rather than keep a list of components beside it.
+ { id: 'live-asset-rebind', run: 'node tools/check-live-asset-rebind.mjs' },
// …and that each of them can be reached on a device, where the registry is
// assembled from ptr accessors rather than from embind.
{ id: 'native-components', run: 'node tools/check-native-components.mjs' },