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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.pngindex c81c811b3..43862f1e9 100644Binary 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 differdiff --git a/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.png b/docs/astro/src/assets/guides/zh/hot-update-delivery-menu.pngindex a25be558e..ed5cbfa7c 100644Binary 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 differdiff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdxindex 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, a1D blend trees driven by named **parameters**. Author it in the editor (orregister one in code), attach an `Animator` component naming the controller, thenset 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.```typescriptimport { 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.mdxindex 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 URLsare immutable and identical files dedupe to a single copy. On by default forWeb/Desktop.- **Auto-atlas** — put loose PNGs in a `<name>.atlas/` folder and the cook packsthem 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`:++++*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 theshipped 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 referencecounting 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 alsodiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex 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.mdxindex 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** soyou 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.mdxindex 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(...)` 注册的控制器;两种方式可以共存:```typescriptimport { 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.mdxindex 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`:++++*右键文件夹 → **交付方式**。三种模式决定资产从哪里发布;**总是打进构建**决定它到底发不发。*++```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.mdxindex 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.mdxindex 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`(蓝)表示远端,`分包`(紫)表示分包。@@ -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 根地址。留空 ⇒ 同源。 |