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.

refactor(editor): single-source the asset-slot load table

esengine70306f986ae8
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index c7c5e35e2..a7f6914b0 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -29,6 +29,7 @@ import { confirm } from '@/components/confirm';
import { previewApply } from './applyPreview';
import { t } from '@/i18n';
import { assetTypeOf } from '@/project/assetMeta';
+import { ASSET_SLOTS, metaTypeToSlot } from '@/project/assetSlots';
import type { AssetType } from '@/types';
import { resolveLayout, orientationFromDesignResolution, resolveOrientation, cameraScaleModeValue, WORKSPACE_DIR, PROJECT_MANIFEST_FILE, type OpenedProject, type ProjectFeatures, type ProjectLayout, type ProjectPackaging, type WorkspaceState, type DesignResolution, type ScreenOrientation, type CameraScaleMode } from './format';
import { useEditorMode } from '@/store/editorModeStore';
@@ -107,27 +108,6 @@ interface PreloadResult {
fontHandles: Map<string, number>;
}
-/** `.meta` type vocabulary → component asset-slot type (what the hot loader
- * dispatches on). Null for types no component slot references (scene, shader,
- * spine — spine has its own live sync; prefabs expand at load). */
-function metaTypeToSlot(metaType: string | undefined): string | null {
- switch (metaType) {
- case 'texture': return 'texture';
- case 'material': return 'material';
- case 'font': case 'bitmapFont': return 'font';
- case 'audio': return 'audio';
- case 'video': return 'video';
- case 'animclip': return 'anim-clip';
- case 'animation': return 'timeline';
- case 'tilemap': return 'tilemap';
- case 'tileset': return 'tileset';
- case 'statemachine': return 'statemachine';
- case 'animatorcontroller': return 'animatorcontroller';
- case 'behaviortree': return 'behaviortree';
- default: return null;
- }
-}
-
interface ProjectState {
root: string;
name: string;
@@ -825,39 +805,15 @@ class ProjectStoreImpl {
});
}
- /** Load `ref` with the loader its slot type names — the same loaders the
+ /** Load `ref` through the loader its slot type names — the same loaders the
* scene-open preload dispatches to (one loading truth, two trigger times). */
private loadForSlot(assets: AssetsData, fieldType: string, ref: string, path: string): Promise<unknown> {
- switch (fieldType) {
- case 'texture':
- return assets.loadTexture(ref); // ref, not path: importer settings key off the original ref
- case 'material':
- return assets.loadMaterial(ref).then((r) => this.recordHandle('material', path, r.handle));
- case 'font':
- return assets.loadFont(ref).then((r) => this.recordHandle('font', path, r.handle));
- case 'audio':
- return assets.loadAudio(ref);
- case 'video':
- // Video streams at runtime (the video system, play-mode only) — there is
- // no edit-mode handle to preload. The ref is valid; nothing to load here.
- return Promise.resolve();
- case 'anim-clip':
- return assets.loadAnimClip(ref); // raw ref: the loader aliases it for component lookups
- case 'tilemap':
- return assets.loadTilemap(path);
- case 'tileset':
- return assets.loadTileset(path);
- case 'timeline':
- return assets.loadTimeline(path);
- case 'statemachine':
- return assets.loadStateMachine(path);
- case 'behaviortree':
- return assets.loadBehaviorTree(path);
- case 'animatorcontroller':
- return assets.loadAnimatorController(path);
- default:
- return Promise.reject(new Error(`no live loader for asset slot type "${fieldType}"`));
- }
+ const def = ASSET_SLOTS[fieldType];
+ if (!def) return Promise.reject(new Error(`no live loader for asset slot type "${fieldType}"`));
+ const loaded = def.load(assets, ref, path);
+ if (!def.record) return loaded;
+ const kind = def.record;
+ return loaded.then((r) => this.recordHandle(kind, path, (r as { handle: number }).handle));
}
/** Record a hot-loaded material/font handle where the incremental resolver
diff --git a/desktop/src/project/assetSlots.ts b/desktop/src/project/assetSlots.ts
new file mode 100644
index 000000000..a758fa495
--- /dev/null
+++ b/desktop/src/project/assetSlots.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file assetSlots.ts
+ * @brief The single registry of loadable asset slots. One entry per slot carries
+ * the `.meta` type vocabulary that resolves to it AND the live loader that
+ * fetches it. `metaTypeToSlot` (the reverse map) and the hot-load dispatch
+ * both derive from this table, so a slot can no longer name a meta-type it
+ * has no loader for (the old failure mode when two parallel switches — one
+ * meta→slot, one slot→loader — drifted). Adding a loadable type is one entry.
+ */
+import type { AssetsData } from 'esengine';
+
+/** Slots whose resolved `{handle}` must be recorded where the incremental resolver
+ * looks it up — material/font have no live engine-side cache getter like textures. */
+export type SlotRecord = 'material' | 'font';
+
+export interface AssetSlotDef {
+ /** `.meta` type vocabulary values that resolve to this slot. `font` folds both
+ * `font` and `bitmapFont`; slots with no meta-type (none today) would omit it. */
+ metaTypes: readonly string[];
+ /** The live loader — the SAME one the scene-open preload dispatches to (one
+ * loading truth, two trigger times). `ref` preserves importer-settings keying;
+ * `path` is for file-fetched slots. */
+ load(assets: AssetsData, ref: string, path: string): Promise<unknown>;
+ /** When set, the loader's `{handle}` result is recorded under this kind. */
+ record?: SlotRecord;
+}
+
+export const ASSET_SLOTS: Record<string, AssetSlotDef> = {
+ // ref (not path): importer settings key off the original ref.
+ texture: { metaTypes: ['texture'], load: (a, ref) => a.loadTexture(ref) },
+ material: { metaTypes: ['material'], load: (a, ref) => a.loadMaterial(ref), record: 'material' },
+ font: { metaTypes: ['font', 'bitmapFont'], load: (a, ref) => a.loadFont(ref), record: 'font' },
+ audio: { metaTypes: ['audio'], load: (a, ref) => a.loadAudio(ref) },
+ // Video streams at runtime (play-mode only) — no edit-mode handle to preload.
+ video: { metaTypes: ['video'], load: () => Promise.resolve() },
+ // raw ref: the loader aliases it for component lookups.
+ 'anim-clip': { metaTypes: ['animclip'], load: (a, ref) => a.loadAnimClip(ref) },
+ timeline: { metaTypes: ['animation'], load: (a, _ref, path) => a.loadTimeline(path) },
+ tilemap: { metaTypes: ['tilemap'], load: (a, _ref, path) => a.loadTilemap(path) },
+ tileset: { metaTypes: ['tileset'], load: (a, _ref, path) => a.loadTileset(path) },
+ statemachine: { metaTypes: ['statemachine'], load: (a, _ref, path) => a.loadStateMachine(path) },
+ behaviortree: { metaTypes: ['behaviortree'], load: (a, _ref, path) => a.loadBehaviorTree(path) },
+ animatorcontroller: { metaTypes: ['animatorcontroller'], load: (a, _ref, path) => a.loadAnimatorController(path) },
+};
+
+const metaToSlot = new Map<string, string>();
+for (const [slot, def] of Object.entries(ASSET_SLOTS)) {
+ for (const mt of def.metaTypes) metaToSlot.set(mt, slot);
+}
+
+/** `.meta` type vocabulary → asset-slot type (what the hot loader dispatches on),
+ * or null for types no component slot references (scene/shader/spine have no slot;
+ * prefabs expand at load). */
+export function metaTypeToSlot(metaType: string | undefined): string | null {
+ return metaType ? metaToSlot.get(metaType) ?? null : null;
+}
diff --git a/desktop/tests/asset-slots.test.ts b/desktop/tests/asset-slots.test.ts
new file mode 100644
index 000000000..c423f64bc
--- /dev/null
+++ b/desktop/tests/asset-slots.test.ts
@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { ASSET_SLOTS, metaTypeToSlot } from '../src/project/assetSlots';
+
+describe('ASSET_SLOTS', () => {
+ it('metaTypeToSlot only ever returns a slot that exists in the table', () => {
+ // The whole point of the single table: a meta-type can never resolve to a slot
+ // with no loader (the drift the two-switch design allowed).
+ for (const [slot, def] of Object.entries(ASSET_SLOTS)) {
+ for (const mt of def.metaTypes) {
+ expect(metaTypeToSlot(mt)).toBe(slot);
+ expect(ASSET_SLOTS[metaTypeToSlot(mt)!]).toBeDefined();
+ }
+ }
+ });
+
+ it('no two slots claim the same meta-type', () => {
+ const seen = new Set<string>();
+ for (const def of Object.values(ASSET_SLOTS)) {
+ for (const mt of def.metaTypes) {
+ expect(seen.has(mt), `duplicate meta-type "${mt}"`).toBe(false);
+ seen.add(mt);
+ }
+ }
+ });
+
+ it('preserves the known meta-type → slot mapping', () => {
+ expect(metaTypeToSlot('texture')).toBe('texture');
+ expect(metaTypeToSlot('material')).toBe('material');
+ expect(metaTypeToSlot('font')).toBe('font');
+ expect(metaTypeToSlot('bitmapFont')).toBe('font');
+ expect(metaTypeToSlot('audio')).toBe('audio');
+ expect(metaTypeToSlot('video')).toBe('video');
+ expect(metaTypeToSlot('animclip')).toBe('anim-clip');
+ expect(metaTypeToSlot('animation')).toBe('timeline');
+ expect(metaTypeToSlot('tilemap')).toBe('tilemap');
+ expect(metaTypeToSlot('tileset')).toBe('tileset');
+ expect(metaTypeToSlot('statemachine')).toBe('statemachine');
+ expect(metaTypeToSlot('animatorcontroller')).toBe('animatorcontroller');
+ expect(metaTypeToSlot('behaviortree')).toBe('behaviortree');
+ });
+
+ it('returns null for types with no component slot', () => {
+ expect(metaTypeToSlot(undefined)).toBeNull();
+ expect(metaTypeToSlot('scene')).toBeNull();
+ expect(metaTypeToSlot('shader')).toBeNull();
+ expect(metaTypeToSlot('prefab')).toBeNull();
+ expect(metaTypeToSlot('unknown-type')).toBeNull();
+ });
+
+ it('only material/font capture a handle (the slots with no live cache getter)', () => {
+ const recorded = Object.entries(ASSET_SLOTS).filter(([, d]) => d.record).map(([s]) => s).sort();
+ expect(recorded).toEqual(['font', 'material']);
+ });
+});