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): clear external entity refs on extract, warn first (P1)
yhh49fc4a0c1da1
diff --git a/desktop/src/i18n/messages/project.ts b/desktop/src/i18n/messages/project.tsindex 50fa4223c..9c2c5bb78 100644--- a/desktop/src/i18n/messages/project.ts+++ b/desktop/src/i18n/messages/project.ts@@ -110,6 +110,9 @@ export const projectMessages = defineMessages({'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.prefabExternalRefsTitle': { en: 'Clear external references?', zh: '清除外部引用?' },+ 'proj.prefabExternalRefsBody': { en: '{count} component reference(s) point to entities outside this selection and will be cleared in the prefab.', zh: '有 {count} 处组件引用指向所选之外的实体,将在预制体中被清除。' },+ 'proj.prefabExternalRefsConfirm': { en: 'Create anyway', zh: '仍然创建' },'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 0730d7f23..4079b2b40 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, collapseInstance, applyDeltaToSource, setTextureParams, TextureFilter, TextureWrap, Renderer, RETIRED_COMPONENT_TYPES, parseThemeOverrides } from 'esengine';+import { getComponent, getEditorType, Assets, migratePrefabData, extractPrefab, collectExternalEntityRefs, 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';@@ -1125,6 +1125,19 @@ class ProjectStoreImpl {.filter((e): e is NonNullable<typeof e> => !!e) as unknown as ExtractEntity[];const name = root.name?.trim() || 'Prefab';++ // Refs into entities outside this selection can't live in a standalone prefab;+ // extractPrefab clears them. Warn before dropping the links.+ const external = collectExternalEntityRefs(entities);+ if (external.length > 0) {+ const ok = await confirm({+ title: t('proj.prefabExternalRefsTitle'),+ body: t('proj.prefabExternalRefsBody', { count: external.length }),+ confirmLabel: t('proj.prefabExternalRefsConfirm'),+ });+ if (!ok) return null;+ }+const prefab = extractPrefab(entities, rootSourceId, name);// A filesystem-safe leaf, deduped against existing assets.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex b13af203a..3f93124eb 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: 1289 stable · 17 beta · 0 deprecated+Symbols: 1291 stable · 17 beta · 0 deprecated## ABI_LAYOUT_HASH — const```@@ -2481,6 +2481,14 @@ static new <T>(bus: EventBus<T>): EventWriterInstance<T>static prototype: EventWriterInstance<any>```+## ExternalEntityRef — interface+```+componentType: string+entityId: number+field: string+target: number+```+## ExtractEntity — interface```children: number[]@@ -8082,6 +8090,11 @@ BtPlugin(prefab: PrefabData, prefabRef: string, expanded: readonly ProcessedEntity[], loadPrefab?: SyncPrefabResolver): PrefabInstanceDelta```+## collectExternalEntityRefs — function+```+(entities: readonly ExtractEntity[]): ExternalEntityRef[]+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex f79c57128..d6b04e1ee 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: 1288 stable · 19 beta · 0 deprecated+Symbols: 1290 stable · 19 beta · 0 deprecated## ANCHOR_AXES — const```@@ -2476,6 +2476,14 @@ static new <T>(bus: EventBus<T>): EventWriterInstance<T>static prototype: EventWriterInstance<any>```+## ExternalEntityRef — interface+```+componentType: string+entityId: number+field: string+target: number+```+## ExtractEntity — interface```children: number[]@@ -8077,6 +8085,11 @@ BtPlugin(prefab: PrefabData, prefabRef: string, expanded: readonly ProcessedEntity[], loadPrefab?: SyncPrefabResolver): PrefabInstanceDelta```+## collectExternalEntityRefs — function+```+(entities: readonly ExtractEntity[]): ExternalEntityRef[]+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex a4b612e31..103210f3c 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: 1299 stable · 17 beta · 0 deprecated+Symbols: 1301 stable · 17 beta · 0 deprecated## ANCHOR_AXES — const```@@ -2476,6 +2476,14 @@ static new <T>(bus: EventBus<T>): EventWriterInstance<T>static prototype: EventWriterInstance<any>```+## ExternalEntityRef — interface+```+componentType: string+entityId: number+field: string+target: number+```+## ExtractEntity — interface```children: number[]@@ -8101,6 +8109,11 @@ BtPlugin(prefab: PrefabData, prefabRef: string, expanded: readonly ProcessedEntity[], loadPrefab?: SyncPrefabResolver): PrefabInstanceDelta```+## collectExternalEntityRefs — function+```+(entities: readonly ExtractEntity[]): ExternalEntityRef[]+```+## collectNestedPrefabPaths — function```(prefab: PrefabData, loadPrefab: (path: string) => PrefabData | null, visited?: Set<string>): string[]diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex e5091c59b..62707194e 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -183,6 +183,7 @@ export {rebuildChildren,extractPrefab,applyDeltaToSource,+ collectExternalEntityRefs,type PrefabEntityId,type ProcessedEntity,type FlattenContext,@@ -201,6 +202,7 @@ export {type SyncPrefabResolver,type ExtractEntity,type SourceDelta,+ type ExternalEntityRef,} from './prefab/index';export { Prefabs, PrefabServer, PrefabsPlugin, prefabsPlugin } from './prefabServer';diff --git a/sdk/src/prefab/index.ts b/sdk/src/prefab/index.tsindex 3f5da3bed..13605d2f4 100644--- a/sdk/src/prefab/index.ts+++ b/sdk/src/prefab/index.ts@@ -39,6 +39,7 @@ export {rebuildChildren,extractPrefab,applyDeltaToSource,+ collectExternalEntityRefs,} from './sceneInstance';export type {AddedEntity,@@ -47,4 +48,5 @@ export type {SyncPrefabResolver,ExtractEntity,SourceDelta,+ ExternalEntityRef,} from './sceneInstance';diff --git a/sdk/src/prefab/sceneInstance.ts b/sdk/src/prefab/sceneInstance.tsindex 5f0f972ff..5bb32f15a 100644--- a/sdk/src/prefab/sceneInstance.ts+++ b/sdk/src/prefab/sceneInstance.ts@@ -32,6 +32,7 @@ import type { DiffBaselineEntity } from './diff';import { cloneComponents } from './clone';import { applyOverridesToSource } from './override';import { getComponent } from '../component';+import { INVALID_ENTITY } from '../types';import { PREFAB_FORMAT_VERSION } from './migrate';import type {PrefabData,@@ -368,7 +369,11 @@ export interface ExtractEntity {* Component fields that REFERENCE another entity (declared via the component's* `entityFields` metadata) are remapped to prefab-local ids when the target is* inside the subtree; instantiation maps them back (see remapComponentEntityRefs).- * A reference pointing outside the subtree is left numeric and will dangle.+ * A reference pointing OUTSIDE the subtree cannot be expressed in the prefab, so+ * it is CLEARED (set to `INVALID_ENTITY`) rather than left as a runtime number+ * that would dangle onto an unrelated entity when the prefab is instantiated+ * elsewhere. Call {@link collectExternalEntityRefs} first to warn the user which+ * refs will be dropped.*//** Capture-side twin of remapComponentEntityRefs: runtime id → prefab-local id. */function captureEntityRefs(@@ -380,14 +385,53 @@ function captureEntityRefs(if (!def || def.entityFields.length === 0) continue;for (const field of def.entityFields) {const value = comp.data[field];- if (typeof value === 'number' && idMap.has(value)) {- comp.data[field] = idMap.get(value)!;+ if (typeof value !== 'number') continue;+ if (idMap.has(value)) {+ comp.data[field] = idMap.get(value)!; // in-subtree → stable prefab-local id+ } else if (value !== INVALID_ENTITY) {+ comp.data[field] = INVALID_ENTITY; // external → cleared (never dangle)}}}return components;}+/** An entity-ref field pointing OUTSIDE the extracted subtree. */+export interface ExternalEntityRef {+ /** Source id of the entity holding the reference. */+ entityId: number;+ componentType: string;+ /** The entity-typed field name on that component. */+ field: string;+ /** The out-of-subtree runtime id it currently points at. */+ target: number;+}++/**+ * List the entity-ref fields in a subtree that point OUTSIDE it — the refs that+ * {@link extractPrefab} will clear. The editor calls this before "Create Prefab"+ * to warn the user (or let them cancel) rather than silently dropping links.+ */+export function collectExternalEntityRefs(+ entities: readonly ExtractEntity[],+): ExternalEntityRef[] {+ const inSubtree = new Set(entities.map((e) => e.id));+ const out: ExternalEntityRef[] = [];+ for (const e of entities) {+ for (const comp of e.components) {+ const def = getComponent(comp.type);+ if (!def || def.entityFields.length === 0) continue;+ for (const field of def.entityFields) {+ const v = comp.data[field];+ if (typeof v === 'number' && v !== INVALID_ENTITY && !inSubtree.has(v)) {+ out.push({ entityId: e.id, componentType: comp.type, field, target: v });+ }+ }+ }+ }+ return out;+}+export function extractPrefab(entities: readonly ExtractEntity[],rootId: number,diff --git a/sdk/tests/scene-prefab.test.ts b/sdk/tests/scene-prefab.test.tsindex a053772b2..f355bef15 100644--- a/sdk/tests/scene-prefab.test.ts+++ b/sdk/tests/scene-prefab.test.ts@@ -15,7 +15,8 @@import { describe, it, expect, vi } from 'vitest';import { World } from '../src/world';import { createMockModule } from './mocks/wasm';-import { defineBuiltin } from '../src/component';+import { defineBuiltin, defineComponent } from '../src/component';+import { INVALID_ENTITY } from '../src/types';import {loadSceneData,loadSceneWithAssets,@@ -31,6 +32,7 @@ import {expandEntry,collapseEntry,extractPrefab,+ collectExternalEntityRefs,type PrefabData,type PrefabInstanceDelta,type PrefabInstanceEntry,@@ -287,6 +289,32 @@ describe('Prefab scene loading (PF1)', () => {expect(entities.find((e) => e.name === 'Barrel')!.parent).toBe(rootId);});+ // ── External entity refs: cleared on extract (never dangle), reportable. ──+ it('extractPrefab remaps in-subtree entity refs and clears external ones', () => {+ defineComponent('Chaser', { target: 0 }, { entityFields: ['target'] });+ const subtree: ExtractEntity[] = [+ // root chases the in-subtree child; child chases an external scene entity (99).+ { id: 10, name: 'Root', parent: null, children: [11], components: [{ type: 'Chaser', data: { target: 11 } }], visible: true },+ { id: 11, name: 'Child', parent: 10, children: [], components: [{ type: 'Chaser', data: { target: 99 } }], visible: true },+ ];+ const prefab = extractPrefab(subtree, 10, 'Squad', (() => { let n = 0; return () => String(n++); })());+ const root = prefab.entities.find((e) => e.name === 'Root')!;+ const child = prefab.entities.find((e) => e.name === 'Child')!;+ // In-subtree ref → the child's prefab-local id ('1'); external ref → cleared.+ expect(root.components[0].data.target).toBe('1');+ expect(child.components[0].data.target).toBe(INVALID_ENTITY);+ });++ it('collectExternalEntityRefs reports only out-of-subtree refs', () => {+ defineComponent('Chaser', { target: 0 }, { entityFields: ['target'] });+ const subtree: ExtractEntity[] = [+ { id: 10, name: 'Root', parent: null, children: [11], components: [{ type: 'Chaser', data: { target: 11 } }], visible: true },+ { id: 11, name: 'Child', parent: 10, children: [], components: [{ type: 'Chaser', data: { target: 99 } }], visible: true },+ ];+ const external = collectExternalEntityRefs(subtree);+ expect(external).toEqual([{ entityId: 11, componentType: 'Chaser', field: 'target', target: 99 }]);+ });+it('loadSceneData (sync) skips prefab entries without throwing', () => {createMockModule();const world = new World();