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
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.mdxindex 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 overridesPass `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:```typescriptconst { 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.mdxindex 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)定位一个预制体实体,并指明-组件 + 属性:+一条覆盖指明组件 + 属性,不另外说明的话就作用在预制体的**根实体**上:```typescriptconst { 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.tsindex 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,