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
chore: release v0.103.0
yhh89599f3f3ff1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 579b6f3d4..e975127f4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,21 @@ published separately; it ships inside the editor.## [Unreleased]+## [0.103.0] - 2026-11-12++### Added++- **Dynamic global illumination that does not leak.** A new `dynamicGI` effect on a `PostProcessVolume` lights a scene with the light its surfaces throw back, live, on WebGPU: a moved lamp, an opened door or a changed sun is in the next frames, with nothing baked. It traces a distance field of the scene instead of the screen or a voxel grid, so a sealed room stays dark (the voxel GI lit its walls from the sun outside) and what is off screen still lights what is on it. A model takes part when its import setting `dynamicGI` is on (the import then bakes a distance field and six cards beside the mesh); the built-in cube needs nothing. It reads material emission, the sun and up to eight point and spot lights with the frame's own falloff, and with `u_cellSize` set the field is three levels that follow the camera, for a world larger than one window. Held to Blender Cycles on six lab rooms (0.54 to 1.3 of its indirect light, zero in the sealed room) and to a cost gate that counts the rays and reads a frame asks for. It costs 3.3 ms at 1080p on a desktop GPU and 7.3 ms on a Snapdragon 8 Elite at 2530 x 1200. Not measured on a mid-range phone; a scene of many instances has not been tried; WebGL2 does not run it.+- **A quality level decides what the dynamic GI spends.** The low level leaves `dynamicGI` out, as it does the voxel GI, and builds no distance field for it. The medium level, which is what a phone gets when a project names none, runs it the cheaper way (`dynamicGIReduced` in a level's profile): one pixel in four asks the probes, a probe traces a quarter of its rays a frame, the cards are relit over eight frames and there are two thirds of the probe rows - 4.5 ms where the full way is 7.3 on a Snapdragon 8 Elite. It gives up a pixel or two of light across the edge two surfaces share and shows more grain while the camera moves. The effect's `u_halfRes` and `u_probeDensity` set the same by hand.+- **A native app streams long audio clips.** On Android, iOS and the desktop host a long clip stays compressed in memory and each voice decodes as it plays, by the same rule the web uses: a 175 second mp3 keeps 2.3 MB where it kept 64, and starts at once instead of after a 215 ms decode on the frame (measured on Windows). A decoded clip no longer falls out of the cache while a play is waiting on it, which is what left a phone silent where the editor had music.++### Changed++- **The 3D Starter looks finished out of the box.** Its sun casts mesh shadows (they were off, so every object floated), its camera carries a `PostProcessVolume` with a sky that lights the scene, height fog, GTAO, auto exposure, bloom, grade, vignette and FXAA, and its ground reaches the horizon. The editor's MCP teaches the same: `audit_look` says what a flat 3D scene lacks (shadow maps off, no sky light, fog, exposure or grade, gamma colour) with the fix for each, and `apply_look` adds it in one undo step, in a day, overcast or dusk mood.+- **AgX is its own effect group, `esengine/fx-agx`.** It brings Blender's tables (about 80 KB of source), so it no longer rides in `esengine/fx-basic`: a package whose volumes name `bloom`, `vignette` or `colorGrade` and not `agx` is about 92 KB smaller (measured on a WeChat export of the 3D Starter with a bloom volume against one with an agx volume), and the export still takes the group by itself for a volume that names `agx`. An AgX effect added from a script needs `import 'esengine/fx-agx'` (or the module set to Include in Project Settings), like the other groups; the editor and any entry that is not lean carry it as before.+- **A web package carries only the SDK its game reaches.** An export bundles the SDK with the host and the game's scripts in one pass, so a module nothing imports is not shipped.+- **The animator graph and grip poses ship in `esengine/skeletal-animation`.** They are installed only where the content uses them; a project that has neither no longer carries them.+### Fixed- **A material that loaded with part of it missing no longer fails in silence.** A texture that would not load, or a property of a shape nothing reads (a tiling written `[12, 12]` instead of `{ "x": 12, "y": 12 }`), left the material loaded and drawing with the default look where that part was, and said so only in one log line. The loader now reports what it left out; `get_diagnostics` lists it as `asset-degraded` against every entity that uses the material, naming the property and what to write instead, and Project Health shows it as a warning. The field that holds the material in Details is marked amber with the problem as its tip, and `write_project_file` and `create_asset` answer a material that has something in it that will not take effect with `problems`, at the moment it is written.@@ -22,13 +37,20 @@ published separately; it ships inside the editor.- **Several editors open at once can be told apart by an agent, and each grants on its own.** An editor advertises itself in a file of its own (its process id, its project, its port, its permission) instead of the one file the last editor to start overwrote. An agent attached to more than one gets `list_editors` and `select_editor` (or `--instance` / `ESTELLA_MCP_INSTANCE`), and until it chooses it is refused with the list rather than sent to whichever window won. It then drives the editor it chose and no other. The Read only / Can edit permission belongs to the editor window it is switched in and every editor starts read-only; it is no longer a saved setting that a second editor inherited. The Connect AI Tools dialog shows which editor it is.- **Fog, water, sky, rain, depth of field and light shafts work under an orthographic camera.** Distance Fog, Height Fog (and its volumetric pass), Underwater, Sky Atmosphere with its clouds, Rain and Depth of Field measured how far a surface is from the camera starting at depth 0, which for an orthographic eye is a plane as far behind the camera as the far plane is ahead (the projection runs from -far to far so 2D content behind the camera still draws). Distance Fog read every surface as past its end and fogged a scene to full colour at any near and far, Height Fog added a camera-length of extra air, Underwater took the camera for being above the water and drew nothing, the cloud layer, placed by that height, stood kilometres off, so a floor above the clouds was still in their shadow, Rain drew its streak layers in front of surfaces a few units from the eye, and Depth of Field blurred what stood exactly at its focus distance. Light Shafts projected the sun to a place on screen, which an orthographic camera does not have (the sun is at infinity), so the shafts were gone; they now run along the sun's direction on screen, as strong as a 60 degree perspective camera would have them for the angle the view makes with the sun. The rest now start from the plane the camera stands in. Perspective cameras are unchanged. Found by the closed-form render checks in `tools/oracle`, which draw spheres, floors and patches whose answer is a formula.- **AgX is Blender's AgX.** The effect read a 32^3 table by trilinear interpolation where Blender's configuration names tetrahedral, so a neutral input came out tinted (middle grey 6 codes short in red, where Blender gives 118 / 118 / 118) and a saturated blue lost 12 of its red; and its contrast look (`u_contrast` 1.2, Blender's Medium High Contrast) took its contrast in a different log space from Blender's, 14 codes off on saturated colours. It now carries Blender's own tables, the 57^3 view transform and the 37^3 luminance compensation the looks start with, reads them tetrahedrally, and takes the look's contrast where Blender does (in the inset Rec.2020 log, through that compensation); every grey and saturated colour checked is within 1 code of Blender 5.2's output, on both backends. The tables are packed (predicted from their neighbours and deflated, unpacked once when the effect is built), and together are 81 KB of source against the 131 KB the old 32^3 table was. Checked against Blender by the render checks in `tools/oracle`, which keep Blender's output as data.+- **A prefab whose root was put under a Canvas opens again.** Reparenting a prefab's root under a Canvas authored in Prefab Mode saved a file the editor then refused to open; it is saved with that Canvas as its root.+- **A wall under a roof is no longer sunlit along its top.** A shadow lookup stepped toward the light by as much as eleven texels of the shadow map on a surface the light grazes; where a texel is a few units (the low and medium levels, a large scene) that is further than a ceiling is thick, and the top of every wall under it came out lit. The lookup now moves off the surface along its normal and a texel and a half toward the light, at every level and on both backends. The wide filter of a soft shadow still forgives by slope, so a very soft shadow under a very thin roof can still let some through.+- **Dynamic resolution lowers the scale when a frame is late.** A GPU timer that read half a millisecond counted as headroom, so a late frame kept its scale; on WebGPU the timer now covers the whole frame and not the last pass alone.+- **The device's language reaches a native game.** Android, iOS and the desktop host report the system locale, and `zh-Hans-CN` reads as the `zh-CN` a browser gives; it was always `en`.+- **A game started over and over in one page no longer runs out of WebAssembly memory.** The module host has an end, the App that made it disposes it on quit, and the KTX2 transcode workers stop with it.+- **A chunk of decoration or grass is drawn out to the distance its rule names.** A chunk with little in it (one group of rocks) was culled 60 m away under a rule that said 1200.+- **Importing a feature module installs it under a bundler that treats chunks as pure.** `esengine/ai`, `tilemap`, `logic`, `worldgen`, `rig2d`, `dragonbones`, `gameplay` and `replication` registered themselves as a side effect of the import, which such a bundler dropped; the game then ran without them.+- **A camera whose viewport does not start at the window's corner draws through the post-process chain.** Its picture was placed as if it did.-### Changed+### Performance-- **The 3D Starter looks finished out of the box.** Its sun casts mesh shadows (they were off, so every object floated), its camera carries a `PostProcessVolume` with a sky that lights the scene, height fog, GTAO, auto exposure, bloom, grade, vignette and FXAA, and its ground reaches the horizon. The editor's MCP teaches the same: `audit_look` says what a flat 3D scene lacks (shadow maps off, no sky light, fog, exposure or grade, gamma colour) with the fix for each, and `apply_look` adds it in one undo step, in a day, overcast or dusk mood.+- **A generated world is there in a second instead of thirty.** Terrain pages and a foliage field's cells are made on the workers and only landed in the frame, the frame's budget is shared among everything that streams, and what stands by the player gets more of it. The first seconds of a generated world run at 5 to 12 ms a frame instead of 20.## [0.102.0] - 2026-11-11-- **AgX is its own effect group, `esengine/fx-agx`.** It brings Blender's tables (about 80 KB of source), so it no longer rides in `esengine/fx-basic`: a package whose volumes name `bloom`, `vignette` or `colorGrade` and not `agx` is about 92 KB smaller (measured on a WeChat export of the 3D Starter with a bloom volume against one with an agx volume), and the export still takes the group by itself for a volume that names `agx`. An AgX effect added from a script needs `import 'esengine/fx-agx'` (or the module set to Include in Project Settings), like the other groups; the editor and any entry that is not lean carry it as before.### Added@@ -15386,7 +15408,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 firstcommit on 2026-01-25.-[Unreleased]: https://github.com/esengine/estella/compare/v0.102.0...HEAD+[Unreleased]: https://github.com/esengine/estella/compare/v0.103.0...HEAD+[0.103.0]: https://github.com/esengine/estella/compare/v0.102.0...v0.103.0[0.102.0]: https://github.com/esengine/estella/compare/v0.101.1...v0.102.0[0.101.1]: https://github.com/esengine/estella/compare/v0.101.0...v0.101.1[0.101.0]: https://github.com/esengine/estella/compare/v0.100.0...v0.101.0diff --git a/SECURITY.md b/SECURITY.mdindex 1622633fc..4f08b31e7 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -7,8 +7,8 @@ upgrading to the latest release is the supported path to a fix.| Version | Supported ||---------|-----------|-| 0.102.x | Yes |-| < 0.102 | No |+| 0.103.x | Yes |+| < 0.103 | No |`tools/check-release-metadata.mjs` fails the build if this table stops matchingthe version being shipped, so it cannot quietly fall behind again.diff --git a/desktop b/desktopindex bbab68e63..4a9f0c1df 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit bbab68e632d5f11a0bf9fd5ce11e572d952bd1bd+Subproject commit 4a9f0c1df5f529d4e04b0211699e03bd3fbfd1fddiff --git a/package.json b/package.jsonindex 0aa4fb46f..d5668c158 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "estella",- "version": "0.102.0",+ "version": "0.103.0","private": true,"type": "module","description": "Estella - A fast 2D/3D game engine powered by WebAssembly and ECS",diff --git a/tools/goldenProjects.mjs b/tools/goldenProjects.mjsindex 99def95a3..1c8d20245 100644--- a/tools/goldenProjects.mjs+++ b/tools/goldenProjects.mjs@@ -92,6 +92,12 @@ export const CENSUS_FLOOR = '0.60.0';* that does not exist, and release notes are a different act. Theirs is ungated.*/export const SHIPPED = {+ "Dynamic global illumination that does not leak.":+ { notCertifiable: "Covered by tools/render-lab/gi_oracle.py (six lab rooms held to Blender Cycles, the sealed room held to zero) and the gi-cost gate; no golden project lists the effect, and it needs WebGPU compute, which the golden frames are not drawn with." },+ "A quality level decides what the dynamic GI spends.":+ { notCertifiable: "Covered by sdk/tests/quality.test.ts and quality-default.test.ts (what each level skips and sets) and measured on a phone by hand; a golden frame is drawn at one level and cannot show what another spends." },+ "A native app streams long audio clips.":+ { notCertifiable: "A native host's memory and start time, which no golden frame can show. Measured by hand on Windows with a 175 s mp3 and run once on an Android phone; the repo has no test of it." },"Multi-touch can be turned off.":{ notCertifiable: "Covered by sdk/tests/input-multitouch-switch.test.ts (the switch, its project default and the call that wins over it); a golden frame cannot show whether a second finger was ignored." },"A Spine skeleton can be part of a UI.":diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 5583ff090..008a200a9 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -4406,4 +4406,100 @@ export const NOTED = {{"note": "A material that loaded with part of it missing no longer fails in silence."},"feat(editor): a material written with something that will not take effect says so in the reply, and its field in Details is marked":{"note": "A material that loaded with part of it missing no longer fails in silence."},+ "fix(shadows): every level asks its shadow from a point moved off the surface along the normal - the full-lighting path too, hard edge, blocker search and soft filter; the nine shadow oracles hold on both backends":+ {"note": "A wall under a roof is no longer sunlit along its top."},+ "perf(foliage): a field's cells are made on the workers and only landed in the frame - the first seconds of a generated world run at 5-12 ms a frame instead of 20":+ {"note": "A generated world is there in a second instead of thirty."},+ "perf(streaming): a generated world is there in a second instead of thirty - terrain pages are made on the workers, the frame's budget is shared among what streams, and what stands by the player gets more of it":+ {"note": "A generated world is there in a second instead of thirty."},+ "fix(shadows): no sunlight on the top of a wall under a roof at the low and medium levels - a level that lights directly moves the lookup off the surface along its normal instead of up to eleven coarse texels toward the light, which was further than a ceiling is thick":+ {"note": "A wall under a roof is no longer sunlit along its top."},+ "fix(quality): the cheaper dynamic GI reaches a level put in force after the stack was built - it is written on the effects each frame, not on the stack as it is made; on a phone the switch did nothing (14.9 ms) and now gives 12.3":+ {"note": "A quality level decides what the dynamic GI spends."},+ "perf(gi): the medium level runs the dynamic GI its cheaper way - half-resolution gather, a quarter of a probe's rays a frame, cards over eight frames, two thirds of the probe rows; 7.3 -> 4.5 ms on a Snapdragon 8 Elite":+ {"note": "A quality level decides what the dynamic GI spends."},+ "fix(worldgen): a chunk of decoration or grass is drawn out to the distance its rule names, however little stands in it - a chunk with one group of rocks was culled 60 m away under a rule that said 1200":+ {"note": "A chunk of decoration or grass is drawn out to the distance its rule names."},+ "feat(gi): a half-resolution way to add the light - one pixel in four asks the probes and every pixel takes it from the four round it; the medium level runs it, and the apply costs 0.14 ms where it cost 0.25 at 1080p":+ {"note": "A quality level decides what the dynamic GI spends."},+ "feat(quality): the low level leaves the dynamic GI out, and a level that does builds no distance field for it either":+ {"note": "A quality level decides what the dynamic GI spends."},+ "fix(gi): no bright and dark blobs beside an edge the camera moves past - a probe whose own history is of another surface still mixes with the neighbours that are on its own":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(audio): a native host streams long clips - the file stays compressed and each voice decodes as it plays, by the same rule as the web; a 175 s mp3 keeps 2.3 MB instead of 64, and loads in no time instead of a decode on the frame":+ {"note": "A native app streams long audio clips."},+ "fix(gi): walls that looked dirty - a probe that has not moved keeps five times the history, so the blotches left of the grain on a still wall go":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(sidemodules): a game started over and over in one page no longer runs out of WebAssembly memory - the module host has an end, the App that made it disposes it on quit, and the KTX2 transcode workers stop with it":+ {"note": "A game started over and over in one page no longer runs out of WebAssembly memory."},+ "fix(gi): no dashed dark line down the edge two walls share - a probe whose G-buffer normal faces into a wall takes the field's way out instead, and a pixel weighs a probe's light by its own normal only as far as the probe faces the same way":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(quality): dynamic resolution lowers the scale when the frame is late and its own run was not - a GPU timer that reads half a millisecond no longer counts as headroom, and on WebGPU that timer now covers the whole frame instead of the surface pass":+ {"note": "Dynamic resolution lowers the scale when a frame is late."},+ "fix(gi): the grain and the dots in the corners - a probe's history is mixed with the eight round it on the same surface, a probe the eye sees is always moved clear of the walls it stands between, and a pixel no probe agrees with takes what the probes get themselves":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(native): the device language reaches the game - Android, iOS and desktop report the system locale, and 'zh-Hans-CN' reads as the 'zh-CN' a browser gives instead of always 'en'":+ {"note": "The device's language reaches a native game."},+ "fix(gi): no black band along the edges of a room - a ray that starts in a corner is moved clear of the wall next to it, and a card pixel buried in another body stays where it is so a sealed room stays dark":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): a scene with no GI yet is built 12 ms a frame instead of 3 - on a phone the first light comes in about 2 s, not 10; a moving camera keeps 3 ms":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): the first build of the field is sliced over frames, and a camera move sends only the rebuilt range - the cards keep their light instead of starting the bounces again every step":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): a camera that moves rebuilds the following field a few milliseconds a frame - boxes built only when the scene changes, levels repacked only when they changed, slabs queued; measured with a walking camera":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): half the probe rows on a phone, and a continuous probe filter - GI on a Snapdragon 8 Elite 20.5 -> 6.4 ms":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): the scene key is asked every frame and the boxes are built only when it changes; profiling switch u_skip is declared so it reaches the engine":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(gi): the dynamic GI runs on a device - the scene is fed through the native heap, the apply reads each probe's stored position instead of rebuilding it; phone numbers and a skip switch for measuring":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): a distance field of three levels that follows the camera, and point and spot lights - lit in the cards with the frame's own falloff, shadowed through the field, held to the CPU reference on the lamp lab":+ {"note": "Dynamic global illumination that does not leak."},+ "perf(gi): dynamic GI 8.9 -> 3.3 ms at 1080p - a card relit by a workgroup of 64 rays, cards relit in slices, probes by stride and a fixed count, the nearest instance recorded per field cell; frame timing tool":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(gi): the dynamic GI has no dark seam in a wall corner and a quieter picture - probes are taken from the nine nearest with a tent weight, history blend 0.15":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): the dynamic GI reads material emission and baked meshes - cards carry the emissive colour, a mesh brings its distance field and cards through the cook, checked on the lab rooms as meshes":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): dynamic GI on the GPU - card lighting, 8x8 screen probes traced through the distance field, applied to the picture; no leak in the sealed room and 0.54-1.08 of Cycles in the lab rooms":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): screen probes - octahedral hemisphere probes traced through the distance field into the surface cache, many bounces by iteration, checked against Cycles on the lab rooms":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): surface cache - mesh cards baked at import, lit by the sun with distance-field shadows, and looked up by a ray's hit":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(gi): mesh distance fields load as assets, import can bake them, and the scene field composes them into clipmaps with a sphere trace checked on WebGPU":+ {"note": "Dynamic global illumination that does not leak."},+ "feat(pipeline): mesh signed distance field baker for the dynamic GI - exact near the surface, thin walls grown to a body, half-float file format":+ {"note": "Dynamic global illumination that does not leak."},+ "fix(sdk): importing esengine/gameplay or esengine/replication installs them under a bundler that treats chunks as pure":+ {"note": "Importing a feature module installs it under a bundler that treats chunks as pure."},+ "feat(post): AgX is its own effect group, esengine/fx-agx, so a package that does not use it does not carry its 80 KB of tables":+ {"note": "AgX is its own effect group, `esengine/fx-agx`."},+ "feat(post): AgX carries Blender's own tables and looks - 57^3 view transform and the luminance-compensated contrast look - read tetrahedrally, packed to 81 KB; within 1 code of Blender":+ {"note": "AgX is Blender's AgX."},+ "feat(export): a web package bundles the SDK with the host and the scripts, so what the game does not reach is not shipped":+ {"note": "A web package carries only the SDK its game reaches."},+ "fix(sdk): importing esengine/ai, tilemap, logic, worldgen, rig2d or dragonbones installs them under a bundler that treats chunks as pure":+ {"note": "Importing a feature module installs it under a bundler that treats chunks as pure."},+ "fix(post): AgX reads its table tetrahedrally as Blender does, so greys stay grey; oracle scenes for AgX against Blender and for soft point and spot shadows":+ {"note": "AgX is Blender's AgX."},+ "refactor(sdk): the animator graph and grip poses ship in esengine/skeletal-animation, installed only where the content uses them":+ {"note": "The animator graph and grip poses ship in `esengine/skeletal-animation`."},+ "fix(post): light shafts run along the sun's direction on screen under an orthographic camera; oracle scenes for shafts":+ {"note": "Fog, water, sky, rain, depth of field and light shafts work under an orthographic camera."},+ "fix(post): rain and depth of field measure from the camera's plane under an orthographic camera; oracle scenes for rain, depth of field and custom sky":+ {"note": "Fog, water, sky, rain, depth of field and light shafts work under an orthographic camera."},+ "fix(render): a camera that does not start at the window's corner draws through the post chain":+ {"note": "A camera whose viewport does not start at the window's corner draws through the post-process chain."},+ "fix(post): sky and clouds place the cloud layer from the camera's plane under an orthographic camera; oracle scenes for the sky dome and cloud shadows":+ {"note": "Fog, water, sky, rain, depth of field and light shafts work under an orthographic camera."},+ "fix(post): height fog and underwater start their ray at the camera's plane under an orthographic camera; oracle scenes for both":+ {"note": "Fog, water, sky, rain, depth of field and light shafts work under an orthographic camera."},+ "feat(mcp): the 3D look is taught by the editor's MCP, not a guide page":+ {"note": "The 3D Starter looks finished out of the box."},+ "feat(templates): the 3D Starter ships a finished look - sun shadows, sky light, fog, exposure and grade - with a guide to getting it":+ {"note": "The 3D Starter looks finished out of the box."},+ "feat(mcp): audit_look says why a 3D scene looks flat, and apply_look gives it a finished look":+ {"note": "The 3D Starter looks finished out of the box."},};