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 Scenes guide to the complete-reference template

yhh64f257018515
diff --git a/docs/astro/src/content/docs/guides/scene.mdx b/docs/astro/src/content/docs/guides/scene.mdx
index fd137a917..d85643382 100644
--- a/docs/astro/src/content/docs/guides/scene.mdx
+++ b/docs/astro/src/content/docs/guides/scene.mdx
@@ -1,13 +1,13 @@
---
title: Scenes
-description: Load, switch, and stack scenes with Res(SceneManager).
+description: The complete guide to scenes — switching, additive loading, querying state, and how systems are gated per scene, via Res(SceneManager).
---
import { Aside } from '@astrojs/starlight/components';
A project is organized into scenes. They all share one ECS world; the
-`SceneManager` resource loads, switches, and unloads them, and gates each
-scene's systems to run only while it's active.
+`SceneManager` resource loads, switches, and unloads them, and gates each scene's
+systems to run only while that scene is active.
## Switch scenes
@@ -24,25 +24,48 @@ const goToLevel2 = defineSystem([Res(SceneManager)], async (scenes) => {
## Additive scenes
-Load a scene **on top** of the current one — a HUD, a pause menu, a streamed
-region — without unloading what's underneath:
+Load a scene **on top** of the current one — a HUD, a pause menu, a streamed region
+— without unloading what's underneath. `loadAdditive` takes an optional progress
+callback and returns the scene context:
```typescript
-await scenes.loadAdditive('pause-menu');
+await scenes.loadAdditive('pause-menu', (loaded, total) => { /* progress */ });
// …later
await scenes.unload('pause-menu');
```
-## Query scene state
+## `SceneManager` reference
-- `scenes.getActive()` — the active scene name; `scenes.getActiveScenes()` for
- all active (additive) scenes.
-- `scenes.isLoaded(name)`, `scenes.isActive(name)`.
-- `scenes.isTransitioning()` — true during a `switchTo` transition.
+| Method | Description |
+|---|---|
+| `switchTo(name, options?)` | Replace the active scene (async; optional transition). |
+| `loadAdditive(name, onProgress?)` | Load a scene on top; returns its context (async). |
+| `unload(name, options?)` | Unload a scene (async; optional transition). |
+| `getActive()` | The active scene name, or `null`. |
+| `getActiveScenes()` | All active (additive) scene names. |
+| `isLoaded(name)` | Whether a scene is loaded. |
+| `isActive(name)` | Whether a scene is active. |
+| `isTransitioning()` | `true` during a `switchTo` transition. |
+
+## Best practices
+
+- **`await` scene calls** — they're async; a switch that isn't awaited races with the
+ rest of your frame.
+- **Additive for overlays** (HUD, pause, dialogs) so gameplay stays loaded underneath.
+- **Gate logic with systems, not flags** — systems declared in a scene only run while
+ it's active, so an additive HUD and the gameplay scene update independently.
+- **Tag long-lived entities** deliberately: because scenes share one world, an
+ untagged entity can outlive a scene switch.
+- **Persist across scenes with [saves](/docs/guides/save/)**, not by leaking entities.
<Aside type="note">
- Because scenes share one world, an entity can outlive a scene switch if you
- don't tag it to the scene. Systems declared in a scene only run while that
- scene is active, so an additive HUD scene and the gameplay scene update
- independently.
+ Scenes share one world, so a scene switch doesn't wipe the world — the manager
+ loads/unloads each scene's entities and gates its systems. Entities you want to
+ survive a switch must be owned outside the scene.
</Aside>
+
+## See also
+
+- [Prefabs](/docs/guides/prefab/) — spawn reusable entity trees within a scene.
+- [Saving & Loading](/docs/guides/save/) — persist state across scene switches.
+- [Assets](/docs/guides/assets/) — scenes are cook entry points.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx b/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
index 6cd5a24ae..67a512ba9 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/scene.mdx
@@ -1,16 +1,16 @@
---
title: 场景
-description: 用 Res(SceneManager) 加载、切换和叠加场景。
+description: 场景的完整指南——切换、叠加加载、查询状态,以及系统如何按场景门控,通过 Res(SceneManager)。
---
import { Aside } from '@astrojs/starlight/components';
-一个项目由若干场景组成。它们共享同一个 ECS 世界;`SceneManager` 资源负责加载、切换、
-卸载它们,并把每个场景的系统限制为只在该场景激活时运行。
+项目由场景组织。它们共享同一个 ECS 世界;`SceneManager` 资源加载、切换和卸载它们,并门控
+每个场景的系统,使其只在该场景活动时运行。
## 切换场景
-`switchTo` 会替换当前活动场景(可带过渡)。它是异步的——用 `await`:
+`switchTo` 替换活动场景(可带过渡)。它是异步的——`await` 它:
```typescript
import { defineSystem, Res, SceneManager } from 'esengine';
@@ -22,22 +22,44 @@ const goToLevel2 = defineSystem([Res(SceneManager)], async (scenes) => {
## 叠加场景
-把一个场景加载到当前场景**之上**——HUD、暂停菜单、流式加载的区域——而不卸载下面的:
+把一个场景加载到当前场景**之上**——HUD、暂停菜单、流式区域——而不卸载下面的内容。
+`loadAdditive` 接受一个可选的进度回调,并返回场景上下文:
```typescript
-await scenes.loadAdditive('pause-menu');
-// ……稍后
+await scenes.loadAdditive('pause-menu', (loaded, total) => { /* progress */ });
+// …later
await scenes.unload('pause-menu');
```
-## 查询场景状态
+## `SceneManager` 参考
-- `scenes.getActive()` —— 活动场景名;`scenes.getActiveScenes()` 返回所有活动
- (叠加)场景。
-- `scenes.isLoaded(name)`、`scenes.isActive(name)`。
-- `scenes.isTransitioning()` —— `switchTo` 过渡期间为 true。
+| 方法 | 说明 |
+|---|---|
+| `switchTo(name, options?)` | 替换活动场景(异步;可选过渡)。 |
+| `loadAdditive(name, onProgress?)` | 在顶部加载一个场景;返回其上下文(异步)。 |
+| `unload(name, options?)` | 卸载一个场景(异步;可选过渡)。 |
+| `getActive()` | 活动场景名,或 `null`。 |
+| `getActiveScenes()` | 所有活动(叠加)场景名。 |
+| `isLoaded(name)` | 场景是否已加载。 |
+| `isActive(name)` | 场景是否活动。 |
+| `isTransitioning()` | `switchTo` 过渡期间为 `true`。 |
+
+## 最佳实践
+
+- **`await` 场景调用**——它们是异步的;未 await 的切换会与本帧其余逻辑竞态。
+- 浮层(HUD、暂停、对话框)**用叠加**,让玩法留在下面。
+- **用系统而非标志门控逻辑**——场景里声明的系统只在它活动时运行,所以叠加 HUD 与玩法场景
+ 独立更新。
+- **有意地给长生命实体打标签**:因为场景共享一个世界,未打标签的实体可能在切换后存活。
+- **跨场景持久化用[存档](/docs/zh-cn/guides/save/)**,而不是泄漏实体。
<Aside type="note">
- 由于场景共享同一个世界,如果你不把实体标记到场景上,它可能在场景切换后仍然存在。
- 场景里声明的系统只在该场景激活时运行,所以叠加的 HUD 场景和游戏场景各自独立更新。
+ 场景共享一个世界,所以切换场景不会清空世界——管理器加载/卸载每个场景的实体并门控它的系统。
+ 想跨切换存活的实体必须归属在场景之外。
</Aside>
+
+## 参见
+
+- [预制体](/docs/zh-cn/guides/prefab/) —— 在场景内生成可复用的实体树。
+- [存档与读档](/docs/zh-cn/guides/save/) —— 跨场景切换持久化状态。
+- [资源](/docs/zh-cn/guides/assets/) —— 场景是 cook 入口点。