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): prefab scene⇄model transform (REARCH_PREFABS PF2)

esengine64677c520e58
diff --git a/desktop/src/engine/PrefabInstance.ts b/desktop/src/engine/PrefabInstance.ts
index 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.ts
index 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');
+ });
});