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: add Prefabs guide (Res(Prefabs).instantiate)

yhh6935e6052d4d
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index ccc4e9de4..7a4e016a0 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -71,6 +71,7 @@ export default defineConfig({
translations: { 'zh-CN': '内容与流程' },
items: [
{ label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'guides/assets' },
+ { label: 'Prefabs', translations: { 'zh-CN': '预制体' }, slug: 'guides/prefab' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
{ label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdx
new file mode 100644
index 000000000..12684987b
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/prefab.mdx
@@ -0,0 +1,42 @@
+---
+title: Prefabs
+description: Save an entity tree as a template and spawn instances at runtime.
+---
+
+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.
+
+## Spawn a prefab
+
+`instantiate` loads the prefab and spawns it. It's async, and returns the spawned
+tree — `root` is the new root entity:
+
+```typescript
+import { defineSystem, Res, Prefabs } from 'esengine';
+
+const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {
+ const { root } = await prefabs.instantiate('prefabs/enemy.esprefab');
+ // `root` is the new entity — move it, tag it, give it a Transform position…
+});
+```
+
+## Parent it and reach its children
+
+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', {
+ parent: mountPointEntity,
+});
+// root → the instance root
+// entities → Map<prefab-local id, spawned Entity>, for reaching children
+```
+
+## 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.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
new file mode 100644
index 000000000..fb1c9979b
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
@@ -0,0 +1,38 @@
+---
+title: 预制体
+description: 把实体树存成模板,并在运行时生成实例。
+---
+
+预制体是一棵存下来的实体树——你在编辑器里编排一次,然后多次生成(敌人、拾取物、
+子弹)。运行时通过 `Prefabs` 资源实例化它。
+
+## 生成一个预制体
+
+`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 位置……
+});
+```
+
+## 挂到父级并访问子实体
+
+把实例嵌套到另一个实体下,并用返回的 `entities` map 按预制体内的本地 id 访问子实体:
+
+```typescript
+const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {
+ parent: mountPointEntity,
+});
+// root → 实例根
+// entities → Map<预制体本地 id, 生成的 Entity>,用于访问子实体
+```
+
+## 逐实例覆盖(override)
+
+传入 `overrides` 可以**只为这个实例**改组件值,而不修改预制体资源——例如用同一个敌人
+预制体生成不同血量或不同着色的实例。预制体仍是单一权威来源,每个实例只是在它之上叠加
+自己的值。