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.

feat(examples): interactive hot-update center for hot-update-demo

yhhb4e4ee1f1853
diff --git a/examples/hot-update-demo/.esengine/asset-groups.json b/examples/hot-update-demo/.esengine/asset-groups.json
index 4420ab104..e408299f6 100644
--- a/examples/hot-update-demo/.esengine/asset-groups.json
+++ b/examples/hot-update-demo/.esengine/asset-groups.json
@@ -1,11 +1,22 @@
{
"version": "1.0",
"groups": {
- "cdn": { "folder": "assets/cdn", "mode": "remote" }
+ "cdn": {
+ "folder": "assets/cdn",
+ "mode": "remote"
+ },
+ "pack": {
+ "folder": "assets/pack",
+ "mode": "remote"
+ }
},
"activeProfile": "dev",
"profiles": {
- "dev": { "remoteRoot": "" },
- "prod": { "remoteRoot": "https://cdn.example.com/hot-update-demo" }
+ "dev": {
+ "remoteRoot": ""
+ },
+ "prod": {
+ "remoteRoot": "https://cdn.example.com/hot-update-demo"
+ }
}
}
diff --git a/examples/hot-update-demo/README.md b/examples/hot-update-demo/README.md
index 7d98ae280..c9a2c0f7f 100644
--- a/examples/hot-update-demo/README.md
+++ b/examples/hot-update-demo/README.md
@@ -1,67 +1,105 @@
# Hot Update Demo
-Ship a game, then change its art **on a CDN** and have running clients pick up the
-new bytes — no re-download of the package, no store re-submission. This example
-shows the whole loop on a single sprite.
+Ship a game, then change its content **on a CDN** and have running clients pick up
+the new bytes — no re-download of the package, no store re-submission. This example
+turns that whole loop into an interactive **hot-update center**: a status line, a
+plan summary, a real download **progress bar**, and two buttons, all built from the
+engine's own UI widgets driving the engine's own `Assets` hot-update API.
-## How it works
+The screen has three parts, all authored in `assets/scenes/main.esscene`:
-Estella assets are **content-addressed**: a cooked asset ships as
-`<contentHash>.<ext>`, an immutable, permanently-cacheable URL. Change a byte →
-new hash → new URL. A hot update is therefore just: *fetch the new manifest,
-diff it, download the assets whose hash changed, swap the active manifest.*
-Nothing is ever overwritten, so a cache can never go stale.
-
-### The pieces
-
-- **`assets/cdn/art.png`** — a texture assigned to a **`remote` group** by the
- project's delivery config, so it's delivered from a CDN (bundle mode `remote`),
- not baked into the package.
-- **`.esengine/asset-groups.json`** — the delivery config. `assets/cdn` is an
- ordinarily-named folder; the config is what marks it a remote group, and build
- profiles (`dev` / `prod`) carry the CDN root per environment:
- ```json
- {
- "groups": { "cdn": { "folder": "assets/cdn", "mode": "remote" } },
- "activeProfile": "dev",
- "profiles": { "dev": { "remoteRoot": "" }, "prod": { "remoteRoot": "https://cdn.example.com/hot-update-demo" } }
- }
- ```
- (The legacy `remote/<name>/` / `subpackages/<name>/` folder names still work as a
- zero-config default when there is no `asset-groups.json`.)
-- **`assets/scenes/main.esscene`** — the Display sprite references the texture by
- an ordinary `@uuid`. The asset lives in a `remote` group, so the runtime routes
- that `@uuid` to the CDN automatically — the scene author does nothing special.
-- **No game code.** `src/main.ts` is empty. When an update is applied the runtime's
- built-in rebinder reloads the changed asset (now resolved to the CDN) and swaps
- it into the live sprite, so the picture changes on screen on its own. (A game can
- still call `Assets.loadGroup(name)` to pull a whole remote group on demand — the
- DLC pattern — or `Assets.onInvalidate` for custom rebinding.)
-- **The update** — call `Assets.checkForUpdate({ manifestUrl, remoteRoot })` to
- diff the CDN's manifest against the running one, then `Assets.applyUpdate()` to
- download the changed assets and swap the manifest. Existing handles bound to a
- changed asset are told to rebind. `Assets.restorePersistedUpdate(key)` at boot
- makes a returning player start on the already-updated content, even offline.
+- a full-screen **remote content** sprite (green) — a `remote`-group texture the
+ hot update swaps;
+- a **DLC tile strip** — six placeholders you fill on demand;
+- an **update console** — status, plan, progress bar, and the `下载资源包` /
+ `检查更新` buttons.
+
+`src/` is behavior only: `systems/build.ts` resolves the scene widgets and wires
+the buttons to the API; `systems/update.ts` mirrors state onto the widgets each
+frame. The layout lives in the scene — the code never builds UI.
+
+## The two flows
+
+### 1. On-demand download (the DLC pattern) — watch it download
+
+`assets/pack/` is a `remote` group the scene does **not** reference, so nothing
+loads it at boot. Press **下载资源包** and the game calls:
```ts
-const plan = await assets.checkForUpdate({
- manifestUrl: 'https://cdn.example.com/asset-manifest.json',
- remoteRoot: 'https://cdn.example.com',
+await assets.loadGroup('pack', (loaded, total) => {
+ progress.setValue(loaded / total); // real per-file progress
});
-if (plan.hasUpdate) await assets.applyUpdate();
```
-The whole path is content-addressed and platform-uniform: the same
-`asset-manifest.json` + `loadGroup` + hot-update work on web, desktop, and
-mini-games.
+The progress bar fills as the six tiles arrive, then each is bound into its slot:
+
+```ts
+const tex = await assets.loadTexture('assets/pack/tile0.png'); // path ref, resolved via the group
+tile.texture = tex.handle;
+```
+
+This flow is fully interactive in editor Play — click Play, press the button, and
+watch the bar fill and the tiles reveal.
+
+### 2. Content hot-update — swap shipped content
+
+Press **检查更新** and the game diffs a candidate manifest against the running one:
+
+```ts
+const plan = await assets.checkForUpdate({ manifestUrl, remoteRoot });
+// plan.changedAssets, plan.totalBytes, plan.fromRevision → plan.toRevision
+if (plan.hasUpdate) {
+ const result = await assets.applyUpdate((loaded, total) => {
+ progress.setValue(loaded / total); // download + integrity-verify progress
+ });
+ // result.ok → the remote sprite hot-swaps on screen (built-in rebinder);
+ // on any failure NOTHING is applied — the update rolls back atomically.
+}
+```
+
+`manifestUrl` / `remoteRoot` come from `window.__estellaHotUpdate` if a host sets
+it; otherwise the demo probes a same-origin `asset-manifest.json`. In editor Play
+there is no newer build to fetch, so the console honestly reports **已是最新版本** —
+the real swap is exercised by the render verify below (and in a shipped build
+pointed at a CDN that has newer content).
+
+## How it works — content addressing
+
+Estella assets are **content-addressed**: a cooked asset ships as
+`<contentHash>.<ext>`, an immutable, permanently-cacheable URL. Change a byte →
+new hash → new URL. A hot update is therefore just: *fetch the new manifest, diff
+it by `contentHash`, download the assets whose hash changed, swap the active
+manifest.* Nothing is ever overwritten, so a cache can never go stale, and
+`applyUpdate` verifies every downloaded file's hash before committing.
+
+The delivery config is `.esengine/asset-groups.json`: `assets/cdn` and
+`assets/pack` are ordinarily-named folders the config marks as `remote` groups,
+and build profiles (`dev` / `prod`) carry the CDN root per environment:
+
+```json
+{
+ "groups": {
+ "cdn": { "folder": "assets/cdn", "mode": "remote" },
+ "pack": { "folder": "assets/pack", "mode": "remote" }
+ },
+ "activeProfile": "dev",
+ "profiles": { "dev": { "remoteRoot": "" }, "prod": { "remoteRoot": "https://cdn.example.com/hot-update-demo" } }
+}
+```
+
+The scene references the `cdn` texture by an ordinary `@uuid`; because it lives in
+a `remote` group the runtime routes it to the CDN automatically, and the built-in
+rebinder swaps the live sprite when an update is applied — the swap needs zero
+game code. The whole path is platform-uniform: the same manifest + `loadGroup` +
+hot-update work on web, desktop, and mini-games.
## Verify it
-The engine ships an automated render check that proves the loop end-to-end —
-cooks the game (green art), cooks a CDN update (red art), boots the shipped
-runtime, asserts it draws **green**, drives the update, and asserts it draws
-**red**:
+The engine ships an automated render check that proves the content-swap loop
+end-to-end — cooks the game (green art), cooks a CDN update (red art), boots the
+shipped runtime, asserts it draws **green**, drives the update, and asserts it
+draws **red**:
```
-pnpm --filter @estella/editor verify:render:hotupdate
+cd desktop && npm run verify:render:hotupdate
```
diff --git a/examples/hot-update-demo/assets/pack/tile0.png b/examples/hot-update-demo/assets/pack/tile0.png
new file mode 100644
index 000000000..904587dbc
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile0.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile0.png.meta b/examples/hot-update-demo/assets/pack/tile0.png.meta
new file mode 100644
index 000000000..f2c3aa8d4
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile0.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000000",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/pack/tile1.png b/examples/hot-update-demo/assets/pack/tile1.png
new file mode 100644
index 000000000..e62098ed5
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile1.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile1.png.meta b/examples/hot-update-demo/assets/pack/tile1.png.meta
new file mode 100644
index 000000000..0c9ba9479
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile1.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000001",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/pack/tile2.png b/examples/hot-update-demo/assets/pack/tile2.png
new file mode 100644
index 000000000..b880de6f7
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile2.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile2.png.meta b/examples/hot-update-demo/assets/pack/tile2.png.meta
new file mode 100644
index 000000000..9de74426c
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile2.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000002",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/pack/tile3.png b/examples/hot-update-demo/assets/pack/tile3.png
new file mode 100644
index 000000000..6d69c594c
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile3.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile3.png.meta b/examples/hot-update-demo/assets/pack/tile3.png.meta
new file mode 100644
index 000000000..c17641d56
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile3.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000003",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/pack/tile4.png b/examples/hot-update-demo/assets/pack/tile4.png
new file mode 100644
index 000000000..38b756e04
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile4.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile4.png.meta b/examples/hot-update-demo/assets/pack/tile4.png.meta
new file mode 100644
index 000000000..e11bdbff0
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile4.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000004",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/pack/tile5.png b/examples/hot-update-demo/assets/pack/tile5.png
new file mode 100644
index 000000000..40cc89be1
Binary files /dev/null and b/examples/hot-update-demo/assets/pack/tile5.png differ
diff --git a/examples/hot-update-demo/assets/pack/tile5.png.meta b/examples/hot-update-demo/assets/pack/tile5.png.meta
new file mode 100644
index 000000000..2a1e7f0a3
--- /dev/null
+++ b/examples/hot-update-demo/assets/pack/tile5.png.meta
@@ -0,0 +1,12 @@
+{
+ "uuid": "a1b2c3d4-0003-4003-8003-000000000005",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": { "left": 0, "right": 0, "top": 0, "bottom": 0 }
+ }
+}
diff --git a/examples/hot-update-demo/assets/scenes/main.esscene b/examples/hot-update-demo/assets/scenes/main.esscene
index ae852b9cf..feebd706b 100644
--- a/examples/hot-update-demo/assets/scenes/main.esscene
+++ b/examples/hot-update-demo/assets/scenes/main.esscene
@@ -15,13 +15,326 @@
},
{
"id": 1,
- "name": "Display",
+ "name": "HeroDisplay",
"parent": null,
"children": [],
"visible": true,
"components": [
{ "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
- { "type": "Sprite", "data": { "size": { "x": 4000, "y": 4000 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "texture": "@uuid:a1b2c3d4-0002-4002-8002-000000000002" } }
+ { "type": "Sprite", "data": { "size": { "x": 2000, "y": 2000 }, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "texture": "@uuid:a1b2c3d4-0002-4002-8002-000000000002" } }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Canvas",
+ "parent": null,
+ "children": [3, 6, 20],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "Canvas", "data": { "designResolution": { "x": 800, "y": 600 }, "scaleMode": 2 } },
+ { "type": "UINode", "data": {} }
+ ]
+ },
+
+ {
+ "id": 3,
+ "name": "TopBar",
+ "parent": 2,
+ "children": [4, 5],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 16, "unit": 0 }, "insetRight": { "value": 16, "unit": 0 }, "insetTop": { "value": 14, "unit": 0 }, "height": { "value": 56, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.11, "g": 0.12, "b": 0.15, "a": 0.9 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Title",
+ "parent": 3,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 20, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 }, "width": { "value": 460, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "热更新中心 · Hot-Update Center", "fontSize": 22, "bold": true, "color": { "r": 0.93, "g": 0.95, "b": 0.98, "a": 1 }, "align": 0, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "VersionLabel",
+ "parent": 3,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetRight": { "value": 20, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 }, "width": { "value": 240, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "远程内容 · CDN", "fontSize": 13, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 2, "verticalAlign": 1 } }
+ ]
+ },
+
+ {
+ "id": 6,
+ "name": "Strip",
+ "parent": 2,
+ "children": [7, 8, 10, 12, 14, 16, 18],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 16, "unit": 0 }, "insetRight": { "value": 16, "unit": 0 }, "insetTop": { "value": 84, "unit": 0 }, "height": { "value": 118, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.11, "g": 0.12, "b": 0.15, "a": 0.9 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 7,
+ "name": "StripLabel",
+ "parent": 6,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 20, "unit": 0 }, "insetRight": { "value": 20, "unit": 0 }, "insetTop": { "value": 10, "unit": 0 }, "height": { "value": 20, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "可选资源包 (DLC) · 点击「下载资源包」按需拉取远程内容", "fontSize": 13, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 0, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 8,
+ "name": "Tile0",
+ "parent": 6,
+ "children": [9],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 20, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 9,
+ "name": "TileMark0",
+ "parent": 8,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 10,
+ "name": "Tile1",
+ "parent": 6,
+ "children": [11],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 104, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 11,
+ "name": "TileMark1",
+ "parent": 10,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 12,
+ "name": "Tile2",
+ "parent": 6,
+ "children": [13],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 188, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 13,
+ "name": "TileMark2",
+ "parent": 12,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 14,
+ "name": "Tile3",
+ "parent": 6,
+ "children": [15],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 272, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 15,
+ "name": "TileMark3",
+ "parent": 14,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 16,
+ "name": "Tile4",
+ "parent": 6,
+ "children": [17],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 356, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 17,
+ "name": "TileMark4",
+ "parent": 16,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 18,
+ "name": "Tile5",
+ "parent": 6,
+ "children": [19],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 440, "unit": 0 }, "insetTop": { "value": 38, "unit": 0 }, "width": { "value": 64, "unit": 0 }, "height": { "value": 64, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.2, "g": 0.22, "b": 0.27, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 19,
+ "name": "TileMark5",
+ "parent": 18,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "?", "fontSize": 22, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+
+ {
+ "id": 20,
+ "name": "Console",
+ "parent": 2,
+ "children": [21, 22, 23, 25, 26, 27],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 16, "unit": 0 }, "insetRight": { "value": 16, "unit": 0 }, "insetBottom": { "value": 16, "unit": 0 }, "height": { "value": 196, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.11, "g": 0.12, "b": 0.15, "a": 0.96 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 21,
+ "name": "StatusLabel",
+ "parent": 20,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 22, "unit": 0 }, "insetRight": { "value": 22, "unit": 0 }, "insetTop": { "value": 18, "unit": 0 }, "height": { "value": 28, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "就绪", "fontSize": 20, "bold": true, "color": { "r": 0.93, "g": 0.95, "b": 0.98, "a": 1 }, "align": 0, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 22,
+ "name": "PlanLabel",
+ "parent": 20,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 22, "unit": 0 }, "insetRight": { "value": 22, "unit": 0 }, "insetTop": { "value": 50, "unit": 0 }, "height": { "value": 20, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "点击「检查更新」比对远程内容,或「下载资源包」按需拉取", "fontSize": 13, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 0, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 23,
+ "name": "ProgressTrack",
+ "parent": 20,
+ "children": [24],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 22, "unit": 0 }, "insetRight": { "value": 92, "unit": 0 }, "insetTop": { "value": 88, "unit": 0 }, "height": { "value": 16, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 1, "color": { "r": 0.24, "g": 0.26, "b": 0.31, "a": 1 }, "enabled": true } }
+ ]
+ },
+ {
+ "id": 24,
+ "name": "ProgressFill",
+ "parent": 23,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 0, "unit": 0 }, "insetTop": { "value": 0, "unit": 0 }, "insetRight": { "value": 0, "unit": 0 }, "insetBottom": { "value": 0, "unit": 0 } } },
+ { "type": "UIVisual", "data": { "visualType": 5, "color": { "r": 0.29, "g": 0.56, "b": 0.95, "a": 1 }, "fillMethod": 0, "fillOrigin": 0, "fillAmount": 0, "enabled": true } }
+ ]
+ },
+ {
+ "id": 25,
+ "name": "PctLabel",
+ "parent": 20,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetRight": { "value": 22, "unit": 0 }, "insetTop": { "value": 84, "unit": 0 }, "width": { "value": 62, "unit": 0 }, "height": { "value": 24, "unit": 0 } } },
+ { "type": "Text", "data": { "content": "0%", "fontSize": 14, "color": { "r": 0.6, "g": 0.64, "b": 0.72, "a": 1 }, "align": 2, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 26,
+ "name": "DlcSlot",
+ "parent": 20,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetLeft": { "value": 22, "unit": 0 }, "insetBottom": { "value": 18, "unit": 0 }, "width": { "value": 210, "unit": 0 }, "height": { "value": 42, "unit": 0 } } }
+ ]
+ },
+ {
+ "id": 27,
+ "name": "PrimarySlot",
+ "parent": 20,
+ "children": [],
+ "visible": true,
+ "components": [
+ { "type": "Transform", "data": {} },
+ { "type": "UINode", "data": { "position": 1, "insetRight": { "value": 22, "unit": 0 }, "insetBottom": { "value": 18, "unit": 0 }, "width": { "value": 210, "unit": 0 }, "height": { "value": 42, "unit": 0 } } }
]
}
]
diff --git a/examples/hot-update-demo/src/config.ts b/examples/hot-update-demo/src/config.ts
new file mode 100644
index 000000000..87e193806
--- /dev/null
+++ b/examples/hot-update-demo/src/config.ts
@@ -0,0 +1,69 @@
+// Static config for the hot-update center: the delivery endpoint, the DLC pack
+// refs, and the palette. Kept data-only so the systems read as pure wiring.
+import type { Color } from 'esengine';
+
+/** The `pack` addressable group (see `.esengine/asset-groups.json`) pulled on
+ * demand by the "Download pack" button — the DLC pattern. */
+export const PACK_GROUP = 'pack';
+
+/** The pack's textures, by ordinary project-relative path (the ref a game
+ * actually writes — loaders resolve it, routing through the `pack` remote group
+ * to the CDN automatically). The order here is the on-screen tile order. */
+export const PACK_TILES: readonly string[] = [
+ 'assets/pack/tile0.png',
+ 'assets/pack/tile1.png',
+ 'assets/pack/tile2.png',
+ 'assets/pack/tile3.png',
+ 'assets/pack/tile4.png',
+ 'assets/pack/tile5.png',
+];
+
+/**
+ * Where "Check for update" looks for a candidate manifest. A shipped build (or a
+ * host) can point this at a CDN by setting `window.__estellaHotUpdate` before the
+ * game boots; otherwise we probe a same-origin `asset-manifest.json` and treat a
+ * miss as "already up to date" (the editor Play case — there is no newer build to
+ * fetch, so the update flow honestly reports it).
+ */
+export interface HotUpdateEndpoint {
+ manifestUrl: string;
+ remoteRoot: string;
+}
+
+export function hotUpdateEndpoint(): HotUpdateEndpoint {
+ const w = globalThis as unknown as { __estellaHotUpdate?: Partial<HotUpdateEndpoint> };
+ const cfg = w.__estellaHotUpdate ?? {};
+ return {
+ manifestUrl: cfg.manifestUrl ?? 'asset-manifest.json',
+ remoteRoot: cfg.remoteRoot ?? '',
+ };
+}
+
+/**
+ * True when booted headless for the render verify (`index.html?headless=1`). In
+ * that mode the verify harness drives `checkForUpdate`/`applyUpdate` directly on
+ * the Assets resource, so we must NOT auto-check — two drivers would race the one
+ * staged pending-update. Button-driven flows are always safe (never auto-fired).
+ */
+export function isHeadless(): boolean {
+ const loc = (globalThis as unknown as { location?: { search?: string } }).location;
+ return typeof loc?.search === 'string' && /(?:\?|&)headless\b/.test(loc.search);
+}
+
+// ── Palette (0..1 linear-ish sRGB triples the UI authors in) ────────────────
+export const COLORS = {
+ card: { r: 0.11, g: 0.12, b: 0.15, a: 0.96 } as Color,
+ cardSoft: { r: 0.11, g: 0.12, b: 0.15, a: 0.90 } as Color,
+ track: { r: 0.24, g: 0.26, b: 0.31, a: 1 } as Color,
+ accent: { r: 0.29, g: 0.56, b: 0.95, a: 1 } as Color,
+ accentHover: { r: 0.36, g: 0.62, b: 0.98, a: 1 } as Color,
+ accentPressed: { r: 0.22, g: 0.46, b: 0.82, a: 1 } as Color,
+ control: { r: 0.22, g: 0.24, b: 0.29, a: 1 } as Color,
+ controlHover: { r: 0.28, g: 0.30, b: 0.36, a: 1 } as Color,
+ controlPressed: { r: 0.18, g: 0.20, b: 0.24, a: 1 } as Color,
+ ok: { r: 0.29, g: 0.80, b: 0.52, a: 1 } as Color,
+ warn: { r: 0.96, g: 0.62, b: 0.30, a: 1 } as Color,
+ text: { r: 0.93, g: 0.95, b: 0.98, a: 1 } as Color,
+ muted: { r: 0.60, g: 0.64, b: 0.72, a: 1 } as Color,
+ tileEmpty: { r: 0.20, g: 0.22, b: 0.27, a: 1 } as Color,
+} as const;
diff --git a/examples/hot-update-demo/src/main.ts b/examples/hot-update-demo/src/main.ts
index 111c4c8f1..77d0f00a7 100644
--- a/examples/hot-update-demo/src/main.ts
+++ b/examples/hot-update-demo/src/main.ts
@@ -1,4 +1,14 @@
-// This demo needs no game code. The Display sprite references the CDN texture by
-// @uuid in the scene; the runtime's built-in hot-update rebinder swaps in the new
-// art automatically when an update is applied. See the README.
-export {};
+// Hot-update demo. The scene (assets/scenes/main.esscene) authors the whole
+// UI — a background "remote content" sprite the hot update swaps, a DLC tile
+// strip, and an update console. These two systems are behavior only: build wires
+// the buttons to the engine's Assets hot-update API; reflect mirrors state onto
+// the scene-authored widgets each frame.
+import { addSystemToSchedule, Schedule } from 'esengine';
+
+import { buildSystem } from './systems/build';
+import { updateSystem } from './systems/update';
+
+// Both run on Update: build no-ops until the Canvas subtree loads (then builds
+// once); reflect no-ops until build has resolved the widgets.
+addSystemToSchedule(Schedule.Update, buildSystem);
+addSystemToSchedule(Schedule.Update, updateSystem);
diff --git a/examples/hot-update-demo/src/state.ts b/examples/hot-update-demo/src/state.ts
new file mode 100644
index 000000000..cd93a75e8
--- /dev/null
+++ b/examples/hot-update-demo/src/state.ts
@@ -0,0 +1,83 @@
+// Mutable demo state. The build system resolves the scene-authored widget
+// entities once; the async flows (check / apply / download) mutate the data
+// fields; the update system reflects data → widgets each frame. One direction.
+import type { Entity, ButtonHandle } from 'esengine';
+
+/** Where the flow is. Only one flow runs at a time (buttons disable while busy). */
+export type Phase =
+ | 'idle' // booted, nothing checked yet
+ | 'checking' // checkForUpdate in flight
+ | 'up-to-date' // no newer content
+ | 'update-found' // a plan is staged, awaiting the user to apply
+ | 'applying' // applyUpdate in flight (downloading + verifying)
+ | 'updated' // applied + hot-swapped
+ | 'update-failed' // download/integrity failure — rolled back
+ | 'downloading' // loadGroup(pack) in flight
+ | 'downloaded'; // pack pulled + bound
+
+/** Summary of a staged update, for the plan line. */
+export interface PlanInfo {
+ files: number;
+ bytes: number;
+ from: string;
+ to: string;
+}
+
+export interface DemoState {
+ built: boolean;
+ phase: Phase;
+ message: string;
+ /** 0..1 for the progress fill. */
+ progress: number;
+ loaded: number;
+ total: number;
+ plan: PlanInfo | null;
+ packBound: boolean[];
+
+ // Scene-authored widget entities, resolved once by the build system.
+ statusEntity: Entity;
+ planEntity: Entity;
+ pctEntity: Entity;
+ versionEntity: Entity;
+ fillEntity: Entity;
+ tiles: Entity[];
+ tileMarks: Entity[];
+
+ // Buttons are created into the scene's slots (createButton needs the
+ // interaction wiring); their labels are child entities we drive.
+ primaryBtn: ButtonHandle | null;
+ dlcBtn: ButtonHandle | null;
+ primaryLabel: Entity;
+ dlcLabel: Entity;
+}
+
+const NONE = -1 as unknown as Entity;
+
+export const state: DemoState = {
+ built: false,
+ phase: 'idle',
+ message: '就绪',
+ progress: 0,
+ loaded: 0,
+ total: 0,
+ plan: null,
+ packBound: [],
+
+ statusEntity: NONE,
+ planEntity: NONE,
+ pctEntity: NONE,
+ versionEntity: NONE,
+ fillEntity: NONE,
+ tiles: [],
+ tileMarks: [],
+
+ primaryBtn: null,
+ dlcBtn: null,
+ primaryLabel: NONE,
+ dlcLabel: NONE,
+};
+
+/** True while a flow owns the progress bar — both buttons disable. */
+export function isBusy(phase: Phase): boolean {
+ return phase === 'checking' || phase === 'applying' || phase === 'downloading';
+}
diff --git a/examples/hot-update-demo/src/systems/build.ts b/examples/hot-update-demo/src/systems/build.ts
new file mode 100644
index 000000000..c02dd3b8b
--- /dev/null
+++ b/examples/hot-update-demo/src/systems/build.ts
@@ -0,0 +1,173 @@
+// Resolves the scene-authored hot-update center once it's loaded, drops the two
+// interactive buttons into their slots, and owns the async flows those buttons
+// drive. The layout lives in the scene (assets/scenes/main.esscene); this file is
+// behavior only — the engine's Assets hot-update API wired to the engine's UI.
+import {
+ defineSystem, Res, GetWorld,
+ UIEvents, Assets,
+ Text, UIVisual, UIVisualType,
+ spawnUIEntity, createButton, TextAlign,
+} from 'esengine';
+import type { Entity, World, Color, UIEventQueue, ButtonHandle, TextData, UIVisualData } from 'esengine';
+
+import { COLORS, PACK_GROUP, PACK_TILES, hotUpdateEndpoint, isHeadless } from '../config';
+import { state, isBusy } from '../state';
+
+export const buildSystem = defineSystem(
+ [Res(UIEvents), Res(Assets), GetWorld()],
+ (events: UIEventQueue, assets, world: World) => {
+ if (state.built) return;
+ const dlcSlot = world.findEntityByName('DlcSlot');
+ const primarySlot = world.findEntityByName('PrimarySlot');
+ // The whole UI subtree loads atomically; the slots being present means the
+ // rest is too. Until then, retry next frame.
+ if (dlcSlot === null || primarySlot === null) return;
+
+ const req = (name: string): Entity => world.findEntityByName(name) as Entity;
+ state.statusEntity = req('StatusLabel');
+ state.planEntity = req('PlanLabel');
+ state.pctEntity = req('PctLabel');
+ state.versionEntity = req('VersionLabel');
+ state.fillEntity = req('ProgressFill');
+ state.tiles = PACK_TILES.map((_, i) => req(`Tile${i}`));
+ state.tileMarks = PACK_TILES.map((_, i) => req(`TileMark${i}`));
+ state.packBound = PACK_TILES.map(() => false);
+
+ // ── Async flows (button-driven; each mutates state, update.ts reflects) ─
+ const bind = (tile: Entity, mark: Entity, handle: number): void => {
+ if (world.valid(tile) && world.has(tile, UIVisual)) {
+ const v = world.get(tile, UIVisual) as UIVisualData;
+ v.visualType = UIVisualType.Image;
+ v.texture = handle;
+ v.color = { r: 1, g: 1, b: 1, a: 1 };
+ world.insert(tile, UIVisual, v);
+ }
+ if (world.valid(mark) && world.has(mark, Text)) {
+ const t = world.get(mark, Text) as TextData;
+ t.content = '';
+ world.insert(mark, Text, t);
+ }
+ };
+
+ async function startCheck(): Promise<void> {
+ if (isBusy(state.phase)) return;
+ state.phase = 'checking';
+ state.message = '正在检查更新…';
+ state.progress = 0;
+ state.plan = null;
+ const ep = hotUpdateEndpoint();
+ try {
+ const plan = await assets.checkForUpdate({ manifestUrl: ep.manifestUrl, remoteRoot: ep.remoteRoot });
+ if (!plan.hasUpdate) {
+ state.phase = 'up-to-date';
+ state.message = '已是最新版本';
+ } else {
+ state.plan = {
+ files: plan.changedAssets.length,
+ bytes: plan.totalBytes,
+ from: plan.fromRevision ?? '—',
+ to: plan.toRevision ?? '—',
+ };
+ state.phase = 'update-found';
+ state.message = '发现新版本';
+ }
+ } catch {
+ // No candidate manifest reachable (e.g. editor Play): honestly "up to date".
+ state.phase = 'up-to-date';
+ state.message = '已是最新版本(当前为本地内容)';
+ }
+ }
+
+ async function startApply(): Promise<void> {
+ if (state.phase !== 'update-found') return;
+ state.phase = 'applying';
+ state.message = '正在下载并校验更新…';
+ state.progress = 0;
+ state.loaded = 0;
+ state.total = state.plan?.files ?? 0;
+ const res = await assets.applyUpdate((loaded, total) => {
+ state.loaded = loaded;
+ state.total = total;
+ state.progress = total ? loaded / total : 0;
+ });
+ if (res.ok) {
+ state.phase = 'updated';
+ state.progress = 1;
+ state.message = '更新完成 · 内容已热替换(无需重新发包)';
+ state.plan = null;
+ } else {
+ state.phase = 'update-failed';
+ state.message = `更新失败已回滚 · ${res.failed.length} 个文件下载/校验未通过`;
+ }
+ }
+
+ async function startDownloadPack(): Promise<void> {
+ if (isBusy(state.phase)) return;
+ state.phase = 'downloading';
+ state.message = '正在下载资源包…';
+ state.progress = 0;
+ state.loaded = 0;
+ state.total = PACK_TILES.length;
+ await assets.loadGroup(PACK_GROUP, (loaded, total) => {
+ state.loaded = loaded;
+ state.total = total;
+ state.progress = total ? loaded / total : 0;
+ });
+ for (let i = 0; i < PACK_TILES.length; i++) {
+ try {
+ const tex = await assets.loadTexture(PACK_TILES[i]!);
+ bind(state.tiles[i]!, state.tileMarks[i]!, tex.handle);
+ state.packBound[i] = true;
+ } catch { /* leave the slot empty */ }
+ }
+ state.phase = 'downloaded';
+ state.progress = 1;
+ state.message = '资源包已下载并装载';
+ }
+
+ // ── Buttons into the scene's slots (createButton gates onClick on enabled) ─
+ state.dlcBtn = button(world, events, dlcSlot, COLORS.control, COLORS.controlHover, COLORS.controlPressed,
+ () => { void startDownloadPack(); });
+ state.dlcLabel = label(world, state.dlcBtn.entity, '下载资源包', false);
+
+ state.primaryBtn = button(world, events, primarySlot, COLORS.accent, COLORS.accentHover, COLORS.accentPressed,
+ () => {
+ if (state.phase === 'update-found') void startApply();
+ else if (!isBusy(state.phase)) void startCheck();
+ });
+ state.primaryLabel = label(world, state.primaryBtn.entity, '检查更新', true);
+
+ // Auto-check on boot for a real loading-screen feel — but NOT headless,
+ // where the render-verify harness is the sole update driver.
+ if (!isHeadless()) void startCheck();
+
+ state.built = true;
+ },
+ { name: 'HotUpdateBuildSystem' },
+);
+
+function button(
+ world: World, events: UIEventQueue, slot: Entity,
+ normal: Color, hover: Color, pressed: Color, onClick: () => void,
+): ButtonHandle {
+ return createButton({
+ world, events, parent: slot,
+ node: { fill: true },
+ background: { color: normal },
+ states: {
+ normal: { color: normal },
+ hover: { color: hover },
+ pressed: { color: pressed },
+ disabled: { color: { ...normal, a: normal.a * 0.5 } },
+ },
+ onClick,
+ });
+}
+
+function label(world: World, parent: Entity, content: string, bold: boolean): Entity {
+ return spawnUIEntity({
+ world, parent,
+ node: { fill: true },
+ text: { content, fontSize: 15, color: COLORS.text, align: TextAlign.Center, bold },
+ });
+}
diff --git a/examples/hot-update-demo/src/systems/update.ts b/examples/hot-update-demo/src/systems/update.ts
new file mode 100644
index 000000000..3555c2f84
--- /dev/null
+++ b/examples/hot-update-demo/src/systems/update.ts
@@ -0,0 +1,104 @@
+// Reflects demo state → widgets every frame. Pure read of `state`, guarded
+// writes (skip when unchanged) so there's no per-frame component churn. This is
+// the only place that touches the widgets after build — the async flows only
+// ever mutate plain data.
+import { defineSystem, GetWorld, Text, UIVisual } from 'esengine';
+import type { Entity, World, Color, TextData, UIVisualData } from 'esengine';
+
+import { COLORS } from '../config';
+import { state, isBusy } from '../state';
+
+export const updateSystem = defineSystem(
+ [GetWorld()],
+ (world: World) => {
+ if (!state.built) return;
+
+ setText(world, state.versionEntity, '远程内容 · CDN', COLORS.muted);
+ setText(world, state.statusEntity, state.message, statusColor());
+ setText(world, state.planEntity, planLine(), COLORS.muted);
+ setText(world, state.pctEntity, `${Math.round(state.progress * 100)}%`, COLORS.muted);
+ setFill(world, state.fillEntity, state.progress);
+
+ setText(world, state.primaryLabel, primaryLabel(), COLORS.text);
+ setText(world, state.dlcLabel, state.phase === 'downloading' ? '下载中…' : '下载资源包', COLORS.text);
+
+ const busy = isBusy(state.phase);
+ state.primaryBtn?.setDisabled(busy);
+ state.dlcBtn?.setDisabled(busy);
+ },
+ { name: 'HotUpdateReflectSystem' },
+);
+
+function statusColor(): Color {
+ switch (state.phase) {
+ case 'up-to-date':
+ case 'updated':
+ case 'downloaded':
+ return COLORS.ok;
+ case 'update-failed':
+ return COLORS.warn;
+ default:
+ return COLORS.text;
+ }
+}
+
+function primaryLabel(): string {
+ switch (state.phase) {
+ case 'checking': return '检查中…';
+ case 'update-found': return '下载并更新';
+ case 'applying': return '更新中…';
+ default: return '检查更新';
+ }
+}
+
+function planLine(): string {
+ switch (state.phase) {
+ case 'checking':
+ return '正在比对远程清单…';
+ case 'update-found': {
+ const p = state.plan;
+ return p ? `${p.files} 个文件 · ${humanBytes(p.bytes)} · rev ${short(p.from)} → ${short(p.to)}` : '';
+ }
+ case 'applying':
+ return `已下载并校验 ${state.loaded}/${state.total} 个文件`;
+ case 'updated':
+ return '已切换到新版本内容(现有贴图句柄已就地重绑)';
+ case 'downloading':
+ return `已下载 ${state.loaded}/${state.total} 个资源`;
+ case 'downloaded':
+ return `已装载 ${state.packBound.filter(Boolean).length}/${state.packBound.length} 个资源`;
+ case 'up-to-date':
+ return '远程清单与本地内容一致';
+ default:
+ return '点击「检查更新」比对远程内容,或「下载资源包」按需拉取';
+ }
+}
+
+function humanBytes(bytes: number): string {
+ if (bytes >= 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+ if (bytes >= 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+ return `${bytes} B`;
+}
+
+function short(rev: string): string {
+ return rev.length > 8 ? rev.slice(0, 7) : rev;
+}
+
+function setText(world: World, entity: Entity, content: string, color: Color): void {
+ if (!world.valid(entity) || !world.has(entity, Text)) return;
+ const t = world.get(entity, Text) as TextData;
+ const sameColor = t.color.r === color.r && t.color.g === color.g && t.color.b === color.b && t.color.a === color.a;
+ if (t.content === content && sameColor) return;
+ t.content = content;
+ t.color = { ...color };
+ world.insert(entity, Text, t);
+}
+
+function setFill(world: World, entity: Entity, amount: number): void {
+ if (!world.valid(entity) || !world.has(entity, UIVisual)) return;
+ const v = world.get(entity, UIVisual) as UIVisualData;
+ const next = amount < 0 ? 0 : amount > 1 ? 1 : amount;
+ if (v.fillAmount === next) return;
+ v.fillAmount = next;
+ world.insert(entity, UIVisual, v);
+}