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.

test(assets): five hot updates in a row leave one release owed

esengine4d7984962017
diff --git a/docs/astro/src/content/docs/publishing/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdx
index 21e3e5e84..1777b52ce 100644
--- a/docs/astro/src/content/docs/publishing/hot-update.mdx
+++ b/docs/astro/src/content/docs/publishing/hot-update.mdx
@@ -216,6 +216,12 @@ alike, as long as the field is declared in `assetFields`. The picture changes on
its own; the scene author writes nothing. (The `hot-update-demo` example's game
code is literally empty.)
+The replacement is acquired once **per scene that holds the asset**, and each
+scene is moved onto it as a unit — all of that scene's bindings or none. So
+unloading one scene never takes the updated texture away from another that is
+still drawing it, and a scene that unloads gives back exactly what it holds,
+however many updates it lived through.
+
For anything the built-in rebinder doesn't cover — a texture you bound manually, a
sound, a custom system — subscribe to `onInvalidate` and rebind yourself:
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
index 0df46e646..1e5c4f6b3 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
@@ -166,6 +166,8 @@ const checkForUpdates = defineSystem([Res(Assets)], (assets) => {
当场景以 `@uuid` 引用某个资产、而该资产位于远端组时,`applyUpdate` 会**全部搞定**——它下载新字节、切换清单,内建重绑器随即把旧贴图换进**每一个声明了该资产的运行中字段**:内建的(`Sprite.texture`、`MeshRenderer.texture` / `.normalMap`、`UIVisual.texture`、`TilemapLayer.tileset`、`ParticleEmitter.texture`、`TrailRenderer.texture`)与你自己的组件一视同仁,只要字段写在 `assetFields` 里。画面自行改变,场景作者什么都不用写。(`hot-update-demo` 示例的游戏代码字面上是空的。)
+替换品**按持有该资产的场景各获取一份**,每个场景整体迁移——要么它的绑定全换,要么一个都不换。因此卸载一个场景绝不会把更新后的贴图从另一个仍在绘制它的场景手里拿走;而一个场景卸载时交回的正是它持有的那些,无论中途经历过多少次更新。
+
对于内建重绑器覆盖不到的东西——你手动绑定的贴图、一段音效、一个自定义系统——订阅 `onInvalidate` 自行重绑:
```ts
diff --git a/sdk/tests/hot-update-rebind.test.ts b/sdk/tests/hot-update-rebind.test.ts
index 2d7c11e16..b129b2ea9 100644
--- a/sdk/tests/hot-update-rebind.test.ts
+++ b/sdk/tests/hot-update-rebind.test.ts
@@ -313,6 +313,30 @@ describe('a replacement is a transaction per owning scope', () => {
expect(assets.sizes().refRows).toBe(base);
});
+ it('five hot updates in a row leave the scene owing exactly one release', async () => {
+ // The measured leak: each successful rebind took a texture out of the
+ // ledger with no receipt, so five updates left five rows that no unload
+ // could ever reach. What a scene owes is one release, always.
+ const { app, assets, manager } = sceneApp();
+ const base = assets.sizes().refRows;
+ manager.register({
+ name: 'level',
+ setup: sceneHolding(app, assets, 'hero.png', [{ component: Sprite, field: 'texture' }]),
+ });
+ await manager.loadAdditive('level');
+
+ for (let i = 0; i < 5; i++) {
+ assets.invalidate('hero.png');
+ await settle(app);
+ expect(boundValues(app, Sprite, 'texture'), `after update ${i + 1}`)
+ .toEqual([assets.getTexture('hero.png')!.handle]);
+ expect(assets.sizes().refRows, `after update ${i + 1}`).toBe(base + 1);
+ }
+
+ await manager.unload('level');
+ expect(assets.sizes().refRows).toBe(base);
+ });
+
it('an entity no scene owns is the app\'s, not nobody\'s', async () => {
// The rebinder must not keep what it acquires, and an acquisition with
// no owner is one nobody can ever give back — the leak this had.