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): 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.ts
index 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.ts
index 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 Team
import { 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.md
index 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.md
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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();