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: 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.mdx
index 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 spawned
tree — `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:
```typescript
const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {
@@ -37,6 +40,46 @@ const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab',
## Per-instance overrides
Pass `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.mdx
index 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` 是新的根实体:
```typescript
import { 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 访问子项:
```typescript
const { 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 时加载。