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(assets): explain ownership of hot-reloaded entity resources

yhha5fd0feaf9af
diff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdx
index cdf23b375..5a2d2335d 100644
--- a/docs/astro/src/content/docs/assets/overview.mdx
+++ b/docs/astro/src/content/docs/assets/overview.mdx
@@ -235,6 +235,12 @@ reference and needs a matching `release*()` (scene loading does both for you).
An asset shared by two scenes survives the first scene's unload and is freed
only when its last holder releases it.
+Hot-reloaded bindings follow the same ownership rule. A scene owns replacement
+resources for its entities; a runtime entity without a scene, or a persistent
+entity that outlived its scene, owns its replacements until it despawns. Repeated
+reloads do not keep those resources alive for the rest of the application.
+Your own explicit `load*()` or `acquire*()` calls still need matching releases.
+
A released asset isn't destroyed immediately, either. Textures and decoded
audio buffers stay resident as **evictable cache entries**, and if the same
asset is loaded again (re-entering a scene, streaming an area back in) it is
diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
index 6e7850def..b23a0aaf2 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
@@ -204,6 +204,11 @@ const { failed } = await assets.preload(
(场景加载会替你完成这两步)。被两个场景共享的资源在第一个场景卸载后仍然存活,只有最后一个
持有者释放时才真正释放。
+热重载后的资源绑定也遵循同一归属规则:场景负责其实体使用的替换资源;没有场景归属的运行时
+实体,以及在原场景卸载后继续存在的持久实体,会持有自己的替换资源,并在实体销毁时释放。
+反复热重载不会让这些资源一直占用到应用退出。游戏代码自己显式调用的 `load*()` 或
+`acquire*()` 仍需要对应的释放操作。
+
释放的资源也不会立即销毁:纹理和解码后的音频缓冲区以**可逐出缓存条目**的形式留驻,同一资源
再次被加载(重进场景、流式加载重新进入某区域)时会被**原地复活**,而不是重新下载和解码。
一个按字节预算的 LRU 在驻留量超过预算时逐出最旧的未引用条目;收到系统内存警告时整个热缓存