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
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsindex 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' },