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): FSM/BT discovery honors the code-name filter; store-key catalog parity
yhhfc5bc4555cbb
diff --git a/sdk/src/ai/bt/BehaviorTreeAgent.ts b/sdk/src/ai/bt/BehaviorTreeAgent.tsindex c788df093..99cc0bf6f 100644--- a/sdk/src/ai/bt/BehaviorTreeAgent.ts+++ b/sdk/src/ai/bt/BehaviorTreeAgent.ts@@ -10,6 +10,7 @@*/import { defineComponent } from '../../component';+import { isUuidRef } from '../../asset/AssetRegistry';import type { BtDefinition } from './types';export interface BehaviorTreeAgentData {@@ -24,10 +25,12 @@ export const BehaviorTreeAgent = defineComponent<BehaviorTreeAgentData>('Behaviostatus: '',}, {assetFields: [{ field: 'bt', type: 'behaviortree' }],- // Preload a `.esbt` reference with the scene; a plain registerBt name is left alone.+ // Preload a `.esbt` path or an editor-serialized uuid ref with the scene; a+ // plain `registerBt` name (code path) is left alone — this callback is the+ // discovery authority; the assetField above only drives the editor picker.discoverAssets: data => {const bt = data.bt;- return typeof bt === 'string' && bt.endsWith('.esbt')+ return typeof bt === 'string' && (bt.endsWith('.esbt') || isUuidRef(bt))? [{ type: 'behaviortree', path: bt }]: [];},diff --git a/sdk/src/ai/fsm/StateMachineAgent.ts b/sdk/src/ai/fsm/StateMachineAgent.tsindex 94840e0f8..5f03b43ca 100644--- a/sdk/src/ai/fsm/StateMachineAgent.ts+++ b/sdk/src/ai/fsm/StateMachineAgent.ts@@ -10,6 +10,7 @@*/import { defineComponent } from '../../component';+import { isUuidRef } from '../../asset/AssetRegistry';import type { FsmDefinition } from './types';import { compileFsm, type CompiledFsm } from './FsmRunner';@@ -25,11 +26,13 @@ export const StateMachineAgent = defineComponent<StateMachineAgentData>('StateMacurrent: '',}, {assetFields: [{ field: 'fsm', type: 'statemachine' }],- // Preload a `.esfsm` reference with the scene so the FSM is registered before- // the agent first ticks. A plain `registerFsm` name (code path) is left alone.+ // Preload a `.esfsm` path or an editor-serialized uuid ref with the scene so+ // the FSM is registered before the agent first ticks. A plain `registerFsm`+ // name (code path) is left alone — this callback is the discovery authority;+ // the assetField above only drives the editor picker.discoverAssets: data => {const fsm = data.fsm;- return typeof fsm === 'string' && fsm.endsWith('.esfsm')+ return typeof fsm === 'string' && (fsm.endsWith('.esfsm') || isUuidRef(fsm))? [{ type: 'statemachine', path: fsm }]: [];},diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 8bb6b122b..bb8dd6fa0 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1041,6 +1041,17 @@ export class Assets {return ref;}+ /**+ * The load path a ref resolves to — resolver plus addressable Catalog,+ * the same two steps every typed load performs. This is the key a loader+ * registers a data asset under, so runtime stores keyed by registration+ * path (FSM/BT/timeline/tilemap via `resolveAssetKey`) must look up with+ * THIS: `resolveRef` alone diverges once the Catalog carries mappings.+ */+ resolveLoadPath(ref: string): string {+ return this.resolveLoadPath_(ref);+ }+/*** Canonical path-resolution for all typed load methods.* Runs the AssetRefResolver first so `@uuid:...` refs map to their realdiff --git a/sdk/src/asset/discoverAssets.ts b/sdk/src/asset/discoverAssets.tsindex f3ebd0730..d16a8f2ab 100644--- a/sdk/src/asset/discoverAssets.ts+++ b/sdk/src/asset/discoverAssets.ts@@ -7,7 +7,11 @@* Each component may reference assets in three ways: a custom* `discoverAssets` callback, declared `assetFields`, or paired* `spineFields`. This module walks a SceneData and buckets every- * such ref by asset type.+ * such ref by asset type. A `discoverAssets` callback is authoritative:+ * when present, `assetFields` are not walked for discovery (they still+ * drive the editor's asset pickers and ref rewrites) — the callback may+ * deliberately exclude values, e.g. FSM/BT agents skip plain+ * code-registered names that only look like asset refs.** Refs in serialized data may be either a concrete path* (`"assets/player.png"`, legacy) or a UUID reference@@ -99,12 +103,12 @@ export function discoverSceneAssets(addAsset(ref.type, ref.path);}}- }-- for (const desc of comp.assetFields) {- const value = data[desc.field];- if (typeof value === 'string' && value) {- addAsset(desc.type, value);+ } else {+ for (const desc of comp.assetFields) {+ const value = data[desc.field];+ if (typeof value === 'string' && value) {+ addAsset(desc.type, value);+ }}}diff --git a/sdk/src/asset/resolveAssetKey.ts b/sdk/src/asset/resolveAssetKey.tsindex 6cc2f1e6c..7ff2d4c5a 100644--- a/sdk/src/asset/resolveAssetKey.ts+++ b/sdk/src/asset/resolveAssetKey.ts@@ -6,18 +6,20 @@* component ref to the key it is registered under.** A data asset (`.esfsm`, `.esbt`, `.estimeline`, `.estilemap`…) loads under its- * RESOLVED path — the realm's ref resolver maps a plain path or `@uuid:` ref to- * that key (in the play realm it gains the `estella://project/` origin). But the- * component still holds the authored ref, and `resolveSceneAssetPaths` leaves- * these path-keyed fields untouched (only texture/material/font become handles).- * So the runtime plugin must resolve the ref the same way before the lookup, and- * fall back to the raw value for keys registered verbatim (a `registerFsm`/- * `registerBt` code name). See the FSM/BT/tilemap/timeline plugins.+ * RESOLVED load path — the realm's ref resolver maps a plain path or `@uuid:` ref+ * (in the play realm it gains the `estella://project/` origin), then the+ * addressable Catalog applies. But the component still holds the authored ref,+ * and `resolveSceneAssetPaths` leaves these path-keyed fields untouched (only+ * texture/material/font become handles). So the runtime plugin must resolve the+ * ref through the SAME two steps before the lookup — resolver alone diverges+ * from the registration key once the Catalog carries mappings — and fall back+ * to the raw value for keys registered verbatim (a `registerFsm`/`registerBt`+ * code name). See the FSM/BT/tilemap/timeline plugins.*/import type { AssetsData } from './AssetPlugin';/** Resolve an authored asset ref to its runtime-store key (or the ref itself). */export function resolveAssetKey(assets: AssetsData | null | undefined, ref: string): string {- return assets?.resolveRef(ref) ?? ref;+ return assets ? assets.resolveLoadPath(ref) : ref;}diff --git a/sdk/src/component.ts b/sdk/src/component.tsindex 0f2b12a5c..6d45c56b6 100644--- a/sdk/src/component.ts+++ b/sdk/src/component.ts@@ -94,6 +94,12 @@ export interface ComponentMetadata {fields?: Record<string, FieldMeta>;/** Keyframeable fields (Sequencer tracks); auto-derived from numeric fields if omitted. */animatableFields?: string[];+ /**+ * Custom asset discovery for scene preload. Authoritative when present:+ * `assetFields` are NOT walked for discovery (they still drive editor+ * pickers/ref rewrites), so the callback can exclude values that are not+ * asset refs (e.g. code-registered FSM/BT names).+ */discoverAssets?: (data: Record<string, unknown>) => AssetRef[];/*** Runtime-only state that must never persist: a transient component isdiff --git a/sdk/tests/discoverAssets.test.ts b/sdk/tests/discoverAssets.test.tsindex ecab97109..924f5c4bf 100644--- a/sdk/tests/discoverAssets.test.ts+++ b/sdk/tests/discoverAssets.test.ts@@ -4,6 +4,8 @@ import { describe, it, expect, beforeEach } from 'vitest';import { defineComponent, clearUserComponents } from '../src/component';import { discoverSceneAssets, getAssetPathsByType } from '../src/asset/discoverAssets';import { AssetRegistry, makeUuidRef } from '../src/asset/AssetRegistry';+import { StateMachineAgent } from '../src/ai/fsm/StateMachineAgent';+import { BehaviorTreeAgent } from '../src/ai/bt/BehaviorTreeAgent';import type { SceneData } from '../src/scene';const SPRITE_NAME = 'DiscoverTest_Sprite';@@ -199,6 +201,68 @@ describe('discoverSceneAssets', () => {});});+describe('discoverAssets callback authority over assetFields', () => {+ const AGENT_NAME = 'DiscoverTest_Agent';++ beforeEach(() => {+ // Mirrors the FSM/BT agent shape: the assetField drives the editor+ // picker, the callback filters out plain code-registered names.+ defineComponent(AGENT_NAME, { fsm: '' }, {+ assetFields: [{ field: 'fsm', type: 'statemachine' }],+ discoverAssets: data => {+ const fsm = data.fsm;+ return typeof fsm === 'string' && fsm.endsWith('.esfsm')+ ? [{ type: 'statemachine', path: fsm }]+ : [];+ },+ });+ });++ it('does NOT bucket values the callback filtered out (code-registered names)', () => {+ const scene = makeScene([{+ id: 1, name: 'e1', parent: null, children: [],+ components: [{ type: AGENT_NAME, data: { fsm: 'patrol' } }],+ }]);++ const refs = discoverSceneAssets(scene);++ expect(getAssetPathsByType(refs, 'statemachine').size).toBe(0);+ expect(refs.unresolved).toEqual([]);+ });++ it('buckets values the callback accepts', () => {+ const scene = makeScene([{+ id: 1, name: 'e1', parent: null, children: [],+ components: [{ type: AGENT_NAME, data: { fsm: 'ai/enemy.esfsm' } }],+ }]);++ const refs = discoverSceneAssets(scene);++ expect(getAssetPathsByType(refs, 'statemachine')).toEqual(new Set(['ai/enemy.esfsm']));+ });+});++describe('FSM/BT agent asset discovery accepts every serialized ref form', () => {+ const UUID = 'e43a0ed9-50e9-46d8-b1db-da1c549590a8';++ it('StateMachineAgent: .esfsm path, @uuid: ref, bare uuid — but not a code name', () => {+ const discover = StateMachineAgent.discoverAssets!;+ expect(discover({ fsm: 'ai/enemy.esfsm' })).toEqual([{ type: 'statemachine', path: 'ai/enemy.esfsm' }]);+ expect(discover({ fsm: `@uuid:${UUID}` })).toEqual([{ type: 'statemachine', path: `@uuid:${UUID}` }]);+ expect(discover({ fsm: UUID })).toEqual([{ type: 'statemachine', path: UUID }]);+ expect(discover({ fsm: 'patrol' })).toEqual([]);+ expect(discover({ fsm: '' })).toEqual([]);+ });++ it('BehaviorTreeAgent: .esbt path, @uuid: ref, bare uuid — but not a code name', () => {+ const discover = BehaviorTreeAgent.discoverAssets!;+ expect(discover({ bt: 'ai/boss.esbt' })).toEqual([{ type: 'behaviortree', path: 'ai/boss.esbt' }]);+ expect(discover({ bt: `@uuid:${UUID}` })).toEqual([{ type: 'behaviortree', path: `@uuid:${UUID}` }]);+ expect(discover({ bt: UUID })).toEqual([{ type: 'behaviortree', path: UUID }]);+ expect(discover({ bt: 'guard' })).toEqual([]);+ });+});+describe('discoverSceneAssets with UUID refResolver', () => {const UUID_PLAYER = 'aaaaaaaa-1111-4111-8111-aaaaaaaaaaaa';const UUID_LOGO = 'bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb';diff --git a/sdk/tests/resolve-asset-key.test.ts b/sdk/tests/resolve-asset-key.test.tsindex 77a4c67ab..f5adc033c 100644--- a/sdk/tests/resolve-asset-key.test.ts+++ b/sdk/tests/resolve-asset-key.test.ts@@ -2,27 +2,66 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** The one primitive shared by every path-keyed runtime store (FSM, BT, tilemap,- * timeline) to map an authored component ref to its resolved store key.+ * timeline) to map an authored component ref to its resolved store key. The key+ * must equal what the loader registered under — resolver + addressable Catalog,+ * the two steps of every typed load. Resolver-only resolution diverges the+ * moment the Catalog carries an address mapping.*/import { describe, it, expect } from 'vitest';+import { Assets } from '../src/asset/Assets';+import { Catalog } from '../src/asset/Catalog';import { resolveAssetKey } from '../src/asset/resolveAssetKey';-import type { AssetsData } from '../src/asset/AssetPlugin';+import type { Backend } from '../src/asset/Backend';+import type { ESEngineModule } from '../src/wasm';-const assets = (fn: (ref: string) => string | null) =>- ({ resolveRef: fn } as unknown as AssetsData);+const UUID = 'e43a0ed9-50e9-46d8-b1db-da1c549590a8';++function buildAssets(catalog?: Catalog): Assets {+ const backend: Backend = {+ resolveUrl: (p: string) => p,+ fetchText: async () => '',+ fetchBinary: async () => new ArrayBuffer(0),+ } as unknown as Backend;+ return Assets.create({+ backend,+ catalog,+ module: { _malloc: () => 0, _free: () => {} } as unknown as ESEngineModule,+ });+}describe('resolveAssetKey', () => {+ it('falls back to the raw ref when there is no Assets resource', () => {+ expect(resolveAssetKey(null, 'a/b.esbt')).toBe('a/b.esbt');+ expect(resolveAssetKey(undefined, `@uuid:${UUID}`)).toBe(`@uuid:${UUID}`);+ });+it('returns the resolver output when it resolves', () => {- expect(resolveAssetKey(assets((r) => `estella://project/${r}`), 'a/b.esfsm'))- .toBe('estella://project/a/b.esfsm');+ const assets = buildAssets();+ assets.setAssetRefResolver(ref => `estella://project/${ref}`);++ expect(resolveAssetKey(assets, 'a/b.esfsm')).toBe('estella://project/a/b.esfsm');});it('falls back to the raw ref when the resolver returns null (code-registered name)', () => {- expect(resolveAssetKey(assets(() => null), 'myCodeFsm')).toBe('myCodeFsm');+ const assets = buildAssets();+ assets.setAssetRefResolver(() => null);++ expect(resolveAssetKey(assets, 'myCodeFsm')).toBe('myCodeFsm');});- it('falls back to the raw ref when there is no Assets resource', () => {- expect(resolveAssetKey(null, 'a/b.esbt')).toBe('a/b.esbt');- expect(resolveAssetKey(undefined, 'a/b.esbt')).toBe('a/b.esbt');+ it('applies the addressable Catalog after the resolver (registration-key parity)', () => {+ const catalog = Catalog.fromJson({+ version: 1,+ entries: { 'assets/ai/boss.esfsm': { type: 'statemachine' } },+ addresses: { 'ai/boss': 'assets/ai/boss.esfsm' },+ });+ const assets = buildAssets(catalog);+ assets.setAssetRefResolver(ref => (ref === `@uuid:${UUID}` ? 'ai/boss' : ref));++ // loadTyped resolves @uuid → 'ai/boss' → Catalog → 'assets/ai/boss.esfsm'+ // and the loader registers under that path; the tick-time lookup must+ // land on the same key.+ expect(resolveAssetKey(assets, `@uuid:${UUID}`)).toBe('assets/ai/boss.esfsm');+ expect(resolveAssetKey(assets, 'ai/boss')).toBe('assets/ai/boss.esfsm');});});