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: what this release changed, and the two things a build will tell you

esengine2581d226bece
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1aa7dc57a..9b62e2bf1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -84,6 +84,64 @@ published separately; it ships inside the editor.
a GPU. The unmasked strings are read where the browser allows it, so a report
now names `ANGLE Metal Renderer: Apple M4` instead of a constant.
+
+- **`examples/celestial-heights` — a game the engine is judged by.** Not a
+ showcase: an ARPG built to be played from its first room to its boss, whose
+ purpose is to find where the engine hurts. Everything below in this release
+ that is not the editor came out of building it, and the rule was that a place
+ it hurt got fixed in the ENGINE — a ledger (`engine-gaps.mjs`) held every
+ workaround, with a gate that refuses a release while the ledger is non-empty.
+ It ships at zero entries.
+
+- **`CameraBounds`: a level's edge belongs at the edge of the screen.** A camera
+ that follows a character walked off the map with it, and every project solved
+ that by clamping in its own follow script — so the constraint lived in whichever
+ system happened to move the camera. It is now a property of where the camera IS:
+ applied after every camera mover, opted into per axis (max > min), centring the
+ view when the interval is narrower than the viewport. Orthographic only.
+
+- **`SceneManager.reload()`: a run can start over.** `switchTo(theSceneYouAreIn)`
+ is a no-op — correct for a door, and no way at all to express dying, retrying,
+ or starting a new run.
+
+- **A prefab spawned at runtime belongs to the scene it landed in.** Entities
+ created from script had no scene, so a scene switch left them behind — the
+ spawner's bullets outliving the level. They now adopt the active scene at spawn;
+ `scene: false` opts out for something deliberately global.
+
+- **`NavAgent.radius` is finally read.** The field was declared and nothing
+ consumed it, so every path was planned for a point and a body-sized agent
+ clipped every corner. Paths are now planned against a clearance field (two-pass
+ chamfer, out-of-bounds counted as blocked, computed on first ask and dropped
+ when walkability changes). **The default changed from 12 to 0**: a field that
+ never took effect would otherwise silently re-route every already-published
+ project the moment it started working.
+
+- **`Virtual('id')`: an input a thumb can reach.** A binding could name a key, a
+ button or an axis, and nothing a finger touches. A named virtual input is an
+ ordinary binding — it serializes, rebinds and lives in a `.inputmap` like the
+ rest — so an on-screen control feeds the same action a key does, rather than a
+ game reading screen rectangles that drift when the layout moves.
+
+- **`PlatformAdapter.hasTouch()`.** "Show the on-screen stick only on a touch
+ device" was unanswerable, so the alternative was to wait for a first touch —
+ which asks the player to touch nothing, twice.
+
+- **`randomSeed`, and one place a seed lives.** The engine's randomness was a
+ particle-system member seeded from the clock, so a run could never be repeated:
+ no replay, no reproducible bug report, and nothing constant to assert about a
+ frame with particles in it. `RandomSource` is the engine's source now, still
+ clock-seeded so an unconfigured game varies; pass `randomSeed` at boot and the
+ run reproduces. Consumers take a NAMED stream rather than sharing a generator,
+ so adding an emitter cannot change what something else rolled.
+
+- **Atlas membership is declared, like delivery already was.** Which textures
+ pack into one page was a `<name>.atlas/` folder convention known only to the
+ cook. `.esengine/asset-groups.json` now carries an `atlases` section, resolved
+ by `resolveAtlas` beside `resolveAssetGroup`. It is a SEPARATE axis from a
+ delivery group on purpose: an atlas may span two groups, and a group may hold
+ two atlases. The folder convention stays as the zero-config default.
+
### Fixed
- **A particle emitter now takes its world Y into the draw key, like everything
@@ -127,6 +185,55 @@ published separately; it ships inside the editor.
(`navGridFromTiles`) was always right and always tested; the seam where two
subsystems with opposite conventions meet had no test, and now does.
+
+- **Safe-area insets are asked for again, not decided on frame one.** The insets
+ were read once when the plugin built and written once to the nodes that existed
+ then. On iOS `env()` has no value until after the first layout, so that read was
+ always zero; and a HUD loaded additively afterwards brought nodes nobody ever
+ visited. The read is throttled and the nodes are walked every frame. Measured
+ under a 44px notch: the node used to receive 0 and now receives 88.
+
+- **Asking a resource store for a value is not the same as having one.**
+ `get` materialised a default into the same table `has` reads, so one system
+ touching a resource was enough to make an install gate believe its plugin was
+ already there. Localization defaults to null, so an additively-loaded scene lost
+ every translation — 38 errors on one scene, none after.
+
+- **A body does not block the view of itself.** Line-of-sight cast from origin to
+ origin while colliders sit at the feet (the 2.5D norm), so the ray entered the
+ target's own capsule before reaching it. The symptom hid well: visible from the
+ side, invisible from below. 49 sightings and no damage before; 571 and a hurt
+ player after.
+
+- **A desktop package built with default settings drew nothing.** Every format a
+ KTX2 transcodes to is a 4x4 block format, and WebGPU refuses a compressed
+ texture whose size is not whole blocks — WebGL does not, so the web package was
+ fine and the native one could not create a single texture. A 70x70 sprite was
+ enough to blank the frame. The cook ships such a texture raw and names it in a
+ warning; the runtime no longer picks a block format for an image that cannot be
+ whole blocks.
+
+- **The same game no longer differs by an sRGB encode between desktop platforms.**
+ The swapchain took whatever format the surface preferred, so whether it encoded
+ on write was the driver's answer. The engine hands that surface values that are
+ already display-encoded, so a platform whose preferred format was *Srgb encoded
+ them twice. Measured: one platform read an exact sRGB encode of the other, on
+ every probe.
+
+- **A headless export could not compress a texture, and said nothing.** The Basis
+ encoder finds its own binary through `import.meta.url`, and the headless path
+ bundles the cook into a temp directory — so it looked for it beside the bundle
+ and threw on every texture. Worse, the cook answered that by DROPPING each
+ asset: no file staged, no manifest entry, and a report that said the build was
+ clean. An asset the game reaches and the cook cannot produce is now an error.
+
+- **The desktop runtime templates can be downloaded.** The Windows, macOS and
+ Linux templates are published, valid and reachable; the button did nothing at
+ all, because two different types were both called `NativePlatform` — the export
+ targets (one `desktop` for three OSes) and the platforms a template is published
+ for — and every layer above the download hand-narrowed it back to the mobile
+ pair.
+
## [0.47.0] - 2026-08-08
### Added
diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
index a09f8c4ad..11febb7fa 100644
--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx
@@ -51,6 +51,7 @@ importable from `esengine`) with `wasmBaseUrl`:
| `backend` | `'webgl2' \| 'webgpu'` | `'webgl2'` | `'webgpu'` boots the injected-device path — the host must have acquired a `GPUDevice` and passed it as the module factory's `preinitializedWebGPUDevice` before instantiation. |
| `canvasSelector` | `string` | `'#canvas'` | CSS selector for the WebGPU swapchain canvas (must be in the DOM). WebGL ignores it. |
| `colorSpace` | `'gamma' \| 'linear'` | `'gamma'` | Project color space. `'linear'` renders in linear light (sRGB decode on sample, linear blending, explicit encode in the final blit). Must be declared **at app creation** — shaders compile against it. |
+| `randomSeed` | `number` | — | Seed the engine's randomness so the run reproduces — a replay, a bug report, an assertion about a frame. Absent, every run differs, which is what a player wants of particles. Subsystems take independent named streams, so adding an emitter cannot change what something else rolled. |
| `ySortLayers` | `number` | `0` | Bitmask of render layers (bits 0–31) that sort by world Y within the layer (top-down occlusion). |
| `screenFit` | `ScreenScalingData` | off (`scaleMode: -1`) | Project camera fit: letterboxes a design resolution into the actual aspect. Only installed when `scaleMode` is a real mode (≥ 0); `SCREEN_FIT_OFF` (-1) keeps the legacy Canvas-or-raw fit. |
diff --git a/docs/astro/src/content/docs/publishing/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdx
index 1273df2f2..e4f20426a 100644
--- a/docs/astro/src/content/docs/publishing/hot-update.mdx
+++ b/docs/astro/src/content/docs/publishing/hot-update.mdx
@@ -109,6 +109,9 @@ never disagree about where an asset ships):
"groups": {
"cdn": { "folder": "assets/cdn", "mode": "remote" }
},
+ "atlases": {
+ "ui": { "folder": "assets/art/ui" }
+ },
"activeProfile": "dev",
"profiles": {
"dev": { "remoteRoot": "" },
@@ -123,6 +126,8 @@ 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. |
+| `atlases` | `Record<name, {folder}>` | Folders whose textures pack into one atlas page. A **separate axis** from `groups`: which assets travel together and which share a texture page are different decisions, so an atlas may span two delivery groups and a group may hold two atlases. Absent ⇒ the `<name>.atlas/` folder convention still applies. |
+| `atlases.<name>.folder` | `string` | Project-relative folder; every texture under it packs into this atlas. Longest matching prefix wins. |
| `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/assets/overview/#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/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index 678d26df0..b6f0d2a1a 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -243,14 +243,32 @@ picks whether to honor those settings at all:
- **Compression → By import settings** — each texture and audio clip compresses per
its Import Settings (PNG → **KTX2** Basis Universal, Max Size, WAV → MP3), and
- `<name>.atlas/` folders pack into atlas pages so many small sprites ship as one
- texture and batch in one draw call.
+ textures that share an atlas pack into atlas pages so many small sprites ship as
+ one texture and batch in one draw call. Membership comes from a `<name>.atlas/`
+ folder, or from an [`atlases` entry](/docs/publishing/hot-update/#esengineasset-groupsjson)
+ in `.esengine/asset-groups.json`.
- **Compression → Skip all** — ship everything raw, for fast iteration.
KTX2 textures are transcoded by the runtime to the best format each device
supports (ASTC → ETC2 → S3TC, falling back to RGBA8), with their mip chains —
smaller downloads and less VRAM.
+:::caution[A texture is compressed only if its size is whole 4×4 blocks]
+Every format a KTX2 transcodes to is block-compressed, and WebGPU refuses a
+compressed texture whose width or height is not a multiple of 4 — so a 70×70
+sprite would fail to create on the native runtime, and one failed texture blanks
+the frame. The build ships such a texture **raw** instead and names it in a
+warning:
+
+```
+assets/textures/platform.png: shipped raw — 70x70 is not a multiple of 4,
+which a block-compressed texture must be
+```
+
+Resize it (or pad it) to a multiple of 4 to get the compression back. Atlas pages
+are always whole blocks, so packing small odd-sized sprites is the other way out.
+:::
+
**Content addressing** is on by default for Web/Desktop (each file named by a hash
of its bytes — immutable URLs, automatic dedupe). **Advanced** holds the CDN root
for [hot update](/docs/publishing/hot-update/), source maps, and whether to open the
diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
index da9367239..89cc6d41f 100644
--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx
@@ -47,6 +47,7 @@ await app.run();
| `backend` | `'webgl2' \| 'webgpu'` | `'webgl2'` | `'webgpu'` 走注入设备路径——宿主必须先取得 `GPUDevice` 并在实例化前作为模块工厂的 `preinitializedWebGPUDevice` 传入。 |
| `canvasSelector` | `string` | `'#canvas'` | WebGPU 交换链画布的 CSS 选择器(必须已在 DOM 中)。WebGL 忽略它。 |
| `colorSpace` | `'gamma' \| 'linear'` | `'gamma'` | 项目色彩空间。`'linear'` 在线性光下渲染(采样时 sRGB 解码、线性混合、最终 blit 显式编码)。必须**在创建应用时**声明——着色器按它编译。 |
+| `randomSeed` | `number` | — | 给引擎的随机性播种,让这次运行可复现——回放、bug 复现、对某一帧下断言。不填则每次运行都不同,这对粒子正是玩家想要的。各子系统取的是按名字独立的流,所以新增一个发射器不会改变别处抽到的数。 |
| `ySortLayers` | `number` | `0` | 渲染层位掩码(bit 0–31):层内按世界 Y 排序(俯视遮挡)。 |
| `screenFit` | `ScreenScalingData` | 关(`scaleMode: -1`) | 项目相机适配:把设计分辨率 letterbox 进实际宽高比。仅当 `scaleMode` 为真实模式(≥ 0)时安装;`SCREEN_FIT_OFF`(-1)保持旧行为(有 Canvas 用 Canvas 适配,否则用原始 orthoSize)。 |
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 aa2eac487..57ad95378 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
@@ -80,6 +80,9 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回
"groups": {
"cdn": { "folder": "assets/cdn", "mode": "remote" }
},
+ "atlases": {
+ "ui": { "folder": "assets/art/ui" }
+ },
"activeProfile": "dev",
"profiles": {
"dev": { "remoteRoot": "" },
@@ -93,6 +96,8 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回
| `version` | `string` | 配置版本(`"1.0"`)。 |
| `groups` | `Record<name, {folder, mode}>` | 文件夹 → 交付方式的指派。 |
| `groups.<name>.folder` | `string` | 项目相对文件夹;其下(递归)每个资产都归入该组。文件夹嵌套时,**最长**匹配前缀胜出。 |
+| `atlases` | `Record<name, {folder}>` | 其下纹理打进同一张图集页的文件夹。与 `groups` 是**互相独立的两个轴**:哪些资产一起交付、哪些资产共享一张纹理页,是两个不同的决定——所以一张图集可以跨两个交付组,一个交付组里也可以有两张图集。不写 ⇒ 仍然沿用 `<name>.atlas/` 文件夹约定。 |
+| `atlases.<name>.folder` | `string` | 项目相对文件夹;其下每张纹理都打进这张图集。最长匹配前缀胜出。 |
| `groups.<name>.mode` | `'local' \| 'subpackage' \| 'remote'` | 交付模式。 |
| `groups.<name>.alwaysInclude` | `boolean` | 即使构建里没有任何东西*可达*到它,也照样发布这个组——用于只有你的代码点名的资产(url、路径、富文本标记)。默认关闭。见[资源](/docs/zh-cn/assets/overview/#只有代码点名的资产)。 |
| `activeProfile` | `string` | 构建使用哪个 profile(`profiles` 的键)。 |
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
index 70aeb8793..e4c9e35a9 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -201,13 +201,29 @@ node build-tools/cli.js build -t wechat
每个平台一个页签,所以一张纹理可以为手机压得比网页端更狠。构建这一层只决定是否遵循这些设置:
- **资源压缩 → 按导入设置** —— 每张纹理与每段音频按各自的导入设置压缩
- (PNG → **KTX2** Basis Universal、Max Size、WAV → MP3),`<name>.atlas/` 文件夹打包成图集页,
- 于是许多小精灵作为一张纹理发布、在一次绘制里合批。
+ (PNG → **KTX2** Basis Universal、Max Size、WAV → MP3),同属一张图集的纹理打包成图集页,
+ 于是许多小精灵作为一张纹理发布、在一次绘制里合批。图集成员来自 `<name>.atlas/` 文件夹,
+ 或 `.esengine/asset-groups.json` 里的
+ [`atlases` 条目](/docs/zh-cn/publishing/hot-update/#esengineasset-groupsjson)。
- **资源压缩 → 全部跳过** —— 一律原样输出,便于快速迭代。
KTX2 纹理由运行时转码为设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8),并带上
mip 链——下载更小、显存更省。
+:::caution[只有尺寸是完整 4×4 块的纹理才会被压缩]
+KTX2 能转码到的每一种格式都是块压缩格式,而 WebGPU 拒绝宽或高不是 4 的倍数的压缩纹理——
+所以一张 70×70 的精灵在原生运行时上会创建失败,**而一张纹理失败就会让整帧变黑**。
+构建会把这类纹理**原样发布**,并在警告里点名:
+
+```
+assets/textures/platform.png: shipped raw — 70x70 is not a multiple of 4,
+which a block-compressed texture must be
+```
+
+把它改成 4 的倍数(缩放或补边)就能恢复压缩。图集页永远是完整块,所以把尺寸零碎的小图
+打进图集是另一条出路。
+:::
+
**内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。
**高级**里放着[热更新](/docs/zh-cn/publishing/hot-update/)的 CDN 根地址、source map,
以及构建结束后是否打开输出目录。