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.

feat(editor): retain SceneData as the source of truth on load (JSON-first L1)

esenginec4ec83a7afa2
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.ts
new file mode 100644
index 000000000..88299efef
--- /dev/null
+++ b/desktop/src/engine/SceneModel.ts
@@ -0,0 +1,69 @@
+import type { SceneData } from 'esengine';
+import type { EntityId } from '@/types';
+
+type SceneEntity = SceneData['entities'][number];
+
+/**
+ * The editor's source-of-truth scene data model — JSON-first (REARCH_SERIALIZATION.md, L1).
+ *
+ * Holds the COMPLETE loaded SceneData: components/fields/entities the live World
+ * drops on projection (unknown component types, schema-extra fields,
+ * `visible:false` entities) and portable `@uuid:` asset refs, all preserved here
+ * verbatim. The World is a lossy render projection of this model; lossless save
+ * serializes THIS, not the World.
+ *
+ * L1 (this step): adopt + retain the model and the model⇄runtime-entity
+ * correspondence on load. L3 will route edits through here; L4 will save from
+ * here (and retire the editor's `lossy` refuse-to-save guard).
+ */
+class SceneModelImpl {
+ private data: SceneData | null = null;
+ /** runtime World entity → this scene's source entity id. */
+ private readonly runtimeToSource = new Map<EntityId, number>();
+ /** source entity id → runtime World entity (absent for visible:false / unspawned). */
+ private readonly sourceToRuntime = new Map<number, EntityId>();
+
+ /**
+ * Adopt a freshly-loaded scene as the editor truth.
+ * @param loaded the complete SceneData (with `@uuid:` refs + unknown components)
+ * @param entityMap source-id → runtime entity, as returned by resetWorldTo / loadSceneData
+ */
+ adopt(loaded: SceneData, entityMap: Map<number, EntityId>): void {
+ this.data = loaded;
+ this.runtimeToSource.clear();
+ this.sourceToRuntime.clear();
+ for (const [sourceId, runtime] of entityMap) {
+ this.sourceToRuntime.set(sourceId, runtime);
+ this.runtimeToSource.set(runtime, sourceId);
+ }
+ }
+
+ clear(): void {
+ this.data = null;
+ this.runtimeToSource.clear();
+ this.sourceToRuntime.clear();
+ }
+
+ /** The current scene truth, or null if none loaded. */
+ get current(): SceneData | null {
+ return this.data;
+ }
+
+ /** The source entity record backing a runtime World entity, if tracked. */
+ sourceEntity(runtime: EntityId): SceneEntity | undefined {
+ const sourceId = this.runtimeToSource.get(runtime);
+ if (sourceId === undefined || !this.data) return undefined;
+ return this.data.entities.find((e) => e.id === sourceId);
+ }
+
+ /** Runtime World entity for a source id (if currently spawned). */
+ runtimeFor(sourceId: number): EntityId | undefined {
+ return this.sourceToRuntime.get(sourceId);
+ }
+ /** Source id for a runtime World entity (if tracked). */
+ sourceFor(runtime: EntityId): number | undefined {
+ return this.runtimeToSource.get(runtime);
+ }
+}
+
+export const SceneModel = new SceneModelImpl();
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index 2274ab9f2..1138f4966 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1,6 +1,7 @@
import { resetWorldTo, serializeScene, getComponent, getComponentAssetFields, Assets } from 'esengine';
import type { SceneData } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
+import { SceneModel } from '@/engine/SceneModel';
import { resolveLayout, type OpenedProject, type ProjectLayout, type WorkspaceState } from './format';
/**
@@ -173,7 +174,14 @@ class ProjectStoreImpl {
}
const data = await this.resolveTextures(raw);
const world = EngineHost.mutableWorld();
- if (world) resetWorldTo(world, data);
+ if (world) {
+ // resetWorldTo returns source-id → runtime entity. Adopt the raw scene
+ // (with @uuid: refs + any components/fields/invisible entities the World
+ // drops) as the editor's source of truth (REARCH_SERIALIZATION.md L1).
+ // The World is a lossy projection; the model is what L4 will save.
+ const entityMap = resetWorldTo(world, data);
+ SceneModel.adopt(raw, entityMap);
+ }
this.state = { ...st, currentScene: rel, lossy: dropped.length > 0 };
this.emit();
}
diff --git a/desktop/tests/scene-model.test.ts b/desktop/tests/scene-model.test.ts
new file mode 100644
index 000000000..47830a40b
--- /dev/null
+++ b/desktop/tests/scene-model.test.ts
@@ -0,0 +1,77 @@
+/**
+ * @file SceneModel (JSON-first L1) — proves the editor's source-of-truth model
+ * retains exactly what the live World drops on projection: unknown
+ * component types, visible:false entities, and portable @uuid: asset refs.
+ * This is the basis of lossless save (L4).
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { SceneData } from 'esengine';
+import { SceneModel } from '@/engine/SceneModel';
+
+function fixture(): SceneData {
+ return {
+ version: '1.0',
+ name: 'fixture',
+ entities: [
+ {
+ id: 1,
+ name: 'Player',
+ parent: null,
+ children: [],
+ components: [
+ { type: 'Transform', data: { position: { x: 1, y: 2, z: 3 } } },
+ { type: 'Sprite', data: { texture: '@uuid:abc-123', extraField: 7 } },
+ { type: 'WaveMotion', data: { amplitude: 5 } }, // unknown to this engine
+ ],
+ },
+ {
+ id: 2,
+ name: 'HiddenSpawner',
+ parent: null,
+ children: [],
+ visible: false, // never spawned into the World
+ components: [{ type: 'Spawner', data: { rate: 10 } }],
+ },
+ ],
+ } as unknown as SceneData;
+}
+
+describe('SceneModel (JSON-first source of truth)', () => {
+ beforeEach(() => SceneModel.clear());
+
+ it('retains the full scene incl. unknown components + invisible entities', () => {
+ const scene = fixture();
+ // entity 1 spawned to runtime 100; entity 2 (visible:false) not spawned.
+ SceneModel.adopt(scene, new Map([[1, 100]]));
+
+ expect(SceneModel.current).toBe(scene);
+
+ const player = SceneModel.sourceEntity(100);
+ expect(player?.name).toBe('Player');
+ // unknown component preserved (the World would have dropped it):
+ expect(player?.components.some((c) => c.type === 'WaveMotion')).toBe(true);
+ // schema-extra field + @uuid: ref preserved verbatim:
+ const sprite = player?.components.find((c) => c.type === 'Sprite');
+ expect((sprite?.data as Record<string, unknown>).extraField).toBe(7);
+ expect((sprite?.data as Record<string, unknown>).texture).toBe('@uuid:abc-123');
+
+ // invisible entity survives in the model despite having no runtime entity:
+ const hidden = SceneModel.current!.entities.find((e) => e.id === 2);
+ expect(hidden?.name).toBe('HiddenSpawner');
+ expect(SceneModel.runtimeFor(2)).toBeUndefined();
+ });
+
+ it('maps runtime entities to/from their source ids', () => {
+ SceneModel.adopt(fixture(), new Map([[1, 100]]));
+ expect(SceneModel.runtimeFor(1)).toBe(100);
+ expect(SceneModel.sourceFor(100)).toBe(1);
+ expect(SceneModel.sourceFor(999)).toBeUndefined();
+ });
+
+ it('clear() drops the model and mappings', () => {
+ SceneModel.adopt(fixture(), new Map([[1, 100]]));
+ SceneModel.clear();
+ expect(SceneModel.current).toBeNull();
+ expect(SceneModel.sourceFor(100)).toBeUndefined();
+ });
+});