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): incremental re-projection resolves plain-path asset refs

yhh38f6760b25db
diff --git a/desktop/src/engine/Reconciler.ts b/desktop/src/engine/Reconciler.ts
index 548ff3aaa..a39985396 100644
--- a/desktop/src/engine/Reconciler.ts
+++ b/desktop/src/engine/Reconciler.ts
@@ -6,7 +6,7 @@ import type { EntityId } from '@/types';
import { EngineHost } from './EngineHost';
import { PerfMonitor } from './PerfMonitor';
import { SceneModel, SceneModelImpl, type ModelEvent } from './SceneModel';
-import { componentByName, componentDefaults, isRenderComponent, componentEnable, type AnyComp, type WorldT } from './schema';
+import { assetFieldType, componentByName, componentDefaults, isRenderComponent, componentEnable, type AnyComp, type WorldT } from './schema';
/**
* Projects the model into the World.
@@ -66,7 +66,8 @@ function foldHidden(c: SceneComp): SceneComp {
return { ...c, data: { ...c.data, [en.key]: false } };
}
-type AssetResolver = (uuid: string) => number;
+/** Asset ref (`@uuid:<id>` or a project-relative path) → live handle, 0 if unloaded. */
+type AssetResolver = (ref: string) => number;
const UNRESOLVED: AssetResolver = () => 0;
export class ReconcilerImpl {
@@ -87,9 +88,10 @@ export class ReconcilerImpl {
}
/**
- * Install the `@uuid:` → GL-handle resolver. ProjectStore sets this after
- * loading a scene's textures, so entities recreated incrementally (duplicate,
- * undo-of-delete) re-resolve their asset refs the same way load does. Defaults
+ * Install the asset-ref → GL-handle resolver (`@uuid:` and plain paths — the
+ * same forms the scene loader accepts). ProjectStore sets this after loading a
+ * scene's assets, so entities re-projected incrementally (duplicate, undo,
+ * visibility toggle) re-resolve their refs the same way load does. Defaults
* to "unresolved" (blank to 0) — fine for tests and ref-free scenes.
*/
setAssetResolver(fn: AssetResolver | null): void {
@@ -121,6 +123,7 @@ export class ReconcilerImpl {
if (!world || !data) return;
PerfMonitor.measure('world.rebuild', () => {
const resolved = this.resolveRefs(data) as SceneData;
+ this.resolveAssetFields(resolved);
const map = resetWorldTo(world, worldProjection(resolved) as never) as Map<number, EntityId>;
this.model.adopt(data, map);
});
@@ -196,7 +199,7 @@ export class ReconcilerImpl {
// Re-fold editor-hidden each time we project a render component, so a field
// edit on a hidden entity doesn't quietly un-hide it in the viewport.
const src = this.model.isHidden(sourceId) ? foldHidden(comp) : comp;
- const data = this.projectData(def, src.data as Record<string, unknown>);
+ const data = this.projectData(type, def, src.data as Record<string, unknown>);
if (world.has(rt, def)) world.set(rt, def, data as Parameters<WorldT['set']>[2]);
else world.insert(rt, def, data as never);
}
@@ -246,27 +249,46 @@ export class ReconcilerImpl {
if (STRUCTURAL.has(type)) return;
const def = componentByName(type);
if (!def) return; // unknown — model only
- world.insert(rt, def, this.projectData(def, data) as never);
+ world.insert(rt, def, this.projectData(type, def, data) as never);
}
/**
* Build the World-facing component data from the model's record: keep only the
* fields the engine component knows (the World is lossy — schema-extra fields
- * stay in the model), and resolve `@uuid:` asset refs to live GL handles.
+ * stay in the model), and resolve asset refs to live GL handles. Asset fields
+ * accept the same ref forms the scene loader does — `@uuid:` or a plain path.
*/
- private projectData(def: AnyComp, data: Record<string, unknown>): Record<string, unknown> {
+ private projectData(type: string, def: AnyComp, data: Record<string, unknown>): Record<string, unknown> {
const defaults = componentDefaults(def);
const out: Record<string, unknown> = {};
for (const key of Object.keys(defaults)) {
- out[key] = key in data ? this.resolveRefs(data[key]) : defaults[key];
+ if (!(key in data)) {
+ out[key] = defaults[key];
+ continue;
+ }
+ const v = data[key];
+ out[key] = typeof v === 'string' && assetFieldType(type, key) ? this.resolveAsset(v) : this.resolveRefs(v);
}
return out;
}
+ /** Resolve plain-path asset-field refs left after the `@uuid:` pass (rebuild path). */
+ private resolveAssetFields(data: SceneData): void {
+ for (const e of data.entities) {
+ for (const c of e.components ?? []) {
+ const d = c.data as Record<string, unknown> | undefined;
+ if (!d) continue;
+ for (const [k, v] of Object.entries(d)) {
+ if (typeof v === 'string' && assetFieldType(c.type, k)) d[k] = this.resolveAsset(v);
+ }
+ }
+ }
+ }
+
/** Recursively replace `@uuid:<id>` strings with resolved asset handles. */
private resolveRefs(value: unknown): unknown {
if (typeof value === 'string') {
- return value.startsWith(UUID_PREFIX) ? this.resolveAsset(value.slice(UUID_PREFIX.length)) : value;
+ return value.startsWith(UUID_PREFIX) ? this.resolveAsset(value) : value;
}
if (Array.isArray(value)) return value.map((v) => this.resolveRefs(v));
if (value && typeof value === 'object') {
diff --git a/desktop/src/engine/SceneLoader.ts b/desktop/src/engine/SceneLoader.ts
index 6b3b24e8d..929236039 100644
--- a/desktop/src/engine/SceneLoader.ts
+++ b/desktop/src/engine/SceneLoader.ts
@@ -47,7 +47,7 @@ export const SceneLoader = {
assets.resolveSceneAssetPaths(resolved, result);
// Incremental recreate (duplicate / undo) re-resolves textures from the
// engine's live cache (just loaded above).
- Reconciler.setAssetResolver((uuid) => assets.getTexture(UUID_PREFIX + uuid)?.handle ?? 0);
+ Reconciler.setAssetResolver((ref) => assets.getTexture(ref)?.handle ?? 0);
}
const map = PerfMonitor.measure('scene.load', () => loadSceneData(app.world, resolved as SceneDataArg));
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 27236380d..969437ccf 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -298,7 +298,7 @@ class ProjectStoreImpl {
useSelection.getState().select(null);
// Incremental recreate (duplicate / undo / play-stop) re-resolves @uuid:→handle
// from the same preload result — for all types, not just textures.
- Reconciler.setAssetResolver((uuid) => this.handleForUuid(uuid));
+ Reconciler.setAssetResolver((ref) => this.handleForRef(ref));
Reconciler.adopt(expandedRaw, resolved);
// Re-apply prefab-instance tags (adopt cleared them) so save can collapse.
for (const { id, tag } of tags) SceneModel.setPrefabTag(id, tag);
@@ -361,7 +361,7 @@ class ProjectStoreImpl {
await this.buildAssetRegistry(); // keep the uuid→path registry current for new refs
EditorHistory.clear();
useSelection.getState().select(null);
- Reconciler.setAssetResolver((uuid) => this.handleForUuid(uuid));
+ Reconciler.setAssetResolver((ref) => this.handleForRef(ref));
Reconciler.adopt(blank, blank); // no @uuid: refs → resolved === raw
EngineHost.syncEditorViewToScene();
this.store.setState({ project: { ...st, currentScene: null } });
@@ -453,11 +453,12 @@ class ProjectStoreImpl {
/** The live GL handle for a uuid. Textures read the engine's live cache (so a
* just-assigned texture resolves); material/font fall back to the scene preload. */
- private handleForUuid(uuid: string): number {
- const ref = UUID_PREFIX + uuid;
+ private handleForRef(ref: string): number {
const tex = EngineHost.getResource(Assets)?.getTexture(ref);
if (tex) return tex.handle;
- const path = this.uuidToPath.get(uuid.toLowerCase());
+ const path = ref.startsWith(UUID_PREFIX)
+ ? this.uuidToPath.get(ref.slice(UUID_PREFIX.length).toLowerCase())
+ : ref;
const r = this.lastAssetResult;
if (!path || !r) return 0;
return r.materialHandles.get(path) ?? r.fontHandles.get(path) ?? 0;
@@ -871,11 +872,16 @@ class ProjectStoreImpl {
}
}
- /** Display info for an asset ref (`@uuid:`), or null (none / unresolved). For
- * the inspector's asset control: the project-relative path + a leaf name. */
+ /** Display info for an asset ref (`@uuid:` or a project-relative path — the same
+ * forms the loaders accept), or null (none / unresolved). For the inspector's
+ * asset control: the project-relative path + a leaf name. */
assetInfo(ref: unknown): { path: string; name: string } | null {
- if (typeof ref !== 'string' || !ref.startsWith(UUID_PREFIX)) return null;
- const path = this.uuidToPath.get(ref.slice(UUID_PREFIX.length).toLowerCase());
+ if (typeof ref !== 'string' || ref.length === 0) return null;
+ const path = ref.startsWith(UUID_PREFIX)
+ ? this.uuidToPath.get(ref.slice(UUID_PREFIX.length).toLowerCase())
+ : this.assetRef(ref)
+ ? ref
+ : undefined;
return path ? { path, name: path.split('/').pop() ?? path } : null;
}
diff --git a/desktop/tests/engine-model-sync.test.ts b/desktop/tests/engine-model-sync.test.ts
index 20f6671b0..467e03d59 100644
--- a/desktop/tests/engine-model-sync.test.ts
+++ b/desktop/tests/engine-model-sync.test.ts
@@ -11,7 +11,7 @@
* the scene into the (mocked) headless World; commands flow model→World through it.
*/
import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
-import { App, Transform, Parent } from 'esengine';
+import { App, Transform, Parent, Sprite } from 'esengine';
import type { ESEngineModule, SceneData } from 'esengine';
import { loadWasmModule, HAS_WASM } from './helpers/loadWasm';
@@ -120,6 +120,39 @@ describe.skipIf(!HAS_WASM)('Model-authoritative projection + lossless save', ()
expect(inspectorFields('Transform', tData).some((f) => f.key === 'rotation')).toBe(true);
});
+ it('visibility toggle re-resolves plain-path asset refs (no white-block)', () => {
+ const raw = (): SceneData => ({
+ version: '1.0',
+ name: 'fx',
+ entities: [
+ {
+ id: 7,
+ name: 'FX',
+ parent: null,
+ children: [],
+ components: [
+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 0 } } },
+ { type: 'Sprite', data: { texture: 'assets/t.png', material: 'assets/m.esmaterial' } },
+ ],
+ },
+ ],
+ }) as unknown as SceneData;
+ const resolved = raw();
+ (resolved.entities[0].components[1].data as Record<string, unknown>).texture = 42;
+ (resolved.entities[0].components[1].data as Record<string, unknown>).material = 9;
+ S.reconciler.setAssetResolver((ref) => (ref === 'assets/t.png' ? 42 : ref === 'assets/m.esmaterial' ? 9 : 0));
+ S.reconciler.adopt(raw(), resolved);
+ const rt = S.model.runtimeFor(7)!;
+
+ S.commands.setEntityVisible(7, false);
+ S.commands.setEntityVisible(7, true);
+
+ const sprite = host.world.get(rt, Sprite) as { texture: number; material: number; enabled: boolean };
+ expect(sprite.texture).toBe(42);
+ expect(sprite.material).toBe(9);
+ expect(sprite.enabled).toBe(true);
+ });
+
it('addEntity / undo is reflected in the model', () => {
const before = S.model.serialize()!.entities.length;
S.commands.addEntity();
diff --git a/examples/effects-gallery/assets/scenes/main.esscene b/examples/effects-gallery/assets/scenes/main.esscene
index 2ba9b036b..fefccc7ee 100644
--- a/examples/effects-gallery/assets/scenes/main.esscene
+++ b/examples/effects-gallery/assets/scenes/main.esscene
@@ -9,7 +9,7 @@
"children": [],
"components": [
{ "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
- { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 360, "isActive": true, "priority": 0, "backgroundColor": { "r": 0.09, "g": 0.1, "b": 0.13, "a": 1 } } }
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 360, "isActive": true, "priority": 0 } }
],
"visible": true
},