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(prefab): structural Apply-to-Prefab (P1)

yhh5140f8d13cef
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.ts
index 096b3d6d9..50fa4223c 100644
--- a/desktop/src/i18n/messages/project.ts
+++ b/desktop/src/i18n/messages/project.ts
@@ -106,6 +106,10 @@ export const projectMessages = defineMessages({
'proj.applyWriteFailed': { en: 'Apply failed: could not write {name}', zh: '应用失败:无法写入 {name}' },
'proj.appliedOverride': { en: 'Applied {count} override to {name}', zh: '已将 {count} 项覆盖应用到 {name}' },
'proj.appliedOverrides': { en: 'Applied {count} overrides to {name}', zh: '已将 {count} 项覆盖应用到 {name}' },
+ 'proj.applyStructuralTitle': { en: 'Apply structural changes to prefab?', zh: '将结构改动应用到预制体?' },
+ 'proj.applyStructuralBody': { en: 'This rewrites "{name}" for all of its instances: {overrides} override(s), {added} added, {removed} removed.', zh: '这会重写"{name}"及其所有实例:{overrides} 项覆盖,新增 {added},移除 {removed}。' },
+ 'proj.applyLabel': { en: 'Apply', zh: '应用' },
+ 'proj.appliedStructural': { en: 'Applied to {name}: {overrides} override(s), {added} added, {removed} removed', zh: '已应用到 {name}:{overrides} 项覆盖,新增 {added},移除 {removed}' },
'proj.prefabCreateFailed': { en: 'Failed to create prefab: {name}', zh: '创建预制体失败:{name}' },
'proj.prefabCreated': { en: 'Created prefab: {name}', zh: '已创建预制体:{name}' },
'proj.saveSortingLayersFailed': { en: 'Failed to save sorting layers', zh: '保存排序层失败' },
diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.ts
index f2b6ce820..0730d7f23 100644
--- a/desktop/src/project/ProjectStore.ts
+++ b/desktop/src/project/ProjectStore.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { createStore } from 'zustand/vanilla';
-import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, diffAgainstSource, applyOverridesToSource, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides } from 'esengine';
+import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, collapseInstance, applyDeltaToSource, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides } from 'esengine';
import { readTextureImportSettings } from './assetImporter';
import type { SceneData, PrefabData, ExtractEntity, ProcessedEntity, PhysicsPluginConfig, AudioProjectConfig, AssetsData, ThemeOverrides } from 'esengine';
import { EngineHost } from '@/engine/EngineHost';
@@ -23,6 +23,7 @@ import { SceneStore } from '@/engine/SceneStore';
import { useSelection } from '@/store/selectionStore';
import { Toasts } from '@/store/Toasts';
import { confirmDiscard } from './discardGuard';
+import { confirm } from '@/components/confirm';
import { t } from '@/i18n';
import { assetTypeOf } from '@/project/assetMeta';
import type { AssetType } from '@/types';
@@ -986,13 +987,14 @@ class ProjectStoreImpl {
* re-syncs to that base so its overrides clear. Works on any entity of the
* instance (resolves to the root). Returns the fresh root's source id, or null.
*
- * Scope: property / name / visibility / component overrides on existing prefab
- * entities (the same set `diffAgainstSource` reports). Metadata diffs are dropped
- * — the editor model doesn't track per-instance metadata, so they're never a real
- * override, and baking them would strip the prefab's own metadata. Structural
- * edits (entities the instance added/removed) and live propagation to *other*
- * in-scene instances are not applied here; those siblings re-derive from the new
- * base on next load.
+ * Scope: property / name / visibility / component overrides PLUS structural
+ * edits — entities the instance added or removed are folded into the asset via
+ * `applyDeltaToSource` (structural changes prompt a confirm first, since they
+ * rewrite the shared prefab for every instance). Metadata diffs are dropped —
+ * the editor model doesn't track per-instance metadata, so they're never a real
+ * override, and baking them would strip the prefab's own metadata. Live
+ * propagation to *other* in-scene instances still isn't immediate; those
+ * siblings re-derive from the new base on next load.
*/
async applyPrefabInstance(sourceId: number): Promise<number | null> {
const tag = SceneModel.prefabTag(sourceId);
@@ -1026,32 +1028,57 @@ class ProjectStoreImpl {
}
if (processed.length === 0) return null;
- const overrides = diffAgainstSource(oldPrefab, processed).overrides
+ // The full delta against the asset: property overrides + structural edits.
+ const delta = collapseInstance(oldPrefab, ref, processed);
+ const overrides = delta.overrides
.filter((o) => o.type !== 'metadata_set' && o.type !== 'metadata_removed');
- if (overrides.length === 0) {
+ const { added, removed } = delta;
+ const structural = added.length + removed.length;
+ if (overrides.length === 0 && structural === 0) {
Toasts.push(t('proj.noOverrides'), 'info');
return instanceRoot;
}
- const newPrefab = applyOverridesToSource(oldPrefab, overrides);
+
+ const name = info.path.split('/').pop() ?? info.path;
+
+ // Structural edits rewrite the shared asset for EVERY instance — confirm first.
+ if (structural > 0) {
+ const ok = await confirm({
+ title: t('proj.applyStructuralTitle'),
+ body: t('proj.applyStructuralBody', {
+ name, overrides: overrides.length, added: added.length, removed: removed.length,
+ }),
+ confirmLabel: t('proj.applyLabel'),
+ danger: true,
+ });
+ if (!ok) return instanceRoot;
+ }
+
+ const newPrefab = applyDeltaToSource(oldPrefab, { overrides, added, removed });
try {
await window.estella.fs.write(info.path, JSON.stringify(newPrefab, null, 2) + '\n');
} catch (err) {
- Toasts.push(t('proj.applyWriteFailed', { name: info.path.split('/').pop() ?? info.path }), 'error');
+ Toasts.push(t('proj.applyWriteFailed', { name }), 'error');
return null;
}
this.prefabCache.set(ref, newPrefab);
- // Re-sync this instance to the updated base so its (now-applied) overrides
+ // Re-sync this instance to the updated base so its (now-applied) edits
// clear — reuses the proven delete + re-instantiate path.
const newRoot = await this.revertPrefabInstance(instanceRoot);
- Toasts.push(
- t(overrides.length === 1 ? 'proj.appliedOverride' : 'proj.appliedOverrides', {
- count: overrides.length,
- name: info.path.split('/').pop() ?? info.path,
- }),
- 'success',
- );
+ if (structural > 0) {
+ Toasts.push(t('proj.appliedStructural', {
+ name, overrides: overrides.length, added: added.length, removed: removed.length,
+ }), 'success');
+ } else {
+ Toasts.push(
+ t(overrides.length === 1 ? 'proj.appliedOverride' : 'proj.appliedOverrides', {
+ count: overrides.length, name,
+ }),
+ 'success',
+ );
+ }
return newRoot;
}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 15652fdc1..b13af203a 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1287 stable · 17 beta · 0 deprecated
+Symbols: 1289 stable · 17 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -5786,6 +5786,13 @@ world: World
PlatformSocketReadyState
```
+## SourceDelta — interface
+```
+added: readonly AddedEntity[]
+overrides: readonly PrefabOverride[]
+removed: readonly string[]
+```
+
## SpatialAudioConfig — interface
```
maxDistance: number
@@ -7865,6 +7872,11 @@ AnimationPlugin
(app: { setMaxDeltaTime(v: number): void; setMaxFixedSteps(v: number): void; }, config: RuntimeBuildConfig): void
```
+## applyDeltaToSource — function
+```
+(source: PrefabData, delta: SourceDelta): PrefabData
+```
+
## applyOverrides — function
```
(entity: OverrideTarget, overrides: readonly PrefabOverride[] | undefined): void
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 8174f679d..f79c57128 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1286 stable · 19 beta · 0 deprecated
+Symbols: 1288 stable · 19 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -5781,6 +5781,13 @@ world: World
PlatformSocketReadyState
```
+## SourceDelta — interface
+```
+added: readonly AddedEntity[]
+overrides: readonly PrefabOverride[]
+removed: readonly string[]
+```
+
## SpatialAudioConfig — interface
```
maxDistance: number
@@ -7860,6 +7867,11 @@ AnimationPlugin
(app: { setMaxDeltaTime(v: number): void; setMaxFixedSteps(v: number): void; }, config: RuntimeBuildConfig): void
```
+## applyDeltaToSource — function
+```
+(source: PrefabData, delta: SourceDelta): PrefabData
+```
+
## applyOverrides — function
```
(entity: OverrideTarget, overrides: readonly PrefabOverride[] | undefined): void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 587070ae1..a4b612e31 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 1297 stable · 17 beta · 0 deprecated
+Symbols: 1299 stable · 17 beta · 0 deprecated
## ANCHOR_AXES — const
```
@@ -5788,6 +5788,13 @@ world: World
PlatformSocketReadyState
```
+## SourceDelta — interface
+```
+added: readonly AddedEntity[]
+overrides: readonly PrefabOverride[]
+removed: readonly string[]
+```
+
## SpatialAudioConfig — interface
```
maxDistance: number
@@ -7884,6 +7891,11 @@ AnimationPlugin
(app: { setMaxDeltaTime(v: number): void; setMaxFixedSteps(v: number): void; }, config: RuntimeBuildConfig): void
```
+## applyDeltaToSource — function
+```
+(source: PrefabData, delta: SourceDelta): PrefabData
+```
+
## applyOverrides — function
```
(entity: OverrideTarget, overrides: readonly PrefabOverride[] | undefined): void
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index a9ecbafd8..e5091c59b 100644
--- a/sdk/src/core-content.ts
+++ b/sdk/src/core-content.ts
@@ -182,6 +182,7 @@ export {
collapseEntry,
rebuildChildren,
extractPrefab,
+ applyDeltaToSource,
type PrefabEntityId,
type ProcessedEntity,
type FlattenContext,
@@ -199,6 +200,7 @@ export {
type PrefabInstanceEntry,
type SyncPrefabResolver,
type ExtractEntity,
+ type SourceDelta,
} from './prefab/index';
export { Prefabs, PrefabServer, PrefabsPlugin, prefabsPlugin } from './prefabServer';
diff --git a/sdk/src/prefab/index.ts b/sdk/src/prefab/index.ts
index 704ab2150..3f5da3bed 100644
--- a/sdk/src/prefab/index.ts
+++ b/sdk/src/prefab/index.ts
@@ -38,6 +38,7 @@ export {
collapseEntry,
rebuildChildren,
extractPrefab,
+ applyDeltaToSource,
} from './sceneInstance';
export type {
AddedEntity,
@@ -45,4 +46,5 @@ export type {
PrefabInstanceEntry,
SyncPrefabResolver,
ExtractEntity,
+ SourceDelta,
} from './sceneInstance';
diff --git a/sdk/src/prefab/sceneInstance.ts b/sdk/src/prefab/sceneInstance.ts
index 4a93fcd60..5f0f972ff 100644
--- a/sdk/src/prefab/sceneInstance.ts
+++ b/sdk/src/prefab/sceneInstance.ts
@@ -30,6 +30,7 @@ import { flattenPrefab } from './flatten';
import { diffEntities } from './diff';
import type { DiffBaselineEntity } from './diff';
import { cloneComponents } from './clone';
+import { applyOverridesToSource } from './override';
import { getComponent } from '../component';
import { PREFAB_FORMAT_VERSION } from './migrate';
import type {
@@ -271,6 +272,79 @@ export function collapseEntry(
return { id: rootId, parent: sceneParent, ...collapseInstance(prefab, prefabRef, expanded, loadPrefab) };
}
+// ── Apply-to-Prefab: fold a whole instance delta back into the asset ─────────
+
+/** The structural + property parts of a delta applied by {@link applyDeltaToSource}. */
+export interface SourceDelta {
+ overrides: readonly PrefabOverride[];
+ added: readonly AddedEntity[];
+ removed: readonly PrefabEntityId[];
+}
+
+/**
+ * Bake a complete instance delta into a prefab's source — the STRUCTURAL
+ * "Apply to Prefab". `applyOverridesToSource` only folds property/component/
+ * name/visibility/metadata edits; this also inserts `added` entities (linked
+ * under their parent) and deletes `removed` subtree roots and their descendants
+ * (never the prefab root), so an instance's structural changes truly enter the
+ * asset. Pure: `source` is not mutated. Nested-scoped ids (composed `slot/…`
+ * addresses) that don't exist on this source are skipped — structural apply
+ * targets the top-level asset.
+ */
+export function applyDeltaToSource(source: PrefabData, delta: SourceDelta): PrefabData {
+ // 1. Property / component / name / visibility / metadata overrides.
+ let next = applyOverridesToSource(source, delta.overrides);
+
+ // 2. Removed: drop each removed subtree root + descendants (never the root),
+ // and unlink them from any parent's children list.
+ if (delta.removed.length > 0) {
+ const childrenOf = new Map<PrefabEntityId, PrefabEntityId[]>();
+ for (const e of next.entities) childrenOf.set(e.prefabEntityId, e.children);
+ const remove = new Set<PrefabEntityId>();
+ const queue = delta.removed.filter((id) => id !== next.rootEntityId);
+ while (queue.length > 0) {
+ const cur = queue.shift()!;
+ if (remove.has(cur)) continue;
+ remove.add(cur);
+ for (const c of childrenOf.get(cur) ?? []) queue.push(c);
+ }
+ if (remove.size > 0) {
+ next = {
+ ...next,
+ entities: next.entities
+ .filter((e) => !remove.has(e.prefabEntityId))
+ .map((e) => ({ ...e, children: e.children.filter((c) => !remove.has(c)) })),
+ };
+ }
+ }
+
+ // 3. Added: append new entities and link each under its parent (root default).
+ if (delta.added.length > 0) {
+ const entities: PrefabEntityData[] = next.entities.map((e) => ({ ...e, children: [...e.children] }));
+ const byId = new Map<PrefabEntityId, PrefabEntityData>();
+ for (const e of entities) byId.set(e.prefabEntityId, e);
+ for (const a of delta.added) {
+ const entity: PrefabEntityData = {
+ prefabEntityId: a.prefabEntityId,
+ name: a.name,
+ parent: a.parentId ?? next.rootEntityId,
+ children: [],
+ components: cloneComponents([...a.components]),
+ visible: a.visible,
+ };
+ entities.push(entity);
+ byId.set(a.prefabEntityId, entity);
+ }
+ for (const a of delta.added) {
+ const parent = byId.get(a.parentId ?? next.rootEntityId);
+ if (parent && !parent.children.includes(a.prefabEntityId)) parent.children.push(a.prefabEntityId);
+ }
+ next = { ...next, entities };
+ }
+
+ return next;
+}
+
// ── Authoring: live entities → a new prefab asset ───────────────────────────
/** A scene/model entity subtree, as fed to {@link extractPrefab} (id-keyed). */
diff --git a/sdk/tests/prefab-apply-to-source.test.ts b/sdk/tests/prefab-apply-to-source.test.ts
index cbec87e3b..2c10142e3 100644
--- a/sdk/tests/prefab-apply-to-source.test.ts
+++ b/sdk/tests/prefab-apply-to-source.test.ts
@@ -10,6 +10,8 @@ import { describe, it, expect } from 'vitest';
// re-exports undefined (the bundled dist resolves them fine). Types are erased, so
// they can still come from the barrel.
import { applyOverridesToSource } from '../src/prefab/override';
+import { applyDeltaToSource } from '../src/prefab/sceneInstance';
+import type { AddedEntity } from '../src/prefab/sceneInstance';
import type { PrefabData, PrefabOverride } from '../src/prefab';
function basePrefab(): PrefabData {
@@ -90,3 +92,85 @@ describe('applyOverridesToSource', () => {
expect(next).toEqual(basePrefab());
});
});
+
+// ── Structural Apply: overrides + added + removed folded into the source ─────
+
+/** root '0' → mid '1' → leaf '2' (a 3-generation prefab). */
+function chainPrefab(): PrefabData {
+ return {
+ version: '2', name: 'Chain', rootEntityId: '0',
+ entities: [
+ { prefabEntityId: '0', name: 'Root', parent: null, children: ['1'], visible: true, components: [] },
+ { prefabEntityId: '1', name: 'Mid', parent: '0', children: ['2'], visible: true, components: [] },
+ { prefabEntityId: '2', name: 'Leaf', parent: '1', children: [], visible: true, components: [] },
+ ],
+ };
+}
+
+describe('applyDeltaToSource (structural Apply)', () => {
+ const noDelta = { overrides: [], added: [], removed: [] };
+
+ it('folds overrides just like applyOverridesToSource', () => {
+ const next = applyDeltaToSource(basePrefab(), {
+ ...noDelta,
+ overrides: [{ prefabEntityId: '1', type: 'property', componentType: 'Sprite', propertyName: 'color', value: 'red' }],
+ });
+ expect((next.entities.find((e) => e.prefabEntityId === '1')!.components[0].data as { color: string }).color).toBe('red');
+ });
+
+ it('removes a subtree root and its descendants, unlinking from the parent', () => {
+ const next = applyDeltaToSource(chainPrefab(), { ...noDelta, removed: ['1'] });
+ expect(next.entities.map((e) => e.prefabEntityId)).toEqual(['0']); // mid + leaf gone
+ expect(next.entities[0].children).toEqual([]); // root no longer lists mid
+ });
+
+ it('removes only a leaf when the leaf is the removed root', () => {
+ const next = applyDeltaToSource(chainPrefab(), { ...noDelta, removed: ['2'] });
+ expect(next.entities.map((e) => e.prefabEntityId)).toEqual(['0', '1']);
+ expect(next.entities.find((e) => e.prefabEntityId === '1')!.children).toEqual([]);
+ });
+
+ it('never removes the prefab root even if asked', () => {
+ const next = applyDeltaToSource(chainPrefab(), { ...noDelta, removed: ['0'] });
+ expect(next.entities.some((e) => e.prefabEntityId === '0')).toBe(true);
+ });
+
+ it('inserts an added entity linked under its parent', () => {
+ const added: AddedEntity[] = [
+ { prefabEntityId: 'new1', name: 'Muzzle', components: [{ type: 'Sprite', data: { texture: 'm.png' } }], visible: true, parentId: '1' },
+ ];
+ const next = applyDeltaToSource(basePrefab(), { ...noDelta, added });
+ const created = next.entities.find((e) => e.prefabEntityId === 'new1')!;
+ expect(created.parent).toBe('1');
+ expect(next.entities.find((e) => e.prefabEntityId === '1')!.children).toContain('new1');
+ expect((created.components[0].data as { texture: string }).texture).toBe('m.png');
+ });
+
+ it('attaches an added entity with null parentId under the root', () => {
+ const added: AddedEntity[] = [
+ { prefabEntityId: 'top', name: 'Top', components: [], visible: true, parentId: null },
+ ];
+ const next = applyDeltaToSource(basePrefab(), { ...noDelta, added });
+ expect(next.entities.find((e) => e.prefabEntityId === 'top')!.parent).toBe('0');
+ expect(next.entities.find((e) => e.prefabEntityId === '0')!.children).toContain('top');
+ });
+
+ it('combines overrides + added + removed in one pass', () => {
+ const next = applyDeltaToSource(chainPrefab(), {
+ overrides: [{ prefabEntityId: '0', type: 'name', value: 'Boss' }],
+ added: [{ prefabEntityId: 'gun', name: 'Gun', components: [], visible: true, parentId: '0' }],
+ removed: ['1'],
+ });
+ expect(next.entities.find((e) => e.prefabEntityId === '0')!.name).toBe('Boss');
+ expect(next.entities.some((e) => e.prefabEntityId === 'gun')).toBe(true);
+ expect(next.entities.some((e) => e.prefabEntityId === '1')).toBe(false); // mid removed
+ expect(next.entities.find((e) => e.prefabEntityId === '0')!.children).toEqual(['gun']); // mid unlinked, gun linked
+ });
+
+ it('is pure — the input source is not mutated', () => {
+ const src = chainPrefab();
+ applyDeltaToSource(src, { overrides: [], added: [{ prefabEntityId: 'x', name: 'X', components: [], visible: true, parentId: '0' }], removed: ['2'] });
+ expect(src.entities.map((e) => e.prefabEntityId)).toEqual(['0', '1', '2']);
+ expect(src.entities[0].children).toEqual(['1']);
+ });
+});