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): 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.ts
index 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>('Behavio
status: '',
}, {
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.ts
index 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>('StateMa
current: '',
}, {
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.ts
index 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 real
diff --git a/sdk/src/asset/discoverAssets.ts b/sdk/src/asset/discoverAssets.ts
index 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.ts
index 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.ts
index 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 is
diff --git a/sdk/tests/discoverAssets.test.ts b/sdk/tests/discoverAssets.test.ts
index 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.ts
index 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');
});
});