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: add Prefabs guide (Res(Prefabs).instantiate)
yhh6935e6052d4d
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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` 可以**只为这个实例**改组件值,而不修改预制体资源——例如用同一个敌人+预制体生成不同血量或不同着色的实例。预制体仍是单一权威来源,每个实例只是在它之上叠加+自己的值。