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): Unpack Prefab — detach an instance from its prefab (P2 UX)

yhheb7da1f6bba6
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.ts
index eaf761253..a41282e4b 100644
--- a/desktop/src/engine/SceneCommands.ts
+++ b/desktop/src/engine/SceneCommands.ts
@@ -4,7 +4,8 @@ import type { SceneData, PrefabData, ControllerState, UIControllerData, GearBind
import { TilemapAPI, TilemapLiveSync, UIPositionType, DimensionUnit, AnchorAxis, writeFieldPath, type AnchorPreset } from 'esengine';
import type { EntityId, InspectorFieldType, InspectorFieldValue } from '@/types';
import { EditorHistory, EditorHistoryImpl } from './EditorHistory';
-import { SceneModel, SceneModelImpl } from './SceneModel';
+import { SceneModel, SceneModelImpl, type PrefabInstanceTag } from './SceneModel';
+import { SceneStore } from './SceneStore';
import { ViewportController } from './ViewportController';
import { expandInstance } from './PrefabInstance';
import { setEntityClipboard, getEntityClipboard, remapClipboardEntities } from './entityClipboard';
@@ -820,6 +821,35 @@ export class SceneCommandsImpl {
return this.create(prefab, { parent });
}
+ /**
+ * Unpack a prefab instance — detach the whole instance subtree from its prefab
+ * so its entities become ordinary, user-owned ones: they no longer collapse to
+ * an instance entry on save and lose their prefab affordances. Works on any
+ * entity of the instance (resolves to the root). Undoable — undo re-links every
+ * entity. Tag changes don't emit a model event (bulk load must not re-render
+ * per tag), so the closures poke the structure revision explicitly.
+ */
+ unpackPrefabInstance(sourceId: EntityId): void {
+ const instanceRoot = this.model.prefabTag(sourceId)?.instanceRoot ?? sourceId;
+ if (!this.model.prefabTag(instanceRoot)) return; // not a prefab instance
+ const saved: Array<[EntityId, PrefabInstanceTag]> = [];
+ for (const id of this.model.collectSubtree(instanceRoot)) {
+ const tag = this.model.prefabTag(id);
+ if (tag) saved.push([id as EntityId, tag]);
+ }
+ if (saved.length === 0) return;
+ const unlink = (): void => {
+ for (const [id] of saved) this.model.setPrefabTag(id, undefined);
+ SceneStore.pokeStructure();
+ };
+ const relink = (): void => {
+ for (const [id, tag] of saved) this.model.setPrefabTag(id, tag);
+ SceneStore.pokeStructure();
+ };
+ unlink();
+ this.history.record('Unpack Prefab', unlink, relink);
+ }
+
/** The scene's Canvas entity (UI layout root), or null — the default parent for new UI. */
findCanvas(): EntityId | null {
const e = this.model.current?.entities.find((x) => x.components.some((c) => c.type === 'Canvas'));
diff --git a/desktop/src/engine/SceneStore.ts b/desktop/src/engine/SceneStore.ts
index 7a5db3334..d439fcfe4 100644
--- a/desktop/src/engine/SceneStore.ts
+++ b/desktop/src/engine/SceneStore.ts
@@ -77,6 +77,11 @@ export class SceneStoreImpl {
* skeleton finished loading, so the inspector's animation/skin options
* exist now) — bump the data revision so panels re-read. */
poke = (): void => this.bump(false);
+
+ /** Editor-transient tree state changed WITHOUT a model event (e.g. prefab
+ * instance tags added/removed by Unpack) — bump the structure revision so the
+ * Outliner + Details re-read their prefab affordances. */
+ pokeStructure = (): void => this.bump(true);
}
/** A change affects the tree (shape / name / kind / add-menu), not just a field value. */
diff --git a/desktop/src/i18n/messages/outliner.ts b/desktop/src/i18n/messages/outliner.ts
index 1237e75ba..27a50645b 100644
--- a/desktop/src/i18n/messages/outliner.ts
+++ b/desktop/src/i18n/messages/outliner.ts
@@ -50,6 +50,7 @@ export const outlinerMessages = defineMessages({
'out.prefabSelectSource': { en: 'Select Prefab Source', zh: '选中预制体源' },
'out.prefabApply': { en: 'Apply to Prefab', zh: '应用到预制体' },
'out.prefabRevert': { en: 'Revert to Prefab', zh: '还原为预制体' },
+ 'out.prefabUnpack': { en: 'Unpack Prefab', zh: '解包预制体' },
'out.hide': { en: 'Hide', zh: '隐藏' },
'out.show': { en: 'Show', zh: '显示' },
'out.lock': { en: 'Lock', zh: '锁定' },
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index eb7656852..f1d137a6c 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -103,6 +103,7 @@ function prefabInstanceItems(id: number): MenuItem[] {
},
{ label: t('out.prefabApply'), onClick: () => void ProjectStore.applyPrefabInstance(id) },
{ label: t('out.prefabRevert'), onClick: () => void ProjectStore.revertPrefabInstance(id) },
+ { label: t('out.prefabUnpack'), onClick: () => SceneCommands.unpackPrefabInstance(id) },
];
}
diff --git a/desktop/tests/prefab-instantiate.test.ts b/desktop/tests/prefab-instantiate.test.ts
index 4c4545729..bee3d211e 100644
--- a/desktop/tests/prefab-instantiate.test.ts
+++ b/desktop/tests/prefab-instantiate.test.ts
@@ -90,6 +90,30 @@ describe.skipIf(!HAS_WASM)('SceneCommands.instantiatePrefab (headless World)', (
expect(S.model.prefabTag(rootId!)?.prefab).toBe(REF);
});
+ it('unpacks a prefab instance — clears the subtree tags, undo re-links, redo unpacks', () => {
+ const rootId = S.commands.instantiatePrefab(turretPrefab(), REF, null)!;
+ const barrel = S.model.current!.entities.find((e) => e.name === 'Barrel')!;
+ expect(S.model.prefabTag(rootId)).toBeTruthy();
+ expect(S.model.prefabTag(barrel.id)).toBeTruthy();
+
+ // Unpack from ANY entity of the instance (the barrel resolves to the root).
+ S.commands.unpackPrefabInstance(barrel.id);
+ expect(S.model.prefabTag(rootId)).toBeUndefined();
+ expect(S.model.prefabTag(barrel.id)).toBeUndefined();
+ // The entities themselves survive — they are just plain, user-owned now.
+ expect(S.model.current!.entities).toHaveLength(2);
+
+ // Undo re-links every entity to its prefab origin.
+ S.history.undo();
+ expect(S.model.prefabTag(rootId)).toMatchObject({ instanceRoot: rootId, prefab: REF });
+ expect(S.model.prefabTag(barrel.id)).toMatchObject({ instanceRoot: rootId, prefabId: 'barrel' });
+
+ // Redo unpacks again.
+ S.history.redo();
+ expect(S.model.prefabTag(rootId)).toBeUndefined();
+ expect(S.model.prefabTag(barrel.id)).toBeUndefined();
+ });
+
it('instantiates under a parent entity', () => {
const parent = S.commands.addEntity()!;
const rootId = S.commands.instantiatePrefab(turretPrefab(), REF, parent)!;