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): Unpack Prefab — detach an instance from its prefab (P2 UX)
yhheb7da1f6bba6
diff --git a/desktop/src/engine/SceneCommands.ts b/desktop/src/engine/SceneCommands.tsindex 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, GearBindimport { 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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)!;