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.

docs(prefab): the sample code still taught the id that matches nothing

esengine599c0889116f
diff --git a/docs/astro/src/content/docs/world/prefabs.mdx b/docs/astro/src/content/docs/world/prefabs.mdx
index 7002e69d1..7b2912e9b 100644
--- a/docs/astro/src/content/docs/world/prefabs.mdx
+++ b/docs/astro/src/content/docs/world/prefabs.mdx
@@ -125,18 +125,30 @@ const { root, entities } = await prefabs.instantiate('assets/prefabs/turret.espr
## Per-instance overrides
Pass `overrides` to change a value for **this instance only** without editing the
-prefab asset — spawn the same enemy with different health or tint. Each override
-targets a prefab entity by its **string** `prefabEntityId` (a UUID for
-editor-authored prefabs) and names the component + property:
+prefab asset — spawn the same enemy with different health or tint. An override
+names the component + property, and aims at the prefab's **root** unless you say
+otherwise:
```typescript
const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {
overrides: [
- { prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
+ { type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
});
```
+To reach a **child**, add its `prefabEntityId` — the entity's own **string** id,
+a UUID for editor-authored prefabs. Read it from the `.esprefab`, or from the
+`entities` map a previous instantiate returned.
+
+:::caution[`prefabEntityId: '0'` no longer matches anything]
+`'0'` is the id every prefab had before stable ids, and it appears in older
+sample code. A prefab saved by the editor since has a UUID instead, so an
+override carrying `'0'` aims at nobody. It now **throws**, naming the root and
+the ids that do exist — before, it was dropped in silence, and the only symptom
+was every instance appearing at the position the prefab was authored with.
+:::
+
Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'`,
`'component_replaced'`, `'component_removed'`, `'metadata_set'`, or `'metadata_removed'`
(the metadata forms use `metadataKey` in place of `componentType`/`propertyName`).
diff --git a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx
index 3c799aca0..dec76a55e 100644
--- a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx
@@ -106,17 +106,26 @@ const { root, entities } = await prefabs.instantiate('assets/prefabs/turret.espr
## 逐实例覆盖
传 `overrides` 来**仅为这个实例**改值,而不编辑预制体资源——用不同血量或着色生成同一个敌人。
-每条覆盖用**字符串** `prefabEntityId`(编辑器创作的预制体里是 UUID)定位一个预制体实体,并指明
-组件 + 属性:
+一条覆盖指明组件 + 属性,不另外说明的话就作用在预制体的**根实体**上:
```typescript
const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {
overrides: [
- { prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
+ { type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
});
```
+要作用到**子实体**,补上它的 `prefabEntityId`——即那个实体自己的**字符串** id,
+编辑器创作的预制体里是 UUID。可以从 `.esprefab` 里读,也可以从上一次 instantiate
+返回的 `entities` 映射里取。
+
+:::caution[`prefabEntityId: '0'` 已经匹配不到任何东西]
+`'0'` 是稳定 id 之前所有预制体的 id,旧的示例代码里还留着它。此后由编辑器保存的预制体
+拿到的是 UUID,所以带 `'0'` 的覆盖谁也指不到。现在它会**抛错**,并列出根实体和实际存在的
+id——在此之前它是被静默丢弃的,唯一的症状就是每个实例都出现在预制体被创作时的那个位置。
+:::
+
除了 `'property'`,`type` 还可以是 `'name'`、`'visibility'`、`'component_added'`、
`'component_replaced'`、`'component_removed'`、`'metadata_set'` 或 `'metadata_removed'`
(metadata 两种用 `metadataKey` 代替 `componentType`/`propertyName`)。
diff --git a/examples/space-shooter/src/resources.ts b/examples/space-shooter/src/resources.ts
index ffd9722f9..34640ca53 100644
--- a/examples/space-shooter/src/resources.ts
+++ b/examples/space-shooter/src/resources.ts
@@ -1,4 +1,4 @@
-import { defineResource, type PrefabOverride } from 'esengine';
+import { defineResource, type SpawnOverride } from 'esengine';
export const HALF_HEIGHT = 540;
export const HALF_WIDTH = 300;
@@ -28,9 +28,12 @@ export const PREFAB_ENEMY_BULLET = 'assets/prefabs/EnemyBullet.esprefab';
export const PREFAB_EXPLOSION = 'assets/prefabs/Explosion.esprefab';
export const PREFAB_STAR = 'assets/prefabs/Star.esprefab';
-export function positionOverride(x: number, y: number): PrefabOverride {
+// These prefabs are one entity each, so neither helper names a `prefabEntityId`:
+// left out, an override aims at the prefab's root. Naming one is for reaching a
+// CHILD, and the id to use is that entity's own — not `'0'`, which is what prefabs
+// had before stable ids and now matches nothing.
+export function positionOverride(x: number, y: number): SpawnOverride {
return {
- prefabEntityId: '0',
type: 'property',
componentType: 'Transform',
propertyName: 'position',
@@ -38,9 +41,8 @@ export function positionOverride(x: number, y: number): PrefabOverride {
};
}
-export function propOverride(componentType: string, propertyName: string, value: unknown): PrefabOverride {
+export function propOverride(componentType: string, propertyName: string, value: unknown): SpawnOverride {
return {
- prefabEntityId: '0',
type: 'property',
componentType,
propertyName,