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(prefab): structural Apply-to-Prefab (P1)
yhh5140f8d13cef
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.tsindex 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.tsindex 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 Teamimport { 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.mdindex 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: WorldPlatformSocketReadyState```+## 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): voiddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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: WorldPlatformSocketReadyState```+## 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): voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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: WorldPlatformSocketReadyState```+## 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): voiddiff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 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.tsindex 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.tsindex 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.tsindex 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']);+ });+});