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-instance support in the Outliner (P2 UX)

yhh98c6969ad415
diff --git a/desktop/src/engine/SceneModel.ts b/desktop/src/engine/SceneModel.ts
index 14655ed04..b08cc527f 100644
--- a/desktop/src/engine/SceneModel.ts
+++ b/desktop/src/engine/SceneModel.ts
@@ -473,6 +473,12 @@ export class SceneModelImpl {
return this.prefabTags.get(sourceId);
}
+ /** True if this entity is the ROOT of a prefab instance — the `prefab` ref is
+ * set only on the root, so members carry a tag but no ref (see PrefabInstance). */
+ isInstanceRoot(sourceId: number): boolean {
+ return this.prefabTags.get(sourceId)?.prefab != null;
+ }
+
/**
* Insert a pre-formed, self-consistent subtree of entities (e.g. an expanded
* prefab instance) whose ids are already allocated (via {@link allocateSourceId}).
diff --git a/desktop/src/i18n/messages/outliner.ts b/desktop/src/i18n/messages/outliner.ts
index 5d6927022..1237e75ba 100644
--- a/desktop/src/i18n/messages/outliner.ts
+++ b/desktop/src/i18n/messages/outliner.ts
@@ -47,6 +47,9 @@ export const outlinerMessages = defineMessages({
'out.deleteFolder': { en: 'Delete Folder', zh: '删除文件夹' },
'out.duplicate': { en: 'Duplicate', zh: '创建副本' },
'out.createPrefab': { en: 'Create Prefab', zh: '创建预制体' },
+ 'out.prefabSelectSource': { en: 'Select Prefab Source', zh: '选中预制体源' },
+ 'out.prefabApply': { en: 'Apply to Prefab', zh: '应用到预制体' },
+ 'out.prefabRevert': { en: 'Revert to Prefab', zh: '还原为预制体' },
'out.hide': { en: 'Hide', zh: '隐藏' },
'out.show': { en: 'Show', zh: '显示' },
'out.lock': { en: 'Lock', zh: '锁定' },
diff --git a/desktop/src/outliner/OutlinerRow.tsx b/desktop/src/outliner/OutlinerRow.tsx
index 61598c5d7..bc7e81f30 100644
--- a/desktop/src/outliner/OutlinerRow.tsx
+++ b/desktop/src/outliner/OutlinerRow.tsx
@@ -44,8 +44,10 @@ export interface OutlinerRowProps {
renaming?: boolean;
/** Active drop indicator: `on` (full row) or a between-rows insertion line. */
dropPos?: 'before' | 'on' | 'after';
- /** Prefab-instance member — warm icon tint (entity rows only). */
- prefab?: boolean;
+ /** Prefab-instance role (entity rows): `root` = the instance's top entity
+ * (warm name + icon), `member` = an entity inside the prefab (warm icon tint).
+ * Absent = not part of a prefab instance. */
+ prefabRole?: 'root' | 'member';
/** When false, the twist is hidden + non-interactive (the always-expanded live-game tree). */
collapsible?: boolean;
/** Trailing columns to render after the name (the column registry). */
@@ -68,7 +70,7 @@ export interface OutlinerRowProps {
// re-renders only the rows whose props actually changed (the old/new selected
// row), not the whole visible window — provided the parent passes stable handlers.
function OutlinerRowInner(props: OutlinerRowProps) {
- const { item, selected, renaming, dropPos, prefab, columns, columnCtx } = props;
+ const { item, selected, renaming, dropPos, prefabRole, columns, columnCtx } = props;
const isFolder = item.kind === 'folder';
const { depth, hasChildren, expanded } = item;
@@ -88,7 +90,8 @@ function OutlinerRowInner(props: OutlinerRowProps) {
`${expanded ? ' open' : ''}` +
`${visible ? '' : ' hidden'}` +
`${locked ? ' locked' : ''}` +
- `${prefab ? ' prefab' : ''}` +
+ `${prefabRole ? ' prefab' : ''}` +
+ `${prefabRole === 'root' ? ' prefab-root' : ''}` +
`${isFolder ? ' folder' : ''}` +
`${dropPos === 'on' ? ' drop' : ''}` +
`${dropPos === 'before' ? ' drop-before' : ''}` +
diff --git a/desktop/src/panels/Outliner.tsx b/desktop/src/panels/Outliner.tsx
index 068486bb1..eb7656852 100644
--- a/desktop/src/panels/Outliner.tsx
+++ b/desktop/src/panels/Outliner.tsx
@@ -85,6 +85,27 @@ function GameTree() {
);
}
+/** Right-click prefab-instance actions (Select Source / Apply / Revert), or [] if
+ * the entity isn't a prefab instance — the Outliner twin of the Inspector's
+ * prefab-bar, backed by the same ProjectStore methods. */
+function prefabInstanceItems(id: number): MenuItem[] {
+ const tag = SceneModel.prefabTag(id);
+ const ref = tag?.prefab ?? (tag ? SceneModel.prefabTag(tag.instanceRoot)?.prefab : undefined);
+ if (!ref) return [];
+ return [
+ { sep: true },
+ {
+ label: t('out.prefabSelectSource'),
+ onClick: () => {
+ const info = ProjectStore.assetInfo(ref);
+ if (info) useSelection.getState().selectAsset(info.path);
+ },
+ },
+ { label: t('out.prefabApply'), onClick: () => void ProjectStore.applyPrefabInstance(id) },
+ { label: t('out.prefabRevert'), onClick: () => void ProjectStore.revertPrefabInstance(id) },
+ ];
+}
+
export function Outliner() {
const engine = useSyncExternalStore(EngineHost.subscribe, EngineHost.getSnapshot);
const structRev = useSyncExternalStore(SceneStore.subscribe, SceneStore.getStructureRevision);
@@ -549,6 +570,7 @@ export function Outliner() {
},
},
{ label: t('out.createPrefab'), onClick: () => void ProjectStore.createPrefabFromEntity(id) },
+ ...prefabInstanceItems(id),
{
label: t('ui.delete'),
shortcut: formatKeybinding('delete'),
@@ -604,7 +626,15 @@ export function Outliner() {
highlight={highlight}
renaming={renaming === it.key}
dropPos={drop?.key === it.key ? drop.pos : undefined}
- prefab={it.kind === 'entity' && SceneModel.prefabTag(it.id) != null}
+ prefabRole={
+ it.kind === 'entity'
+ ? SceneModel.isInstanceRoot(it.id)
+ ? 'root'
+ : SceneModel.prefabTag(it.id) != null
+ ? 'member'
+ : undefined
+ : undefined
+ }
columns={activeColumns}
columnCtx={columnCtx}
draggable
diff --git a/desktop/src/theme/outliner.css b/desktop/src/theme/outliner.css
index 4a565f5b8..fdc34eb63 100644
--- a/desktop/src/theme/outliner.css
+++ b/desktop/src/theme/outliner.css
@@ -63,6 +63,11 @@
.row.sel .ricon { color: rgba(255, 255, 255, 0.92); }
.row.prefab .ricon { color: var(--info-warm); }
.row.sel.prefab .ricon { color: var(--on-accent); }
+/* Prefab-instance ROOT — the name carries the warm "prefab identity" colour + a
+ touch more weight so an instance reads at a glance; its members keep only the
+ warm icon tint. On selection the name reverts to the readable on-accent colour. */
+.row.prefab-root .rname { color: var(--info-warm); font-weight: 500; }
+.row.sel.prefab-root .rname { color: var(--on-accent); }
.row .rname { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.row .rname mark { background: var(--acc-soft); color: inherit; border-radius: 2px; padding: 0 1px; }
.row.sel .rname mark { background: rgba(255, 255, 255, 0.28); }