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: rewrite the Prefabs guide to the complete-reference template
yhh5b15c4a2c288
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdxindex 12684987b..3df4194c2 100644--- a/docs/astro/src/content/docs/guides/prefab.mdx+++ b/docs/astro/src/content/docs/guides/prefab.mdx@@ -1,15 +1,18 @@---title: Prefabs-description: Save an entity tree as a template and spawn instances at runtime.+description: The complete guide to prefabs — instantiating entity-tree templates, parenting, reaching children, and per-instance overrides via Res(Prefabs).----A prefab is a saved entity tree — a template you author once in the editor and-spawn many times (enemies, pickups, bullets). Instantiate one at runtime through-the `Prefabs` resource.+import { Aside } from '@astrojs/starlight/components';++A prefab is a saved entity tree — a template you author once in the editor and spawn+many times (enemies, pickups, bullets). Instantiate one at runtime through the+`Prefabs` resource. The prefab asset stays the single source of truth; instances can+layer their own values on top.## Spawn a prefab-`instantiate` loads the prefab and spawns it. It's async, and returns the spawned+`instantiate` loads the prefab and spawns it. It's async and returns the spawnedtree — `root` is the new root entity:```typescript@@ -21,10 +24,10 @@ const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {});```-## Parent it and reach its children+## Parent it & reach its children-Nest the instance under another entity, and use the returned `entities` map to-reach children by their prefab-local id:+Nest the instance under another entity, and use the returned `entities` map to reach+children by their prefab-local id:```typescriptconst { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {@@ -37,6 +40,46 @@ const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab',## Per-instance overridesPass `overrides` to change component values for **this instance only** without-editing the prefab asset — for example, spawn the same enemy prefab with-different health or tint. The prefab stays the single source of truth; each-instance just layers its own values on top.+editing the prefab asset — spawn the same enemy with different health or tint:++```typescript+const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {+ overrides: [+ { entity: 0, component: 'Health', field: 'value', value: 250 },+ ],+});+```++## `instantiate` reference++| Option | Type | Description |+|---|---|---|+| `parent` | Entity | Nest the instance under this entity. |+| `overrides` | override[] | Per-instance component-value changes. |+| `baseUrl` | string | Base URL for resolving the prefab's assets. |++| Result field | Description |+|---|---|+| `root` | The instance's root `Entity`. |+| `entities` | `Map<prefab-local id, Entity>` for reaching children. |++## Best practices++- **One prefab, many instances** — keep shared data in the prefab and vary instances+ with `overrides`, so a design change updates every instance.+- **Reach children via the `entities` map**, not by walking the hierarchy by index.+- **Parent at spawn** (`parent`) rather than re-parenting after, so transforms resolve+ correctly on the first frame.+- **Apply-to-prefab** in the editor to push an instance's tweaks back to the source+ when a change should be global.++<Aside type="tip">+ Prefabs nest: a prefab can contain instances of other prefabs, and overrides layer+ through the nesting. Instantiate is async because it may load the prefab asset (and+ its dependencies) on first use.+</Aside>++## See also++- [Scenes](/docs/guides/scene/) — scenes are where prefab instances live.+- [Assets](/docs/guides/assets/) — prefabs are assets, loaded on first instantiate.diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdxindex fb1c9979b..00acc341d 100644--- a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx@@ -1,38 +1,78 @@---title: 预制体-description: 把实体树存成模板,并在运行时生成实例。+description: 预制体的完整指南——实例化实体树模板、设置父级、访问子项,以及逐实例覆盖,通过 Res(Prefabs)。----预制体是一棵存下来的实体树——你在编辑器里编排一次,然后多次生成(敌人、拾取物、-子弹)。运行时通过 `Prefabs` 资源实例化它。+import { Aside } from '@astrojs/starlight/components';++预制体是一棵存好的实体树——你在编辑器里编辑一次、生成很多次的模板(敌人、拾取物、子弹)。+在运行时通过 `Prefabs` 资源实例化。预制体资源始终是单一权威来源;实例可以在其之上叠加+自己的值。## 生成一个预制体-`instantiate` 加载预制体并生成它。它是异步的,返回生成的树——`root` 是新的根实体:+`instantiate` 加载预制体并生成它。它是异步的,并返回生成的树——`root` 是新的根实体:```typescriptimport { defineSystem, Res, Prefabs } from 'esengine';const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {const { root } = await prefabs.instantiate('prefabs/enemy.esprefab');- // `root` 是新实体——移动它、打标记、设置 Transform 位置……+ // `root` is the new entity — move it, tag it, give it a Transform position…});```-## 挂到父级并访问子实体+## 设置父级并访问子项-把实例嵌套到另一个实体下,并用返回的 `entities` map 按预制体内的本地 id 访问子实体:+把实例嵌套到另一个实体下,并用返回的 `entities` map 按预制体局部 id 访问子项:```typescriptconst { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {parent: mountPointEntity,});-// root → 实例根-// entities → Map<预制体本地 id, 生成的 Entity>,用于访问子实体+// root → the instance root+// entities → Map<prefab-local id, spawned Entity>, for reaching children```-## 逐实例覆盖(override)+## 逐实例覆盖-传入 `overrides` 可以**只为这个实例**改组件值,而不修改预制体资源——例如用同一个敌人-预制体生成不同血量或不同着色的实例。预制体仍是单一权威来源,每个实例只是在它之上叠加-自己的值。+传 `overrides` 来**仅为这个实例**改组件值,而不编辑预制体资源——用不同血量或着色生成同一个敌人:++```typescript+const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {+ overrides: [+ { entity: 0, component: 'Health', field: 'value', value: 250 },+ ],+});+```++## `instantiate` 参考++| 选项 | 类型 | 说明 |+|---|---|---|+| `parent` | Entity | 把实例嵌套到该实体下。 |+| `overrides` | override[] | 逐实例的组件值改动。 |+| `baseUrl` | string | 解析预制体资源的基 URL。 |++| 结果字段 | 说明 |+|---|---|+| `root` | 实例的根 `Entity`。 |+| `entities` | `Map<prefab-local id, Entity>`,用于访问子项。 |++## 最佳实践++- **一个预制体,多个实例**——共享数据放在预制体里,用 `overrides` 区分实例,这样一次设计+ 改动就更新所有实例。+- **通过 `entities` map 访问子项**,而不是按索引遍历层级。+- **在生成时设父级**(`parent`),而非事后重设父级,让变换在第一帧就正确解析。+- 当某个改动应当全局时,在编辑器里用 **apply-to-prefab** 把实例的调整推回源。++<Aside type="tip">+ 预制体可嵌套:一个预制体可以包含其它预制体的实例,覆盖会穿过嵌套层层叠加。instantiate 是+ 异步的,因为首次使用时它可能加载预制体资源(及其依赖)。+</Aside>++## 参见++- [场景](/docs/zh-cn/guides/scene/) —— 预制体实例存在于场景中。+- [资源](/docs/zh-cn/guides/assets/) —— 预制体是资源,首次 instantiate 时加载。