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(editor): the Game inspector names live assets instead of flagging them red
yhhb46826a9e883
diff --git a/desktop/src/engine/liveAssetRefs.ts b/desktop/src/engine/liveAssetRefs.tsnew file mode 100644index 000000000..e187d689f--- /dev/null+++ b/desktop/src/engine/liveAssetRefs.ts@@ -0,0 +1,40 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The realm→inspector vocabulary boundary for asset slots. A running+ * World stores HANDLES in handle-valued asset fields; the inspector+ * layer speaks REFS (paths / `@uuid:`). Shipping raw handles up made the+ * live "Game" Details coerce them to 0 and flag a perfectly-textured+ * Sprite as "required but empty" (red), while showing "None". Translate+ * at the snapshot boundary instead: each realm's own Assets knows which+ * path every handle it minted came from.+ */+import { getComponentAssetFieldDescriptors } from 'esengine';++export interface LiveComponent {+ type: string;+ data: Record<string, unknown>;+}++/**+ * Rewrite handle-valued asset fields to the load paths behind them, via+ * `pathForHandle` (the realm Assets' reverse map — see Assets.pathForHandle).+ * Handles nobody can name (0, or minted outside the Assets channel) pass+ * through untouched; path-valued slots are already strings and never touched.+ * Pure — returns fresh component objects only where a field actually changed.+ */+export function translateAssetHandles(+ components: readonly LiveComponent[],+ pathForHandle: (kind: string, handle: number) => string | null,+): LiveComponent[] {+ return components.map(({ type, data }) => {+ let out: Record<string, unknown> | null = null;+ for (const d of getComponentAssetFieldDescriptors(type)) {+ const v = data[d.field];+ if (typeof v !== 'number' || v === 0) continue;+ const path = pathForHandle(d.type, v);+ if (path !== null) (out ??= { ...data })[d.field] = path;+ }+ return out ? { type, data: out } : { type, data };+ });+}diff --git a/desktop/src/engine/schema.ts b/desktop/src/engine/schema.tsindex b694eb9c5..b85e03ea5 100644--- a/desktop/src/engine/schema.ts+++ b/desktop/src/engine/schema.ts@@ -488,7 +488,11 @@ function fieldFor(const at = assetFieldType(compType, key) ?? spineSlotType(compType, key);let field: InspectorField | null;if (at) {- field = { key, label: prettyLabel(key), type: 'asset', value: typeof value === 'string' ? value : 0, assetType: at };+ // Refs pass through; NUMBERS pass through too — a live realm snapshot holds+ // handles, and coercing a non-zero handle to 0 made the required-empty rule+ // flag a perfectly-loaded asset red. 0/other stays the empty sentinel.+ const v = typeof value === 'string' ? value : typeof value === 'number' ? value : 0;+ field = { key, label: prettyLabel(key), type: 'asset', value: v, assetType: at };} else if (meta?.gradient) {const g = value && typeof value === 'object' && Array.isArray((value as GradientValue).stops) ? (value as GradientValue) : { stops: [] };field = { key, label: prettyLabel(key), type: 'gradient', value: g };diff --git a/desktop/src/panels/Details.tsx b/desktop/src/panels/Details.tsxindex 0a74e337b..c5fe3786d 100644--- a/desktop/src/panels/Details.tsx+++ b/desktop/src/panels/Details.tsx@@ -718,12 +718,16 @@ const isImageAsset = (t: AssetType): boolean => t === 'texture' || t === 'spriteexport function AssetControl({value,assetType,+ readOnly,onBegin,onEnd,onChange,}: ControlGesture & {value: string | number;assetType?: string;+ /** Display-only (the live "Game" inspector): asset identity is not live-tunable+ * — a picked ref would land in a World slot that holds a realm-local handle. */+ readOnly?: boolean;onChange: (v: string | number) => void;}) {const [over, setOver] = useState(false);@@ -751,6 +755,7 @@ export function AssetControl({const onDrop = (e: React.DragEvent) => {e.preventDefault();setOver(false);+ if (readOnly) return;const path = e.dataTransfer.getData('application/x-estella-asset') || e.dataTransfer.getData('text/plain');if (path) setRefFromPath(path);};@@ -802,10 +807,12 @@ export function AssetControl({</span><span className="an">{info ? info.name : t('det.none')}</span></button>- <button type="button" className="pk" title={t('det.pickAsset')} onMouseDown={(e) => e.stopPropagation()} onClick={openPick}>- <Search size={11} strokeWidth={2} />- </button>- {info && (+ {!readOnly && (+ <button type="button" className="pk" title={t('det.pickAsset')} onMouseDown={(e) => e.stopPropagation()} onClick={openPick}>+ <Search size={11} strokeWidth={2} />+ </button>+ )}+ {!readOnly && info && (<buttontype="button"className="pk"@@ -990,6 +997,7 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp<AssetControlvalue={field.value as string | number}assetType={field.assetType}+ readOnly={!!write}onBegin={begin}onEnd={end}onChange={apply}diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex 05e5bac78..342bc22cb 100644--- a/desktop/src/playHost.ts+++ b/desktop/src/playHost.ts@@ -14,10 +14,11 @@* Everything is same-origin estella:// (host, sdk, bundle, wasm, assets),* sidestepping the custom-scheme cross-fetch ban.*/-import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport } from 'esengine';+import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets } from 'esengine';import type { App, ESEngineModule, SceneData } from 'esengine';import { PLAY_PROTOCOL_VERSION } from './engine/playProtocol';import type { PlayOutbound, PlayInbound } from './engine/playProtocol';+import { translateAssetHandles } from './engine/liveAssetRefs';type LiveEntity = SceneData['entities'][number];@@ -65,13 +66,18 @@ function liveSnapshot(world: App['world'], selectedId: number | null): { tree: Slet selected: LiveEntity | null = null;if (selectedId != null) {- const components = inspectableTypes(world, selectedId)+ const raw = inspectableTypes(world, selectedId).map((type) => {const def = getComponent(type);const data = def ? world.tryGet(selectedId as never, def) : null;return data ? { type, data: data as Record<string, unknown> } : null;}).filter((c): c is { type: string; data: Record<string, unknown> } => !!c);+ // The World stores HANDLES in asset slots; the inspector speaks REFS —+ // translate at this boundary via the realm's own Assets, so the Details+ // panel names the asset instead of flagging a live handle as "empty".+ const assets = app?.getResource(Assets) ?? null;+ const components = translateAssetHandles(raw, (kind, handle) => assets?.pathForHandle(kind, handle) ?? null);selected = { id: selectedId, name: nameOf(selectedId), parent: parentOf.get(selectedId) ?? null, children: childrenOf.get(selectedId) ?? [], components } as unknown as LiveEntity;}return { tree, selected };diff --git a/desktop/tests/live-asset-refs.test.ts b/desktop/tests/live-asset-refs.test.tsnew file mode 100644index 000000000..8d703e01e--- /dev/null+++ b/desktop/tests/live-asset-refs.test.ts@@ -0,0 +1,48 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The realm→inspector asset vocabulary boundary. A play-realm snapshot+ * carries HANDLES in handle-valued asset slots; shipping them raw made+ * the Game inspector flag a textured Sprite "required but empty" (red).+ * translateAssetHandles rewrites them to the load paths the realm's own+ * Assets recorded — and leaves everything it can't name untouched.+ */+import { describe, it, expect } from 'vitest';+import { translateAssetHandles } from '../src/engine/liveAssetRefs';++const resolver = (kind: string, handle: number): string | null =>+ kind === 'texture' && handle === 7 ? 'assets/art/hero.png' : null;++describe('translateAssetHandles', () => {+ it('rewrites a live texture handle to its load path', () => {+ const out = translateAssetHandles(+ [{ type: 'Sprite', data: { texture: 7, layer: 2 } }],+ resolver,+ );+ expect(out[0].data.texture).toBe('assets/art/hero.png');+ expect(out[0].data.layer).toBe(2); // non-asset fields untouched+ });++ it('leaves the empty sentinel (0) and unresolvable handles untouched', () => {+ const out = translateAssetHandles(+ [{ type: 'Sprite', data: { texture: 0, material: 99 } }],+ resolver,+ );+ expect(out[0].data.texture).toBe(0); // genuinely empty stays empty (red is truthful)+ expect(out[0].data.material).toBe(99); // nobody can name it — pass through, no lie+ });++ it('passes components without asset slots through by reference (pure, no churn)', () => {+ const transform = { type: 'Transform', data: { position: { x: 1, y: 2, z: 0 } } };+ const out = translateAssetHandles([transform], resolver);+ expect(out[0].data).toBe(transform.data);+ });++ it('already-string refs (path-valued slots) are never touched', () => {+ const out = translateAssetHandles(+ [{ type: 'Tilemap', data: { source: 'assets/maps/level1.tmj' } }],+ () => 'should-not-be-asked',+ );+ expect(out[0].data.source).toBe('assets/maps/level1.tmj');+ });+});diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 843d2751a..3a9b434c1 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -182,6 +182,10 @@ export class Assets {private assetRegistry_: AssetRegistry | null = null;private refCounter_: AssetRefCounter | null = null;private invalidateListeners_ = new Set<InvalidateListener>();+ /** `"<kind>:<handle>"` → resolved load path, recorded on every handle-yielding+ * load. The REVERSE of resolution — inspectors and tooling that only hold a+ * live World handle use it to name the asset (see {@link pathForHandle}). */+ private handleToPath_ = new Map<string, string>();private constructor(options: AssetsOptions) {this.backend = options.backend;@@ -242,6 +246,7 @@ export class Assets {: this.textureLoader_.loadRaw(path, this.getLoadContext_());});this.textureRefCounts_.set(cacheKey, (this.textureRefCounts_.get(cacheKey) ?? 0) + 1);+ this.recordHandlePath_('texture', result.handle, path);return result;}@@ -280,6 +285,22 @@ export class Assets {return this.textureCache_.get(this.textureCacheKey_(path, true));}+ /**+ * The load path behind a LIVE handle (`kind` = the asset slot type:+ * 'texture' | 'material' | 'font' | …), or null when this realm never+ * loaded such a handle. The reverse of ref resolution — the live "Game"+ * inspector uses it to show WHICH asset a World component's handle-valued+ * slot is wearing (a raw handle number names nothing to a human).+ */+ pathForHandle(kind: string, handle: number): string | null {+ return this.handleToPath_.get(`${kind}:${handle}`) ?? null;+ }++ /** Record a handle→path pair for {@link pathForHandle} (dropped on invalidate/releaseAll). */+ private recordHandlePath_(kind: string, handle: number, path: string): void {+ if (handle !== 0) this.handleToPath_.set(`${kind}:${handle}`, path);+ }+async loadSpine(skeletonRef: string, atlasRef?: string): Promise<SpineResult> {const skelPath = this.resolveLoadPath_(skeletonRef);const ctx = this.getLoadContext_();@@ -970,6 +991,12 @@ export class Assets {if (loader.invalidate?.(path)) hit = true;}+ // The reverse handle→path records for this path are stale now too — a+ // reload mints new handles; the old ones must stop naming the asset.+ for (const [key, p] of this.handleToPath_) {+ if (p === path) this.handleToPath_.delete(key);+ }+if (hit) {for (const listener of this.invalidateListeners_) {try {@@ -1016,6 +1043,7 @@ export class Assets {}this.genericCache_.clear();this.genericRefCounts_.clear();+ this.handleToPath_.clear();}// =========================================================================@@ -1161,6 +1189,8 @@ export class Assets {) as Promise<T>);const key = `${type}:${path}`;this.genericRefCounts_.set(key, (this.genericRefCounts_.get(key) ?? 0) + 1);+ const handle = (result as { handle?: unknown } | null)?.handle;+ if (typeof handle === 'number' && handle !== 0) this.recordHandlePath_(type, handle, path);return result;}diff --git a/sdk/tests/asset-handle-path.test.ts b/sdk/tests/asset-handle-path.test.tsnew file mode 100644index 000000000..ba5665019--- /dev/null+++ b/sdk/tests/asset-handle-path.test.ts@@ -0,0 +1,97 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Assets.pathForHandle — the REVERSE of ref resolution. Every+ * handle-yielding load records handle→path, so tooling that only holds+ * a live World handle (the "Game" inspector) can name the asset.+ * Invalidate drops the stale records (a reload mints new handles);+ * releaseAll clears everything.+ */+import { describe, it, expect, vi } from 'vitest';+import { Assets } from '../src/asset/Assets';+import { Catalog } from '../src/asset/Catalog';+import type { Backend } from '../src/asset/Backend';++const mockModule = {+ _malloc: vi.fn(() => 0),+ _free: vi.fn(),+ HEAPU8: new Uint8Array(1024),+ GL: null,+ FS: null,+} as never;++vi.mock('../src/resourceManager', () => ({+ requireResourceManager: () => ({+ createTexture: vi.fn(() => 42),+ registerExternalTexture: vi.fn(() => 42),+ releaseTexture: vi.fn(),+ releaseBitmapFont: vi.fn(),+ getTextureGLId: vi.fn(() => 1),+ registerTextureWithPath: vi.fn(),+ getTextureDimensions: vi.fn(() => ({ width: 64, height: 64 })),+ setTextureMetadata: vi.fn(),+ }),+ getResourceManager: () => null,+ evictTextureDimensions: vi.fn(),+}));++function createMockBackend(): Backend {+ return {+ fetch: vi.fn(async () => new ArrayBuffer(8)),+ fetchText: vi.fn(async () => '{}'),+ resolvePath: vi.fn((p: string) => p),+ resolveUrl: vi.fn((p: string) => p),+ } as never;+}++function createAssets(): Assets {+ return Assets.create({+ backend: createMockBackend(),+ catalog: Catalog.empty(),+ module: mockModule,+ });+}++describe('Assets.pathForHandle', () => {+ it('records handle→path on a typed load and resolves it back', async () => {+ const assets = createAssets();+ assets.register({+ type: 'material',+ extensions: ['.esmaterial'],+ load: async () => ({ handle: 42, shaderHandle: 7 }),+ unload: () => {},+ } as never);+ await assets.loadMaterial('assets/materials/glow.esmaterial');+ expect(assets.pathForHandle('material', 42)).toBe('assets/materials/glow.esmaterial');+ // Kind is part of the key — a texture handle 42 is a different asset.+ expect(assets.pathForHandle('texture', 42)).toBeNull();+ expect(assets.pathForHandle('material', 43)).toBeNull();+ });++ it('invalidate drops the stale reverse records for that path', async () => {+ const assets = createAssets();+ assets.register({+ type: 'material',+ extensions: ['.esmaterial'],+ load: async () => ({ handle: 9, shaderHandle: 1 }),+ unload: () => {},+ } as never);+ await assets.loadMaterial('assets/m.esmaterial');+ expect(assets.pathForHandle('material', 9)).toBe('assets/m.esmaterial');+ assets.invalidate('assets/m.esmaterial');+ expect(assets.pathForHandle('material', 9)).toBeNull();+ });++ it('releaseAll clears every record', async () => {+ const assets = createAssets();+ assets.register({+ type: 'material',+ extensions: ['.esmaterial'],+ load: async () => ({ handle: 5, shaderHandle: 1 }),+ unload: () => {},+ } as never);+ await assets.loadMaterial('assets/m.esmaterial');+ assets.releaseAll();+ expect(assets.pathForHandle('material', 5)).toBeNull();+ });+});