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: what this release changed, and the two things a build will tell you
esengine2581d226bece
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 reportnow 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 twosubsystems 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### Addeddiff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex 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.mdxindex 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.mdxindex 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 perits 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 devicesupports (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 hashof its bytes — immutable URLs, automatic dedupe). **Advanced** holds the CDN rootfor [hot update](/docs/publishing/hot-update/), source maps, and whether to open thediff --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.mdxindex 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.mdxindex 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.mdxindex 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,以及构建结束后是否打开输出目录。