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(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.ts
new file mode 100644
index 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.ts
index 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.tsx
index 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 === 'sprite
export 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 && (
<button
type="button"
className="pk"
@@ -990,6 +997,7 @@ function FieldRow({ entities, comp, field, write }: { entities: EntityId[]; comp
<AssetControl
value={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.ts
index 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: S
let 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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();
+ });
+});