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(scenes): a persistent entity keeps what it draws with

esengine74a6c0fd5d15
diff --git a/docs/astro/src/content/docs/world/scenes.mdx b/docs/astro/src/content/docs/world/scenes.mdx
index f81037365..9b4f54d9e 100644
--- a/docs/astro/src/content/docs/world/scenes.mdx
+++ b/docs/astro/src/content/docs/world/scenes.mdx
@@ -115,18 +115,28 @@ would quietly stop rendering. Pass `keepPersistent: false` to `switchTo` or
`unload` to tear down everything anyway, persistent entities included — the
clean slate you want when returning to a main menu.
+What it **keeps**: the assets it is bound to. Promotion splits the scene's
+reference rather than transferring or dropping it, so a surviving entity owns
+what it draws with — the exact instance it is bound to, even when a hot update
+has since replaced the file — and gives it back when the entity is despawned,
+including as part of a parent's subtree. It also keeps its place: an entity
+detached from a parent that did not survive stays where it was on screen
+rather than jumping to its parent-relative position.
+
Two things do **not** come along with it:
- **The scene's systems.** Every system a scene declares is unregistered on
unload, so a persistent entity's behavior has to come from a system
registered on the `App` itself, not from the scene's `systems` list.
-- **The scene's asset references.** Unload releases the refs the scene took on
- every texture, material, font, audio clip, anim clip, tilemap and timeline it
- declared — persistence doesn't exempt them. If that was the last reference,
- the asset is freed (at best it lingers as an evictable cache entry that the
- next load revives), even though the surviving entity still draws with it.
- Take a reference that outlives the scene instead: `Assets.preload` at
- bootstrap, or an additive scene that is never unloaded.
+- **Assets a component names by reference** rather than by a runtime handle —
+ an anim clip, for instance. Those are still released with the scene, so take
+ a reference that outlives it: `Assets.preload` at bootstrap, or an additive
+ scene that is never unloaded. Textures, materials, fonts, meshes and
+ environments are handle-bound and come along.
+- **Its non-persistent children.** "This entity persists" is about the entity,
+ not its subtree: children that were not themselves marked are despawned with
+ the scene, and a persistent child of a non-persistent parent is detached and
+ survives on its own.
<Aside type="caution">
There is no Inspector checkbox for this. `SceneOwner` is an engine-internal
diff --git a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx
index 9a18654ab..d541c6ac0 100644
--- a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx
@@ -99,14 +99,20 @@ const keepPlayer = defineSystem([Res(SceneManager)], (scenes) => {
一个持久化的相机会就此悄悄停止渲染。给 `switchTo` 或 `unload` 传 `keepPersistent: false`
可以连持久化实体一起拆掉——回主菜单时你要的正是这种干净状态。
+它**会带走**的是:自己绑定的资源。提升会把场景的那份引用**分裂**出一份,而不是转移或丢弃,
+所以活下来的实体拥有自己正在绘制的东西——就是它当前绑定的那一个实例,哪怕文件后来被热更替换
+过——并在实体销毁时(包括作为父节点子树的一部分被销毁)交回。它也会留在原地:被一个没能存活
+的父节点摘下来的实体,停在它原本所在的位置,而不会跳到「相对父节点」的那个坐标上。
+
有两样东西**不会**跟着走:
- **场景的系统**。场景声明的每个系统都会在卸载时注销,所以持久化实体的行为必须来自注册在
`App` 上的系统,而不是场景 `systems` 列表里的。
-- **场景的资源引用**。卸载会释放场景声明的每一份纹理、材质、字体、音频、动画剪辑、瓦片地图
- 和时间轴的引用——持久化并不豁免它们。如果那是最后一份引用,资源就被释放了(好一点的情况是
- 留成一个可驱逐的缓存条目、等下次加载复活),哪怕活下来的实体还在用它绘制。要拿一份比场景
- 活得更久的引用:在引导时 `Assets.preload`,或者用一个永不卸载的叠加场景。
+- **组件按「引用」而非运行时句柄命名的资源**(例如动画剪辑)。它们仍随场景一起释放,所以要
+ 拿一份比场景活得更久的引用:在引导时 `Assets.preload`,或者用一个永不卸载的叠加场景。
+ 纹理、材质、字体、网格与环境是按句柄绑定的,会跟着走。
+- **它那些没有被标记的子节点**。「这个实体持久化」说的是这个实体,不是它的子树:没有自己被
+ 标记的子节点会随场景销毁;而一个持久化的子节点若父节点不持久,会被摘下来单独存活。
<Aside type="caution">
Inspector 里没有这个勾选项。`SceneOwner` 是引擎内部组件,被刻意排除在项目组件 schema