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.

release: v0.27.0 - the manual catches up, the API reads one way

esengine3b610dfd8dd7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4edd1ea10..dfedbd5a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,103 @@ published separately; it ships inside the editor.
## [Unreleased]
+## [0.27.0] - 2026-07-18
+
+The manual catches up with the engine, and the API learns to read one way.
+The docs site grows from per-subsystem overviews into a **fine-grained manual**:
+new foundational chapters finally teach what nothing taught before — that one
+world unit is one design pixel, that `Canvas.pixelsPerUnit` is the physics
+meter scale, how quaternion rotation works in 2D — and the UI manual splits
+into nine subchapters written from source, in both languages. Eight new
+examples cover every previously example-less pillar, and chasing them through
+live Play runs flushed out real engine bugs that had been hiding for releases:
+within a layer, **z now actually orders sprites**, and a `RenderTexture` can
+finally be shown by a Sprite.
+
+### Added
+
+- **Foundational documentation chapters** (en + 简体中文). Core Concepts gains
+ "Transforms, Units & Coordinates" (the Transform component, Y-up, the
+ world-units-are-design-pixels doctrine, quaternion rotation and its
+ helpers, parenting), "Screen & Design Resolution" (Canvas, every scale
+ mode's fit math, `ScreenScaling`, why UI px are design px, safe areas) and
+ "App Setup & Lifecycle" (`createWebApp`/headless options, the plugin
+ model, lifecycle events, subsystem health, side modules, hot reload);
+ Utilities gains "Profiling & Diagnostics" (stats overlay, `Logger`, frame
+ capture, texture budgets).
+- **The UI manual, split into nine subchapters** — Overview / Layout / Text /
+ Widgets / Lists & Scrolling / Interaction / Theming / Data Binding /
+ Controllers — documenting the previously invisible surface: dimension
+ semantics and anchor presets in code, the real rich-text tag set, the
+ focus/drag pipelines, the ListView virtualization contract, all twelve
+ theme color roles, and two-way widget binding.
+- **Eight new examples**, all verified in live editor Play runs:
+ `camera-follow` (FollowTarget damping/dead zone, screen shake, view-target
+ blends), `save-load` (versioned SaveManager slots with a live v1→v2
+ migration), `scene-flow` (menu → levels through SceneManager fades over a
+ persistent shell), `input-actions` (rebindable InputMap actions +
+ gestures), `timers-demo`, `trail-demo`, `render-texture` and
+ `drawing-demo` (immediate Draw, retained Graphics, procedural Mesh2D).
+ The catalog also lists the previously uncatalogued `chat` and
+ `ui-controller`.
+- **Play == ship scene registration.** Pressing Play now registers every
+ project scene under its export name (siblings lazily by path), so
+ `SceneManager.switchTo` behaves identically in the editor and in a
+ shipped build.
+- `RenderTextureHandle.texture` — a resource-table handle components can
+ actually consume (`Sprite.texture`, `UIVisual.texture`), registered
+ through the same external-texture channel video frames use.
+- The `Mesh2D` component and the animator sub-machine helpers
+ (`enterStatePath`, `leafStateOf`, `evaluateAnimatorPath`) join the main
+ barrel; Spine's wiring surface (`SpinePlugin`/`SpineEvents`/`Spine`) is
+ mirrored into the main barrel exactly like physics.
+
+### Changed
+
+- **The public API reads one way** (breaking, pre-1.0). The physics class is
+ now `PhysicsAPI` and the resource token `Physics` — `Res(Physics)` like
+ `Res(Audio)`/`Res(Tween)` everywhere else. Six `Api`-suffixed classes are
+ now `API` (`CameraViewAPI`, `SpriteAnimationAPI`, `AnimatorControllerAPI`,
+ `PostProcessAPI`, `LocalizationAPI`, `TimelineAPI`). The deprecated
+ `getAllRegisteredComponents` alias is gone (use `getComponentRegistry`).
+- **One plugin-construction shape.** A lowercase `xPlugin` export is always a
+ ready-to-add `Plugin` value; configurable plugins expose a PascalCase
+ class. `lifecyclePlugin` is now such a value (configure with
+ `new LifecyclePlugin({ autoPause })` — previously a factory call).
+- **Plugin wiring moved to one barrel.** `webAppFactory` now only ships the
+ app factories; the UI pipeline plugins, the physics/spine wiring and
+ `PostProcessPlugin` live in a dedicated `core-plugins` barrel, the
+ Timeline surface joined `core-content`, and engine-internal
+ `init*/shutdown*API` functions left the public surface.
+- **Director and scene APIs are callable from systems.** `setViewTarget`,
+ `shakeCamera` and `transitionTo` accept the `CameraDirector` /
+ `SceneManager` resource state alongside the `App`, so gameplay systems no
+ longer need an App handle they cannot get.
+- `Canvas.pixelsPerUnit` is documented (tooltip included) as what it actually
+ is — world pixels per physics meter — and the abandoned
+ texture-px-per-unit helpers on the C++ component are gone.
+
+### Fixed
+
+- **z actually orders sprites within a layer.** The draw sort key assumed
+ z ∈ [-1, 1] and truncated: any real-world z wrapped through the bit mask
+ and sorted non-monotonically, and the blended stages had the painter's
+ order inverted. Depth now maps through order-preserving float bits —
+ transparent draws back-to-front, opaque front-to-back.
+- **Runtime-loaded scenes unload cleanly.** Entities of a scene registered at
+ runtime carried the `SceneOwner` tag but were never adopted into the scene
+ instance's entity set, so `switchTo` away from such a scene leaked every
+ entity it had spawned.
+- **`RenderTexture` + `Sprite` no longer renders white.** Pointing
+ `Sprite.texture` at the raw device `textureId` sampled the white fallback;
+ the new `texture` handle goes through the resource table.
+- **PreviewPlugin's fallback camera un-zoomed.** It still derived its ortho
+ size from the abandoned px-per-unit doctrine — a 100× zoom-in whenever a
+ scene had a Canvas but no active camera.
+- The physics guide's joint samples used a `world.spawn(Component, …)`
+ overload that does not exist; unit contracts (meters vs world pixels) are
+ now stated on `PhysicsAPI` itself and in the guide.
+
## [0.26.0] - 2026-07-17
Tilemaps leave the square grid, and projects make the UI their own. The editor
@@ -1012,7 +1109,8 @@ not kept before this file was introduced — see the Git history at
`github.com/esengine/estella` for the full commit-level record since the first
commit on 2026-01-25.
-[Unreleased]: https://github.com/esengine/estella/compare/v0.23.0...HEAD
+[Unreleased]: https://github.com/esengine/estella/compare/v0.27.0...HEAD
+[0.27.0]: https://github.com/esengine/estella/compare/v0.26.0...v0.27.0
[0.23.0]: https://github.com/esengine/estella/compare/v0.22.0...v0.23.0
[0.22.0]: https://github.com/esengine/estella/compare/v0.21.0...v0.22.0
[0.21.0]: https://github.com/esengine/estella/compare/v0.20.0...v0.21.0
diff --git a/desktop/package.json b/desktop/package.json
index cc7cd248e..a2e61ad85 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "@estella/editor",
- "version": "0.26.0",
+ "version": "0.27.0",
"private": true,
"license": "Apache-2.0",
"description": "Estella Editor — visual scene editor for the Estella 2D WASM engine",
diff --git a/sdk/package.json b/sdk/package.json
index 05a9e9df7..b38d6efd9 100644
--- a/sdk/package.json
+++ b/sdk/package.json
@@ -1,6 +1,6 @@
{
"name": "esengine",
- "version": "0.6.0",
+ "version": "0.7.0",
"private": true,
"type": "module",
"description": "Estella SDK - A fast 2D game engine for Web and WeChat MiniGames",