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(changelog): the 0.74 Added notes lead with their headlines
esengine2de8679d61e7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex bb3214a04..f10424977 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,20 +18,21 @@ published separately; it ships inside the editor.- **Android release signing.** A Shipping APK (and App Bundle) is signed with the release key the project names under Project Settings → Android → Signing — two PEM paths, the passphrase kept in this machine's keychain (the command line reads `ESTELLA_ANDROID_KEY_PASSPHRASE`); Development builds keep the development key. A Shipping build without one says it will be refused by Google Play.- **EmscriptenGLX on WeChat.** A WeChat project can ship the engine linked with WeChat's EmscriptenGLX (Project Settings → WeChat → Render through EmscriptenGLX, off by default), which issues the engine's GL calls natively instead of through JavaScript: a draw-heavy scene spent about 12% less time rendering on an Android phone. It adds about 310KB of wasm and needs base library 3.8.12 on Android, or iOS in 高性能+ mode; any other host renders through WebGL2 as before, and the log says which. The engine is built once with `node build-tools/cli.js build -t wechat-glx`, which fetches WeChat's library at a pinned version and hash, and emsdk 4.0.10 beside the main one; an export that asks for it without it says so.-- A connected development build says which graphics API it draws through — WebGL2, EmscriptenGLX or WebGPU — once its game has started: the Profiler shows it beside the device's controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.-- A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device's own engine. The frame debugger's replay shows one pass of a captured frame.-- Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.-- A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file's own level 0 byte for byte, so it no longer shimmers into the distance. Bistro's 2048² textures each took about 0.3 s; the package grows by the chain's third.-- Exporting compresses textures on every core the machine lets it use instead of one: the encoder runs on worker threads, and the pool widens only while the memory its workers have measured fits in half the machine's. The ORCA Bistro exterior's first web export on a 20-thread Windows machine took 5 min 25 s; one core had managed 184 of its 200 textures in 47 minutes. The encoded bytes are the same either way. `ESTELLA_ENCODER_WORKERS` sets the width, and 0 encodes on the calling thread.-- Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.-- A scene's preload logs what each asset type cost it — how many, their summed load time and the slowest one — and `preloadSceneAssets` returns the same as `timings` and `wallMs`. Bistro on a Windows machine: 132 materials 54 s, 107 textures 47 s and 1505 meshes 45 s of load time over 24 s of wall time.-- KTX2 textures on the web and in the editor transcode on worker threads instead of the main thread, one to four of them by the machine's cores. Bistro's assets loaded in 14 s instead of 24 s on a Windows machine, and the page stays responsive while they do. A realm with no workers (a mini-game host) transcodes on the main thread as before, and so does one whose workers fail, which says so once.-- Web exports pack their small local assets — meshes, materials, KTX2 textures, timelines and animation assets — into a few `packs/*.pack` files, one request each, and the runtime reads each asset out of its pack. A browser holds six connections to a site, so a scene of thousands of small files loaded at the pace of its requests: Bistro's 1505 meshes took 43 s of load time for 0.2 s of upload. Its first frame on a Windows machine went from 15.2 s to 7.3 s, pixel for pixel the same. An export with hot update configured keeps one file per asset, since an update downloads assets one by one; an update that meets a packed asset refuses it by name.-- Importing a model converts its DDS textures to PNG — BC1 to BC5 and uncompressed, whether the file sits beside the model or inside an FBX — so a model shipped with DDS art arrives with every map instead of references nothing can load. BC5 normal maps get their Z rebuilt; BC6H and BC7 are named and skipped.-- An FBX model's specular map can be read as packed occlusion, roughness and metalness (Specular Map → Packed ORM in its import settings, `--specular-map orm` on the command line), the way scenes authored for Falcor such as Bistro store it. Read as a colour, as before, it has no slot in metal/rough shading and is left out.-- An FBX material takes its alpha from its base colour image, since FBX has no alpha mode: an image that is mostly clear where it is not solid imports as a cutout (alpha test 0.5), one that is mostly in between as blended, and one without a real alpha channel stays opaque. A material whose name ends in `.DoubleSided`, as Lumberyard-era exports such as Bistro mark it, draws both sides. Bistro's trees were leaf cards drawn opaque and one-sided — black squares with a few leaves on them.-- A project file's settings that nothing reads are named instead of dropped: opening the project in the editor and exporting from the command line both say which keys of `project.esproject` are ignored, and point a block written at the wrong level (a `rendering` beside `features` rather than inside it) to where it belongs. That misplaced block had left a linear, ACES project running in gamma with no tone curve and no word.-- A model import says when a map's pixels contradict its slot: an occlusion map that is zero in every texel is left out with a warning, since it would take all ambient light from the surface, and a map that is one colour throughout is noted.+- **A connected development build says which graphics API it draws through.** WebGL2, EmscriptenGLX or WebGPU, once its game has started — the Profiler shows it beside the device's controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.+- **A connected development build can be asked for the whole frame it composited.** Every camera and the UI over them, as the player sees it — `device_screenshot` returns it as a PNG, read back by the device's own engine. The frame debugger's replay shows one pass of a captured frame.+- **Web and mini-game packages decode Zstandard-supercompressed KTX2.** The native host already did. UASTC textures made outside Estella usually are supercompressed, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.+- **A single-level KTX2 made outside Estella ships with a mip chain.** The cook encodes the levels below it and keeps the file's own level 0 byte for byte, so it no longer shimmers into the distance. Bistro's 2048² textures each took about 0.3 s; the package grows by the chain's third.+- **Exporting compresses textures on every core.** The encoder runs on worker threads, as many as the machine lets this process use, and the pool widens only while the memory its workers have measured fits in half the machine's. The ORCA Bistro exterior's first web export on a 20-thread Windows machine took 5 min 25 s; one core had managed 184 of its 200 textures in 47 minutes. The encoded bytes are the same either way. `ESTELLA_ENCODER_WORKERS` sets the width, and 0 encodes on the calling thread.+- **Exporting again is fast when the art has not changed.** The cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.+- **A scene's preload says what each asset type cost it.** Per type it logs how many, their summed load time and the slowest one, and `preloadSceneAssets` returns the same as `timings` and `wallMs`. Bistro on a Windows machine: 132 materials 54 s, 107 textures 47 s and 1505 meshes 45 s of load time over 24 s of wall time.+- **KTX2 textures transcode on worker threads.** On the web and in the editor, one to four of them by the machine's cores, instead of on the main thread. Bistro's assets loaded in 14 s instead of 24 s on a Windows machine, and the page stays responsive while they do. A realm with no workers (a mini-game host) transcodes on the main thread as before, and so does one whose workers fail, which says so once.+- **Web exports pack their small assets into a few files.** Local meshes, materials, KTX2 textures, timelines and animation assets go into a few `packs/*.pack` files, one request each, and the runtime reads each asset out of its pack. A browser holds six connections to a site, so a scene of thousands of small files loaded at the pace of its requests: Bistro's 1505 meshes took 43 s of load time for 0.2 s of upload. Its first frame on a Windows machine went from 15.2 s to 7.3 s, pixel for pixel the same. An export with hot update configured keeps one file per asset, since an update downloads assets one by one; an update that meets a packed asset refuses it by name.+- **Importing a model converts its DDS textures to PNG.** BC1 to BC5 and uncompressed, whether the file sits beside the model or inside an FBX, so a model shipped with DDS art arrives with every map instead of references nothing can load. BC5 normal maps get their Z rebuilt; BC6H and BC7 are named and skipped.+- **An FBX model's specular map can be read as packed ORM.** Occlusion in red, roughness in green, metalness in blue (Specular Map → Packed ORM in its import settings, `--specular-map orm` on the command line), the way scenes authored for Falcor such as Bistro store it. Read as a colour, as before, it has no slot in metal/rough shading and is left out.+- **An FBX material takes its alpha from its base colour image.** FBX has no alpha mode, so an image that is mostly clear where it is not solid imports as a cutout (alpha test 0.5), one that is mostly in between as blended, and one without a real alpha channel stays opaque. A material whose name ends in `.DoubleSided`, as Lumberyard-era exports such as Bistro mark it, draws both sides. Bistro's trees were leaf cards drawn opaque and one-sided — black squares with a few leaves on them.+- **A project file's settings that nothing reads are named instead of dropped.** Opening the project in the editor and exporting from the command line both say which keys of `project.esproject` are ignored, and point a block written at the wrong level (a `rendering` beside `features` rather than inside it) to where it belongs. That misplaced block had left a linear, ACES project running in gamma with no tone curve and no word.+- **A model import says when a map's pixels contradict its slot.** An occlusion map that is zero in every texel is left out with a warning, since it would take all ambient light from the surface, and a map that is one colour throughout is noted.+- **An export warns about a signing key committed with the project.** It says so when a signing key the project names (a quick game's or Android's) sits inside the project and is committed to its repository, or is not ignored and would be committed next.- **Export profiles.** A project can name several exports of one target in `packaging.profiles` — a test and a production WeChat build, each with its own AppID, CDN root and development or shipping configuration, writing only what differs from the project's settings. The Build dialog creates, edits and deletes them per target, marking each setting a profile overrides with a reset that hands it back to the project; `estella export --profile <name>` and the agent's `export_game` build the same one, and the size history records which profile a build used.### Changed@@ -54,7 +55,6 @@ published separately; it ships inside the editor.- On a host that compresses the engine binary (most CDNs and static hosts), the web boot bar no longer runs to the end of the engine download a third of the way through and stands there for the rest of it: the page divided decompressed bytes by the compressed Content-Length. The export now records the binary's own size (`engineBytes` in `game.config.json`) and the bar measures against that.- Project Settings says the start screen's logo is for web exports; a mini-game shows its host's own start screen and loading text.- The Profiler no longer reports a connected build's debug-channel cost as 0 ms when the device's clock is too coarse to measure it — a browser that is not cross-origin isolated steps by 0.1 ms. The device reports its clock's step, the row reads "< 0.100 ms", and `profile_frames` returns it as `channelClockMs`.-- An export warns when a signing key the project names (a quick game's or Android's) sits inside the project and is committed to its repository, or is not ignored and would be committed next.- Opening a project no longer holds the editor behind "Preparing play realm…" for about ten seconds: the play realm's warm-up was being cut off and the editor waited out its deadline. A project now opens in under a second, and the first Play is still warm.- An export from the Build dialog and one from `estella export` now read the project the same way. The dialog's builds keep the engine modules a project includes or excludes, which they ignored; the command line's carry the project's app id (a native package was always `com.estella.game`, so two games replaced each other on a phone), its script entry and scenes folder, its desktop channel and Steam app, and a playable's ad network.- Android's "Android Studio project" and "App Bundle (.aab)" settings take effect: the project file never read them back, so every Android export wrote an APK and nothing else.diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 5beb6d684..683643a3e 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -1185,9 +1185,9 @@ export const NOTED = {'feat(settings): WeChat\'s EmscriptenGLX is a project setting':{ note: '**EmscriptenGLX on WeChat.** A WeChat project can ship the engine linked with WeChat\'s EmscriptenGLX (Project Settings → WeChat → Render through EmscriptenGLX, off by default), which issues the engine\'s GL calls natively instead of through JavaScript: a draw-heavy scene spent about 12% less time rendering on an Android phone. It adds about 310KB of wasm and needs base library 3.8.12 on Android, or iOS in 高性能+ mode; any other host renders through WebGL2 as before, and the log says which. The engine is built once with `node build-tools/cli.js build -t wechat-glx`, which fetches WeChat\'s library at a pinned version and hash, and emsdk 4.0.10 beside the main one; an export that asks for it without it says so.' },'feat(debug): a connected build says which graphics API it draws through':- { note: 'A connected development build says which graphics API it draws through — WebGL2, EmscriptenGLX or WebGPU — once its game has started: the Profiler shows it beside the device\'s controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.' },+ { note: 'A connected development build says which graphics API it draws through' },'feat(profiler): the Profiler shows which graphics API a device draws through':- { note: 'A connected development build says which graphics API it draws through — WebGL2, EmscriptenGLX or WebGPU — once its game has started: the Profiler shows it beside the device\'s controls, the Output Log notes it, and `device_targets` returns it as `graphics`. A WeChat build set to EmscriptenGLX reports WebGL2 on a host that does not offer it.' },+ { note: 'A connected development build says which graphics API it draws through' },'fix(export): a mini-game package draws each atlas sprite as its own frame':{ note: 'A WeChat or other mini-game package draws each sprite from a packed atlas as its own frame again, not as the whole atlas page shrunk into the sprite. The package\'s scenes now keep their `@uuid:` references as the web package does, and a reference by bare uuid finds its atlas frame too.' },'fix(minigame): sprite masks draw in a mini-game package':@@ -1195,9 +1195,9 @@ export const NOTED = {'test(golden): space-shooter is certified on WeChat by the pixels it claims':{ internal: 'A repository golden check; no creator runs it.' },'feat(debug): a connected build answers with the whole frame it composited':- { note: 'A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device\'s own engine. The frame debugger\'s replay shows one pass of a captured frame.' },+ { note: 'A connected development build can be asked for the whole frame it composited' },'feat(agent): device_screenshot shows what a connected build shows its player':- { note: 'A connected development build can be asked for the whole frame it composited — every camera and the UI over them — as the player sees it: `device_screenshot` returns it as a PNG, read back by the device\'s own engine. The frame debugger\'s replay shows one pass of a captured frame.' },+ { note: 'A connected development build can be asked for the whole frame it composited' },'fix(wechat): a WeChat package registers the engine components and AI names again':{ note: 'A WeChat package registers every engine component and the built-in AI names again. The WeChat entries lost their start-up calls to the bundler, so a scene using a component with no typed definition — a rigged model\'s MeshSkin among them — loaded without it ("Unknown component type") and its character was never skinned.' },'fix(ecs): a list field reads back as an array on every read path':@@ -1205,7 +1205,7 @@ export const NOTED = {'fix(import): import-model registers the images a model names on disk':{ note: '`estella import-model` registers the images a model references on disk, so an export ships them. It wrote the materials and prefab that name them and left the images themselves unregistered, and a package built from the command line carried none of its textures.' },'feat(render): KTX2 textures under zstd supercompression decode on web and mini-games':- { note: 'Web and mini-game packages decode KTX2 textures under Zstandard supercompression, as the native host already did. UASTC textures made outside Estella usually are, and every one failed to decode; the transcoder module grows by about 21KB compressed, in packages that carry KTX2.' },+ { note: 'Web and mini-game packages decode Zstandard-supercompressed KTX2' },'refactor(build): the GLX engine adds its exports to the WeChat lists':{ internal: 'The WeChat GLX engine exports the same functions as before; its link flags now extend the WeChat lists instead of restating them.' },'fix(export): the size report reads a Windows path as it reads any other':@@ -1215,25 +1215,25 @@ export const NOTED = {'fix(render): a compressed texture is sampled with the mip chain it carries':{ note: 'Compressed (KTX2) textures on web and mini-games are sampled with their mip chain. The cook has always written one into every texture it compresses, and only level 0 reached the GPU: a compressed texture shimmered as it shrank into the distance, and the rest of its bytes shipped for nothing. A texture decoded to RGBA on a device with no compressed format gets its chain generated.' },'feat(export): an authored single-level KTX2 ships with a mip chain':- { note: 'A KTX2 texture made outside Estella with a single level ships with a mip chain: the cook encodes the levels below it and keeps the file\'s own level 0 byte for byte, so it no longer shimmers into the distance. Bistro\'s 2048² textures each took about 0.3 s; the package grows by the chain\'s third.' },+ { note: 'A single-level KTX2 made outside Estella ships with a mip chain' },'perf(export): the cook reads back a texture encode it already did':- { note: 'Exporting again is fast when the art has not changed: the cook keeps what it encoded under `.esengine/cache/cook/`, keyed by the source, the settings and the encoder. Re-exporting Bistro took 24 s against 131 s the first time.' },+ { note: 'Exporting again is fast when the art has not changed' },'feat(asset): a scene preload reports what each asset type cost':- { note: 'A scene\'s preload logs what each asset type cost it — how many, their summed load time and the slowest one — and `preloadSceneAssets` returns the same as `timings` and `wallMs`. Bistro on a Windows machine: 132 materials 54 s, 107 textures 47 s and 1505 meshes 45 s of load time over 24 s of wall time.' },+ { note: 'A scene\'s preload says what each asset type cost it' },'perf(asset): KTX2 textures transcode on worker threads':- { note: 'KTX2 textures on the web and in the editor transcode on worker threads instead of the main thread, one to four of them by the machine\'s cores. Bistro\'s assets loaded in 14 s instead of 24 s on a Windows machine, and the page stays responsive while they do. A realm with no workers (a mini-game host) transcodes on the main thread as before, and so does one whose workers fail, which says so once.' },+ { note: 'KTX2 textures transcode on worker threads' },'fix(asset): a preload times itself without a platform':{ internal: 'The per-type preload timings landed one commit earlier and never shipped; they read the platform clock, which a realm without a platform (the SDK tests) does not have.' },'feat(asset): the runtime reads an asset out of the pack its export put it in':- { note: 'Web exports pack their small local assets — meshes, materials, KTX2 textures, timelines and animation assets — into a few `packs/*.pack` files, one request each, and the runtime reads each asset out of its pack. A browser holds six connections to a site, so a scene of thousands of small files loaded at the pace of its requests: Bistro\'s 1505 meshes took 43 s of load time for 0.2 s of upload. Its first frame on a Windows machine went from 15.2 s to 7.3 s, pixel for pixel the same. An export with hot update configured keeps one file per asset, since an update downloads assets one by one; an update that meets a packed asset refuses it by name.' },+ { note: 'Web exports pack their small assets into a few files' },'feat(export): a web export packs its small local assets into a few files':- { note: 'Web exports pack their small local assets — meshes, materials, KTX2 textures, timelines and animation assets — into a few `packs/*.pack` files, one request each, and the runtime reads each asset out of its pack. A browser holds six connections to a site, so a scene of thousands of small files loaded at the pace of its requests: Bistro\'s 1505 meshes took 43 s of load time for 0.2 s of upload. Its first frame on a Windows machine went from 15.2 s to 7.3 s, pixel for pixel the same. An export with hot update configured keeps one file per asset, since an update downloads assets one by one; an update that meets a packed asset refuses it by name.' },+ { note: 'Web exports pack their small assets into a few files' },'fix(render): a two-channel normal map lights its surface':{ note: 'Normal maps stored in two channels light correctly. The shader rebuilds Z from X and Y instead of reading blue, so a BC5 map, or one a converter wrote with blue at 0 — every normal map of Bistro\'s glTF conversion — no longer points its surface\'s normals inward, which left normal-mapped surfaces unlit by their sun.' },'feat(import): a model brings its DDS maps as PNG and reads a packed specular map':{ note: 'Importing a model converts its DDS textures to PNG' },'feat(import): a model\'s specular map is read as its import settings say':- { note: 'An FBX model\'s specular map can be read as packed occlusion' },+ { note: 'An FBX model\'s specular map can be read as packed ORM' },'feat(cook): textures encode on every core':{ note: 'Exporting compresses textures on every core' },'fix(render): a double-sided mesh is lit on the side the camera sees':