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): prefab scene⇄model transform (REARCH_PREFABS PF2)
esengine64677c520e58
diff --git a/desktop/src/engine/PrefabInstance.ts b/desktop/src/engine/PrefabInstance.tsindex 643b1034a..757d9ec57 100644--- a/desktop/src/engine/PrefabInstance.ts+++ b/desktop/src/engine/PrefabInstance.ts@@ -56,7 +56,7 @@ export function expandInstance(prefab: PrefabData,delta: PrefabInstanceDelta,allocateId: () => number,-): ProcessedEntity[] {+): { entities: ProcessedEntity[]; rootId: number } {const { entities, rootId } = flattenPrefab(prefab, delta.overrides, {allocateId,loadPrefab: () => null, // nested prefabs: PF2-later@@ -88,14 +88,17 @@ export function expandInstance(});const all = [...kept, ...added];- // Rebuild children arrays from parent links so the subtree stays consistent- // (kept entities' children may reference removed ids).- const byId = new Map(all.map((e) => [e.id, e]));- for (const e of all) e.children = [];- for (const e of all) {+ rebuildChildren(all);+ return { entities: all, rootId };+}++/** Rebuild every entity's `children` array from its `parent` link (consistency). */+function rebuildChildren(entities: ProcessedEntity[]): void {+ const byId = new Map(entities.map((e) => [e.id, e]));+ for (const e of entities) e.children = [];+ for (const e of entities) {if (e.parent != null) byId.get(e.parent)?.children.push(e.id);}- return all;}/**@@ -119,3 +122,53 @@ export function collapseInstance(}));return { prefab: prefabRef, overrides, added, removed: orphanedSourceIds };}++// ── Scene ⇄ model boundary ──────────────────────────────────────────────────+// A prefab instance is ONE entry in the scene file and an expanded subtree in+// the model. The instance root keeps a stable scene id across save/load (other+// entities may parent to it); the internal entities are re-allocated each load.++/** A prefab instance as it lives in the scene FILE: a delta + where it attaches. */+export interface PrefabInstanceEntry extends PrefabInstanceDelta {+ /** The instance root's stable scene source id. */+ id: number;+ /** The instance root's scene parent (its attach point), or null = scene root. */+ parent: number | null;+}++/**+ * Expand a scene instance entry into model entities: flatten the asset + delta,+ * pin the instance root to the entry's stable `id` (re-allocating only the+ * internal entities), and attach the root under the entry's scene `parent`.+ */+export function expandEntry(+ prefab: PrefabData,+ entry: PrefabInstanceEntry,+ allocateId: () => number,+): { entities: ProcessedEntity[]; rootId: number } {+ const { entities, rootId } = expandInstance(prefab, entry, allocateId);+ // Pin the root to the persisted scene id (external refs target it); internal+ // entities keep their fresh ids. Remap the root id + any parent pointing at it.+ for (const e of entities) {+ if (e.id === rootId) e.id = entry.id;+ if (e.parent === rootId) e.parent = entry.id;+ }+ const root = entities.find((e) => e.id === entry.id);+ if (root) root.parent = entry.parent; // attach under the scene parent+ rebuildChildren(entities);+ return { entities, rootId: entry.id };+}++/**+ * Collapse an expanded instance subtree (root `rootId`, attached under+ * `sceneParent`) back to a scene entry — the inverse of {@link expandEntry}.+ */+export function collapseEntry(+ prefab: PrefabData,+ prefabRef: string,+ expanded: readonly ProcessedEntity[],+ rootId: number,+ sceneParent: number | null,+): PrefabInstanceEntry {+ return { id: rootId, parent: sceneParent, ...collapseInstance(prefab, prefabRef, expanded) };+}diff --git a/desktop/tests/prefab-instance.test.ts b/desktop/tests/prefab-instance.test.tsindex 6f5da7121..5347d4faf 100644--- a/desktop/tests/prefab-instance.test.ts+++ b/desktop/tests/prefab-instance.test.ts@@ -9,7 +9,14 @@import { describe, it, expect } from 'vitest';import { migratePrefabData } from 'esengine';import type { PrefabData } from 'esengine';-import { expandInstance, collapseInstance, type PrefabInstanceDelta } from '@/engine/PrefabInstance';+import {+ expandInstance,+ collapseInstance,+ expandEntry,+ collapseEntry,+ type PrefabInstanceDelta,+ type PrefabInstanceEntry,+} from '@/engine/PrefabInstance';function turretPrefab(): PrefabData {return migratePrefabData({@@ -70,7 +77,7 @@ describe('Prefab instance expand/collapse round-trip', () => {};let nid = 0;- const expanded = expandInstance(prefab, delta, () => nid++);+ const { entities: expanded } = expandInstance(prefab, delta, () => nid++);const back = collapseInstance(prefab, REF, expanded);expect(back.prefab).toBe(REF);@@ -93,7 +100,7 @@ describe('Prefab instance expand/collapse round-trip', () => {const prefab = turretPrefab();const delta: PrefabInstanceDelta = { prefab: REF, overrides: [], added: [], removed: ['scope'] };let nid = 0;- const expanded = expandInstance(prefab, delta, () => nid++);+ const { entities: expanded } = expandInstance(prefab, delta, () => nid++);// root + barrel kept; scope removed; nothing added.expect(expanded.map((e) => e.prefabEntityId).sort()).toEqual(['barrel', 'root']);const root = expanded.find((e) => e.prefabEntityId === 'root')!;@@ -105,9 +112,62 @@ describe('Prefab instance expand/collapse round-trip', () => {const prefab = turretPrefab();const delta: PrefabInstanceDelta = { prefab: REF, overrides: [], added: [], removed: [] };let nid = 0;- const back = collapseInstance(prefab, REF, expandInstance(prefab, delta, () => nid++));+ const back = collapseInstance(prefab, REF, expandInstance(prefab, delta, () => nid++).entities);expect(back.overrides).toEqual([]);expect(back.added).toEqual([]);expect(back.removed).toEqual([]);});++ // ── Scene ⇄ model boundary (expandEntry / collapseEntry) ──+ it('expandEntry pins the root to the entry id + attaches under the scene parent', () => {+ const prefab = turretPrefab();+ const entry: PrefabInstanceEntry = {+ id: 100, // stable scene id of the instance root+ parent: 7, // attaches under scene entity 7+ prefab: REF,+ overrides: [],+ added: [],+ removed: [],+ };+ let nid = 200; // fresh model ids for the internals+ const { entities, rootId } = expandEntry(prefab, entry, () => nid++);+ expect(rootId).toBe(100);+ const root = entities.find((e) => e.id === 100)!;+ expect(root.prefabEntityId).toBe('root');+ expect(root.parent).toBe(7); // scene parent+ // The barrel's parent points at the pinned root id, not the allocated one.+ const barrel = entities.find((e) => e.prefabEntityId === 'barrel')!;+ expect(barrel.parent).toBe(100);+ expect(root.children).toContain(barrel.id);+ });++ it('a scene instance entry round-trips through expandEntry → collapseEntry', () => {+ const prefab = turretPrefab();+ const entry: PrefabInstanceEntry = {+ id: 100,+ parent: 7,+ prefab: REF,+ overrides: [+ { prefabEntityId: 'root', type: 'property', componentType: 'Transform', propertyName: 'position', value: { x: 9, y: 0, z: 0 } },+ { prefabEntityId: 'barrel', type: 'name', value: 'BigBarrel' },+ ],+ added: [+ { prefabEntityId: 'addon1', name: 'Muzzle', components: [{ type: 'Sprite', data: {} }], visible: true, parentId: 'root' },+ ],+ removed: ['scope'],+ };+ let nid = 200;+ const { entities, rootId } = expandEntry(prefab, entry, () => nid++);+ const back = collapseEntry(prefab, REF, entities, rootId, entry.parent);++ expect(back.id).toBe(100); // stable root id preserved+ expect(back.parent).toBe(7); // scene attach point preserved+ expect(back.removed.sort()).toEqual(['scope']);+ expect(back.added.map((a) => a.prefabEntityId)).toEqual(['addon1']);+ expect(back.added[0].parentId).toBe('root');+ expect(+ back.overrides.find((o) => o.type === 'property' && o.prefabEntityId === 'root')?.value,+ ).toEqual({ x: 9, y: 0, z: 0 });+ expect(back.overrides.find((o) => o.type === 'name' && o.prefabEntityId === 'barrel')?.value).toBe('BigBarrel');+ });});