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(guides): four features that shipped without a line of documentation

esengine708bc8e8c118
diff --git a/docs/astro/src/assets/guides/en/hot-update-delivery-menu.png b/docs/astro/src/assets/guides/en/hot-update-delivery-menu.png
index c81c811b3..43862f1e9 100644
Binary files a/docs/astro/src/assets/guides/en/hot-update-delivery-menu.png and b/docs/astro/src/assets/guides/en/hot-update-delivery-menu.png differ
diff --git a/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.png b/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.png
index a25be558e..ed5cbfa7c 100644
Binary files a/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.png and b/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.png differ
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdx
index 50c70b8ff..0fda56714 100644
--- a/docs/astro/src/content/docs/guides/animation.mdx
+++ b/docs/astro/src/content/docs/guides/animation.mdx
@@ -67,8 +67,28 @@ const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q
| `registerClip(clip)` | Register a `SpriteAnimClip` at runtime. |
| `getClip(name)` | Look up a registered clip. |
-Clips can carry **frame events** (`SpriteAnimEvent`) that fire when playback
-reaches a frame — use them for footstep sounds or hit frames.
+### Frame events
+
+Clips carry **frame events** (`SpriteAnimEvent` — `{ frame, name, data? }`) that
+fire when playback reaches a frame: a footstep sound, the hit frame of an attack,
+the moment a coin flips. Author them on the **Events** track of the Flipbook
+editor — pick a frame, **Add event**, name it; the frame strip marks which frames
+carry one. Then subscribe:
+
+```typescript
+import { defineSystem, Res, SpriteAnimation } from 'esengine';
+
+const listen = defineSystem([Res(SpriteAnimation)], (anim) => {
+ anim.onEvent(playerEntity, (e) => {
+ if (e.name === 'footstep') audio.playSFX('sfx/step.wav');
+ });
+});
+```
+
+| Method | Description |
+|---|---|
+| `onEvent(entity, handler)` | Listen to one entity's frame events. Returns an unsubscribe function. |
+| `onEventGlobal(handler)` | Listen to every entity's — the handler receives the entity too. |
### Authoring clips in the editor
@@ -264,7 +284,15 @@ For character animation, an **animator controller** holds states, transitions, a
1D blend trees driven by named **parameters**. Author it in the editor (or
register one in code), attach an `Animator` component naming the controller, then
set parameters each frame through `Res(AnimatorController)` — the controller
-resolves the current state, clip, and blend:
+resolves the current state, clip, and blend.
+
+A controller is an **`.esanimator` asset**: create one from the Content Browser's
+**New** menu, double-click to open the graph editor above — states with positions,
+transitions with conditions, and a **Parameters** panel — and point the `Animator`
+component's `controller` field at it with the asset picker. The scene preloads it,
+so it is registered before the first tick. Assigning a plain string instead
+resolves against controllers `registerController(...)` put there from code; both
+kinds coexist.
```typescript
import { defineSystem, Query, Res, Animator, AnimatorController } from 'esengine';
@@ -281,7 +309,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)
| `Animator` field | Type | Default | Description |
|---|---|---|---|
-| `controller` | string | `''` | Registered controller name. |
+| `controller` | string | `''` | An `.esanimator` asset ref (what the editor writes) or a name passed to `registerController` in code. |
| `currentState` | string | `''` | Active state, as a `/`-separated path for nested machines (seeded from the controller's initial state). |
| `enabled` | boolean | `true` | Disable to freeze the state machine. |
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 3d200405c..3768d8ffe 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -118,14 +118,54 @@ way it can:
- **Compress textures** — encode PNGs to GPU-ready **KTX2** (Basis Universal),
which the runtime transcodes to the best format the device supports (ASTC → ETC2
- → S3TC, falling back to RGBA8). Toggle **Compress textures** in the Package dialog.
+ → S3TC, falling back to RGBA8), mip chain included. Per-asset **Import Settings**
+ decide this, with a tab per platform, so a texture can be compressed harder for a
+ phone than for the web; the Package dialog's **Compression** switch only chooses
+ whether to honor those settings or skip them all.
- **Content-address** — name each shipped file by a hash of its bytes, so URLs
are immutable and identical files dedupe to a single copy. On by default for
Web/Desktop.
- **Auto-atlas** — put loose PNGs in a `<name>.atlas/` folder and the cook packs
them into atlas pages (with the frame UVs written into the manifest), so many
- small sprites ship as one texture and batch in one draw call. Toggle **Pack .atlas
- folders** in the Package dialog.
+ small sprites ship as one texture and batch in one draw call.
+
+### Shipping what only code names
+
+Reachability is what keeps a build from shipping everything — and it is **blind to
+anything your code names at runtime**: a texture in rich-text markup, a clip played
+by url, a prefab spawned by path. Those get culled, and nothing warns you, because
+the editor serves the project straight off disk and never needs the manifest. The
+first symptom is a silent button or a missing image in a real build.
+
+Declare the folder instead. In the **Content Browser**, right-click it and pick
+**Delivery → Always include in builds** — the same menu that sets local /
+subpackage / remote delivery, writing to the same `.esengine/asset-groups.json`:
+
+![The Content Browser folder menu — Delivery, with Local / Subpackage / Remote and Always include in builds](../../../assets/guides/en/hot-update-delivery-menu.png)
+
+*Right-click a folder → **Delivery**. The three modes decide where an asset ships from; **Always include in builds** decides whether it ships at all.*
+
+```json
+{
+ "version": "1.0",
+ "groups": {
+ "markup-images": {
+ "folder": "assets/textures",
+ "mode": "local",
+ "alwaysInclude": true
+ }
+ }
+}
+```
+
+It is Unity's `Resources` folder and Unreal's additional cook directory, in the
+model this project already had. **Off by default**, deliberately.
+
+<Aside type="tip">
+ Assets under `subpackages/` are always included even when unreachable — only
+ their group assignment differs. `alwaysInclude` is what gives any other folder
+ the same guarantee.
+</Aside>
## Lifetime & reference counting
@@ -200,13 +240,15 @@ parameters (pixel-art nearest vs. smooth linear) are covered in the
(and a WeChat subpackage) instead of bloating the main bundle.
- **Let cooking cull + compress** — reachable-only staging and PNG→KTX2 keep the
shipped bundle small; don't ship raw PNGs you can cook.
+- **Mark folders your code loads by name** as **Delivery → Always include in
+ builds**, or reachability culling will drop them from the build the editor never
+ needed a manifest to run.
- **Set a texture budget** on memory-constrained targets and trust reference
counting for the rest.
<Aside type="note">
Content hashing runs on the **staged** bytes (after PNG→KTX2 encoding), so the
- manifest hash identifies the shipped artifact. Assets under `subpackages/` are
- always included even if unreachable — only their group assignment differs.
+ manifest hash identifies the shipped artifact.
</Aside>
## See also
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
index 46ac54832..045e5948e 100644
--- a/docs/astro/src/content/docs/guides/audio.mdx
+++ b/docs/astro/src/content/docs/guides/audio.mdx
@@ -61,6 +61,7 @@ it once ready.
| `preload(url)` | Decode and cache a clip ahead of time (async). |
| `preloadAll(urls)` | Preload an array of clips (async). |
| `getBufferHandle(url)` | The cached buffer for `url`, or `undefined`. |
+| `getSpectrum(out)` | Fill a `Uint8Array` with the master output's frequency spectrum (0–255 per bin, low→high) for a visualizer. Returns `false` on backends without analysis (WeChat) — treat that as silence. |
| `setBufferBudget(bytes)` | Override the warm-cache byte budget (`null` returns to the RuntimeConfig value; `0` disables the cache). |
| `getBufferStats()` | Residency counters: `bufferCount`, `bufferBytes`, `bufferBudget`, `evictableCount`. |
| `trimBufferCache()` | Free every unused cached buffer now (the engine calls this on OS memory warnings). |
diff --git a/docs/astro/src/content/docs/guides/hot-update.mdx b/docs/astro/src/content/docs/guides/hot-update.mdx
index da7df3d8e..ffd1aeb55 100644
--- a/docs/astro/src/content/docs/guides/hot-update.mdx
+++ b/docs/astro/src/content/docs/guides/hot-update.mdx
@@ -69,6 +69,10 @@ In the **Content Browser**, right-click any folder and pick **Delivery → Remot
*Content Browser → right-click a folder → **Delivery** → **Local / Subpackage / Remote (CDN / hot-update)**. The choice is written to `.esengine/asset-groups.json`.*
+The same submenu carries **Always include in builds** — an independent toggle that
+keeps the folder in a build even when nothing in it is reachable from a scene. See
+[Assets](/docs/guides/assets/#shipping-what-only-code-names).
+
A folder assigned to a Subpackage or Remote group carries a corner **badge** so
you can see the delivery layout at a glance — `CDN` (blue) for remote, `PKG`
(purple) for subpackage.
@@ -119,6 +123,7 @@ never disagree about where an asset ships):
| `groups` | `Record<name, {folder, mode}>` | Folder → delivery assignments. |
| `groups.<name>.folder` | `string` | Project-relative folder; every asset under it (recursively) joins the group. The **longest** matching prefix wins when folders nest. |
| `groups.<name>.mode` | `'local' \| 'subpackage' \| 'remote'` | Delivery mode. |
+| `groups.<name>.alwaysInclude` | `boolean` | Ship the group even when nothing in the build *reaches* it — for assets only your code names (a url, a path, rich-text markup). Off by default. See [Assets](/docs/guides/assets/#shipping-what-only-code-names). |
| `activeProfile` | `string` | Which profile the build uses (key into `profiles`). |
| `profiles.<name>.remoteRoot` | `string` | CDN root that this profile's remote-group assets are served from. Empty ⇒ same-origin. |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
index 3a8717dc6..a59b6fdb4 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
@@ -65,7 +65,26 @@ const jump = defineSystem([Query(Mut(SpriteAnimator)), Res(SpriteAnimation)], (q
| `registerClip(clip)` | 在运行时注册一个 `SpriteAnimClip`。 |
| `getClip(name)` | 查找一个已注册的片段。 |
-片段可以携带**帧事件**(`SpriteAnimEvent`),播放到某帧时触发——用于脚步声或命中帧。
+### 帧事件
+
+片段携带**帧事件**(`SpriteAnimEvent`——`{ frame, name, data? }`),播放到某帧时触发:
+脚步声、攻击的命中帧、金币翻面的那一刻。在 Flipbook 编辑器的 **Events** 轨道上编辑它们——
+选中一帧,**添加事件**,起个名字;帧条会标出哪些帧带事件。然后订阅:
+
+```typescript
+import { defineSystem, Res, SpriteAnimation } from 'esengine';
+
+const listen = defineSystem([Res(SpriteAnimation)], (anim) => {
+ anim.onEvent(playerEntity, (e) => {
+ if (e.name === 'footstep') audio.playSFX('sfx/step.wav');
+ });
+});
+```
+
+| 方法 | 说明 |
+|---|---|
+| `onEvent(entity, handler)` | 监听某个实体的帧事件。返回一个取消订阅的函数。 |
+| `onEventGlobal(handler)` | 监听所有实体的帧事件——回调还会收到实体本身。 |
### 在编辑器中创作剪辑
@@ -246,8 +265,13 @@ tween.sequence([
*动画控制器:状态(Idle / Move / Hop)、带条件的转移(`speed>20`、`hop` 触发器),以及驱动它们的**参数**面板。*
角色动画用一个**动画控制器**:它持有状态、转移和由命名**参数**驱动的 1D 混合树。在编辑器
-里编辑它(或用代码注册),给实体加一个指明控制器名的 `Animator` 组件,然后每帧通过
-`Res(AnimatorController)` 设置参数——控制器会解析出当前状态、片段与混合:
+里编辑它(或用代码注册),给实体加一个指明控制器的 `Animator` 组件,然后每帧通过
+`Res(AnimatorController)` 设置参数——控制器会解析出当前状态、片段与混合。
+
+控制器是一份 **`.esanimator` 资产**:在内容浏览器的 **新建** 菜单里创建,双击打开上图的
+图编辑器——带位置的状态、带条件的转移,以及**参数**面板——再用资产选择器把 `Animator`
+组件的 `controller` 字段指向它。场景会预加载它,所以第一帧之前它就已注册好。若直接填一个
+普通字符串,则解析为代码里 `registerController(...)` 注册的控制器;两种方式可以共存:
```typescript
import { defineSystem, Query, Res, Animator, AnimatorController } from 'esengine';
@@ -264,7 +288,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)
| `Animator` 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
-| `controller` | string | `''` | 已注册的控制器名。 |
+| `controller` | string | `''` | 一个 `.esanimator` 资产引用(编辑器写入的),或代码里传给 `registerController` 的名字。 |
| `currentState` | string | `''` | 活动状态;嵌套状态机时是 `/` 分隔的路径(从控制器的初始状态种入)。 |
| `enabled` | boolean | `true` | 关掉即冻结状态机。 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
index 7ed2afbd5..c2588d48f 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -104,12 +104,48 @@ const { failed } = await assets.preload(
**剔除一切触达不到的资源**,暂存可达文件,并写出清单。过程中它还能:
- **压缩纹理** —— 把 PNG 编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
- 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。在打包对话框勾选**压缩纹理**。
+ 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8),连同 mip 链。这由逐资产的
+ **导入设置**决定,每个平台一个页签,所以一张纹理可以为手机压得比网页端更狠;
+ 打包对话框的**资源压缩**开关只选择遵循还是全部跳过这些设置。
- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。
Web/桌面默认开启。
- **自动图集** —— 把零散的 PNG 放进 `<name>.atlas/` 文件夹,烘焙时会把它们打包成图集页
- (帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。在打包对话框勾选
- **打包 .atlas 文件夹**。
+ (帧 UV 写进清单),于是许多小精灵作为一张纹理发布、在一次绘制里合批。
+
+### 只有代码点名的资产
+
+可达性分析正是拦住"什么都往包里塞"的东西——而它对**你的代码在运行时才点名的一切是瞎的**:
+富文本标记里的纹理、按 url 播放的音频、按路径 spawn 的预制体。这些会被剔除,而且没有任何警告,
+因为编辑器直接从磁盘伺服项目,压根不需要清单。第一个症状是真实构建里一个没声的按钮或一张缺失的图。
+
+那就把这个文件夹声明出来。在**内容浏览器**里右键它,选 **交付方式 → 总是打进构建**——
+就是那个设置本地 / 分包 / 远端交付的同一个菜单,写进同一份
+`.esengine/asset-groups.json`:
+
+![内容浏览器的文件夹菜单——交付方式,含本地 / 分包 / 远端与"总是打进构建"](../../../../assets/guides/zh/hot-update-delivery-menu.png)
+
+*右键文件夹 → **交付方式**。三种模式决定资产从哪里发布;**总是打进构建**决定它到底发不发。*
+
+```json
+{
+ "version": "1.0",
+ "groups": {
+ "markup-images": {
+ "folder": "assets/textures",
+ "mode": "local",
+ "alwaysInclude": true
+ }
+ }
+}
+```
+
+它就是 Unity 的 `Resources` 文件夹、Unreal 的 additional cook directory,
+只不过落在这个项目原本就有的模型里。**默认关闭**,这是刻意的。
+
+<Aside type="tip">
+ `subpackages/` 下的资源即使触达不到也总会被包含——只是分组归属不同。
+ `alwaysInclude` 让任何其他文件夹也能拿到同样的保证。
+</Aside>
## 生命周期与引用计数
@@ -168,11 +204,13 @@ const freed = trimTextureCache(); // 立即丢弃所有可逐出纹理
- **把按需内容放到 `subpackages/<name>/` 下**,它就成为一个 lazy 组(以及微信子包),而不是
撑大主包。
- **让 cook 去剔除 + 压缩**——只暂存可达资源、PNG→KTX2 让发布包更小;别发能被 cook 的裸 PNG。
+- **把代码按名字加载的文件夹标记为 交付方式 → 总是打进构建**,否则可达性剔除会把它们从构建里丢掉——
+ 而编辑器从来不需要清单就能跑起来。
- **在内存受限的目标上设纹理预算**,其余交给引用计数。
<Aside type="note">
内容哈希基于**暂存后**的字节(PNG→KTX2 编码之后)计算,因此清单里的哈希标识的是最终
- 发布的产物。`subpackages/` 下的资源即使触达不到也总会被包含——只是分组归属不同。
+ 发布的产物。
</Aside>
## 参见
diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
index b873eaf91..e4fa7980a 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/audio.mdx
@@ -56,6 +56,7 @@ const play = defineSystem([Res(Audio)], (audio) => {
| `preload(url)` | 提前解码并缓存一个片段(异步)。 |
| `preloadAll(urls)` | 预加载一组片段(异步)。 |
| `getBufferHandle(url)` | `url` 的已缓存缓冲区,或 `undefined`。 |
+| `getSpectrum(out)` | 用主输出的频谱填充一个 `Uint8Array`(每个频段 0–255,从低频到高频),供可视化用。在没有分析能力的后端(微信)上返回 `false`——按静音处理。 |
| `setBufferBudget(bytes)` | 覆盖热缓存字节预算(`null` 回到 RuntimeConfig 的值;`0` 关闭缓存)。 |
| `getBufferStats()` | 驻留计数:`bufferCount`、`bufferBytes`、`bufferBudget`、`evictableCount`。 |
| `trimBufferCache()` | 立即释放所有未使用的缓存缓冲区(引擎在系统内存警告时会自动调用)。 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx
index 414e810ec..a74d7e4e6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx
@@ -51,6 +51,9 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回
*内容浏览器 → 右键文件夹 → **交付方式** → **本地 / 分包 / 远端(CDN / 热更)**。选择会写入 `.esengine/asset-groups.json`。*
+同一个子菜单里还有**总是打进构建**——一个独立开关,即使文件夹里没有任何东西能从场景可达,
+也让它留在构建里。见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。
+
被指派到分包或远端组的文件夹会带一个角标**徽标**,让你一眼看清交付布局——`CDN`(蓝)表示远端,`分包`(紫)表示分包。
![内容浏览器中一个文件夹图块,带蓝色 CDN 交付徽标](../../../../assets/guides/zh/hot-update-cdn-badge.png)
@@ -91,6 +94,7 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回
| `groups` | `Record<name, {folder, mode}>` | 文件夹 → 交付方式的指派。 |
| `groups.<name>.folder` | `string` | 项目相对文件夹;其下(递归)每个资产都归入该组。文件夹嵌套时,**最长**匹配前缀胜出。 |
| `groups.<name>.mode` | `'local' \| 'subpackage' \| 'remote'` | 交付模式。 |
+| `groups.<name>.alwaysInclude` | `boolean` | 即使构建里没有任何东西*可达*到它,也照样发布这个组——用于只有你的代码点名的资产(url、路径、富文本标记)。默认关闭。见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。 |
| `activeProfile` | `string` | 构建使用哪个 profile(`profiles` 的键)。 |
| `profiles.<name>.remoteRoot` | `string` | 该 profile 的远端组资产的 CDN 根地址。留空 ⇒ 同源。 |