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
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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();+ });+});