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
perf(shader): a shader's comments stay out of the binary
esengine4287f59fb680
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex d7bb7e1b3..f1500a072 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -39,8 +39,170 @@ published separately; it ships inside the editor.All three default to what the engine already did, so every scene renders as it did;the criterion that says so runs beside the three that change one field each.+- **A `.psd` file imports.** A layered document is how 2D art is actually authored, and+ the engine could read none of it: the way across was Photoshop's own export, a folder+ of PNGs whose arrangement nothing records, so a character came back as a pile of parts+ to be placed by hand again every time the art changed. A PSD now becomes ordinary+ project files — a PNG per layer and the `.esprefab` that assembles them — so nothing+ downstream has to learn what a PSD is. The parsing is ag-psd's; what the engine owns+ is the translation, the same division the FBX import draws.++- **A sprite states where it sits inside its sorting layer.** A painter layer already+ ordered by transform z, so within one layer the answer was "move it in Z". A+ **Y-sorted** layer drops z from the key entirely, and there the hole had no workaround+ at all: nothing an author could write kept a shadow under its owner or a weapon over+ the hand holding it, except moving the sprite in Y and lying about where it stands.+ `Sprite.order` is the explicit answer and it outranks both — layer, then order, then+ stage, then depth or world Y.++- **A polygon collider takes any ring, concave and unbounded.** Box2D builds only convex+ polygons of at most eight vertices, and that was the COLLIDER's limit too: an authored+ notch was filled in by the hull and a ninth vertex was dropped in silence — the limit+ of a shape standing in for the limit of what an author may draw. A ring is now split+ into convex pieces that each fit, every piece a shape on the same body.++- **An `.aseprite` file imports.** Aseprite is where most pixel art is drawn, and its+ documents are frames and tags — "walk is 1 to 6, and it ping-pongs" — where a PSD is+ a stack. Bringing one into a project meant exporting a sheet by hand, typing the cell+ size into the texture's settings, and then re-typing each tag's range as a clip; three+ transcriptions of facts the file already carried, all of them stale the next time the+ artist added a frame.++ Dropping one in now writes the composited sheet and one `.esanim` per tag beside it,+ with each frame's own duration, the direction the tag states (a ping-pong turns around+ on its ends rather than repeating them), and the anchor of a slice that carries a+ pivot. Re-importing is the same door, so an edited file reaches the game by saving it.++ The frame composite is the artwork: layers exist so the artist can work, and what+ plays is what they see — so the stack collapses at import, with every blend mode the+ format can store, the group switches that hide what is inside them, and linked cels+ resolved. A tilemap layer is drawn from a tileset rather than from pixels and says so+ instead of arriving blank.++ The sheet arrives asking for `nearest` filtering and no GPU compression, which is the+ one kind of image where both defaults are wrong: a bilinear filter blurs the pixels+ the artist placed, and a lossy format invents colours a small palette does not have.+ Its cell grid is re-derived on every import — a resized canvas that kept the old cell+ size would leave every cell index in the project pointing at the wrong pixels — while+ the filter and the compression stay whatever the project set them to.++- **A polygon collider can take the sprite's own silhouette.** Drawing a collider+ around art by hand is the one authoring step where the answer is already in the+ file: the artist drew the shape, and every vertex placed by eye is a chance to+ disagree with it. Trace Collider From Sprite — on the component and in the palette+ — traces the outer boundary of the opaque region, simplifies it, and writes the+ ring. What Box2D does with a concave ring was settled when polygon colliders+ learned to partition; this only had to produce one.++ Holes and separate islands are deliberately not traced. They are not a coarser+ version of this answer but a different component count, which is the author's+ decision rather than a trace's.++- **A texture's geometry is one picture.** The 9-slice border had a canvas in the+ asset inspector — drag the guides on the sprite — and the sheet grid, added+ alongside it, had four numbers in a list. A grid is the case where numbers are+ least sufficient: `cellWidth` is easy to type and impossible to check without+ seeing the cells land on the art. The canvas draws both now, and is named for+ what it is rather than for one of the two.++ Where the cells fall is not decided there. `sheetGrid` in the SDK is the one+ author of that and the runtime cuts by the same function, so a grid that reads+ right in the inspector cannot cut differently at load — the editor only carries+ the cells across the letterbox fit the border is already drawn through.++- **A sprite can be cut by another sprite's shape.** 2D needed a hole and had no way to+ make one: a blood bar that fills, a torch clearing fog, a character seen through a+ window. `SpriteMask` turns an entity's OWN `Sprite` into the stencil — not a second+ texture field on a mask component, because everything a mask shape needs (texture,+ size, pivot, flips, 9-slice) the sprite already says, and a second one is a second+ thing to keep in step with what the author sees. While it is masking, the mask's+ sprite is not drawn; turning it off puts the picture back, which is what makes+ "is this masking?" answerable by looking.++ Cutting is opt-in per sprite (`Sprite.maskInteraction`: `VisibleInside` for a window,+ `VisibleOutside` for a hole), so a mask added to a scene can never make an unrelated+ sprite vanish.++ Reach is a RANGE, not a subtree. What a 2D mask cuts is rarely its own children — fog+ belongs to no part of the torch clearing it — so a mask reaches the sprites drawn+ after it, in the order the author already arranges by layer and order. That is also+ the order its stencil is written in, so nothing had to be added to the sort key to+ make the mask come first; a sprite at the mask's exact layer AND order is not cut at+ all, because those two have no order between them. `UIMask` keeps the subtree rule,+ because a UI tree IS its containment.++ `GfxStencilMode` gains `TestOutside` (compare NotEqual) on both backends — the engine+ could only ever test INSIDE a stencil, so a hole was not expressible. The state flags+ now resolve to a mode through one function rather than in each caller's words: the+ first version of that mapping had no criterion over it, and sabotage proved it —+ ignoring the outside bit entirely left every test green.++ The stencil clears on the same terms as depth, which it shares an attachment with. A+ frame keeping the last one's stencil cuts along a mask that has since moved.++ The reach rule is a pure header (`SpriteMaskRange.hpp`) held by `test_sprite_mask_range`,+ because a frame can show that SOME mask won and never which one the rule chose. Four+ sabotages, each reddening its own case: reaching backwards, choosing the farthest mask+ instead of the nearest, ignoring a stated range, and picking a mask that never got a+ stencil ref — which would test ref 0, every unmasked pixel in the frame.++ What a frame CAN show is held by the `sprite-mask` pixel scene: one mask, both its+ sides, and a bar that never asked to be cut. Dropping the resolver paints the frame+ red; mapping `TestOutside` to Equal leaves the right half black. An editor check+ carries it the rest of the way — through the scene file, the reconciler and the Add+ Component list — and asks what no picture can: that the component can be added at+ all, and that its range fields stay hidden until `limitRange` turns them on. And `space-shooter`+ now draws its hull as one, because a capability no game has called is a promise with+ nothing behind it — the fill is cut rather than scaled, so the art never stretches+ with the number, and the lost segment is the same mask's other side.++- **A subtree can sort as one unit.** `sprite.order` is a promise about one sprite+ against everything else in its layer, and that stops scaling the moment two+ assembled characters overlap: raising a weapon over the other character raises it+ over its own body too, and the only way out was globally unique orders across every+ entity that might ever meet. `SortingGroup` states the layer and order a whole+ subtree presents outward, and each member's own order becomes its place INSIDE the+ group — so nothing outside can land between two members, which is the one thing a+ per-sprite order cannot offer.++ The group takes over everything DERIVED from a layer, not just the key: the camera's+ culling bit and the layer's ordering rule are asked of the group's layer too.+ Leaving either on the member y-sorts a group through one sprite and not the next.++ Groups nest, and an inner one does not start a fresh identity — a weapon prefab+ rigged under an arm would drift out of the character. It becomes one BLOCK in the+ outer group instead, so it stays whole wherever the arm goes.++ Where the member's order LIVES is the whole design. The group owns the key's top+ fields, so the member needs the highest field left, and it must be the same field in+ every packing or two members of one group are incomparable — a group holds an opaque+ prop under a blended character. [37:30] is the only field directly under stage in all+ three layouts, and it is stamped there after the fact, which costs nothing outside a+ group and inside one replaces a projection (depth, shader, world Y) the author's+ order was overriding anyway.++ Held at four levels, each watched failing first: the bit layout in a new header-only+ `test_sort_key` harness, the draw path's resolution in `test_batch_builder`, the+ editor's picking — which mirrors all of this in `layerOrder.ts`, or a click selects+ what the person cannot see — and an editor check on real pixels, where a member whose+ own layer would put it on top is drawn underneath and a click agrees. Two of the engine cases were TRIVIALLY satisfied when+ first written (a stated order outranks both depth and world Y, so it cannot be what+ makes two layer rules disagree) and were rebuilt until sabotage reddened them.+### Fixed+- **Opening a project no longer strands the loading overlay.** Two callers arm the+ project-open gate — the entry seam that reveals the shell, and the effect that runs the+ work — and only one of them joined an attempt already in flight. Open a project and+ then enter the editor, the order automation uses, and the gate was left on a ticket+ nobody owned: nothing could settle it, and the only safety timer belonged to the+ attempt it had replaced. The overlay never lifted.++- **A shader's comments stay out of the binary.** A third of the engine's embedded+ shader source was comment — ten kilobytes of prose riding into every game, and into a+ playable's single file where the budget is 2MB. Comment lines are emptied at embed+ time rather than removed, so a shader's diagnostics still name the line they came from.+- **A WGSL twin no longer declares the engine's own texture bindings.** A twin thatwrites its own vertex stage had to spell out every `tN`/`sN` it touched — a conventionthe engine owns, where forgetting one is an invalid pipeline that mentions no shader.@@ -107,6 +269,15 @@ published separately; it ships inside the editor.in it — the mask is screen space, so what a fragment reads has to be the part of it itsown camera filled.+- **A polygon collider is drawn as the polygon it collides as.** The overlay drew the+ authored ring while the solver saw the pieces it was split into, so the two disagreed+ exactly where an author would look to find out why.++- **A ring of more than eight points keeps its collider.** A twelve-point ring whose+ first eight are collinear — what the editor's insert makes of one edge subdivided+ repeatedly — decomposed into no pieces at all, and the collider silently ceased to+ exist.+### Changed- **2D shadows are drawn, not solved.** A 2D shadow used to be an analytic test inside@@ -174,138 +345,6 @@ published separately; it ships inside the editor.`GradientStop` is deliberately NOT folded in: a colour stop is not a scalar key, andone shape for both would be a name over two things.--### Added--- **An `.aseprite` file imports.** Aseprite is where most pixel art is drawn, and its- documents are frames and tags — "walk is 1 to 6, and it ping-pongs" — where a PSD is- a stack. Bringing one into a project meant exporting a sheet by hand, typing the cell- size into the texture's settings, and then re-typing each tag's range as a clip; three- transcriptions of facts the file already carried, all of them stale the next time the- artist added a frame.-- Dropping one in now writes the composited sheet and one `.esanim` per tag beside it,- with each frame's own duration, the direction the tag states (a ping-pong turns around- on its ends rather than repeating them), and the anchor of a slice that carries a- pivot. Re-importing is the same door, so an edited file reaches the game by saving it.-- The frame composite is the artwork: layers exist so the artist can work, and what- plays is what they see — so the stack collapses at import, with every blend mode the- format can store, the group switches that hide what is inside them, and linked cels- resolved. A tilemap layer is drawn from a tileset rather than from pixels and says so- instead of arriving blank.-- The sheet arrives asking for `nearest` filtering and no GPU compression, which is the- one kind of image where both defaults are wrong: a bilinear filter blurs the pixels- the artist placed, and a lossy format invents colours a small palette does not have.- Its cell grid is re-derived on every import — a resized canvas that kept the old cell- size would leave every cell index in the project pointing at the wrong pixels — while- the filter and the compression stay whatever the project set them to.--- **A polygon collider can take the sprite's own silhouette.** Drawing a collider- around art by hand is the one authoring step where the answer is already in the- file: the artist drew the shape, and every vertex placed by eye is a chance to- disagree with it. Trace Collider From Sprite — on the component and in the palette- — traces the outer boundary of the opaque region, simplifies it, and writes the- ring. What Box2D does with a concave ring was settled when polygon colliders- learned to partition; this only had to produce one.-- Holes and separate islands are deliberately not traced. They are not a coarser- version of this answer but a different component count, which is the author's- decision rather than a trace's.--- **A texture's geometry is one picture.** The 9-slice border had a canvas in the- asset inspector — drag the guides on the sprite — and the sheet grid, added- alongside it, had four numbers in a list. A grid is the case where numbers are- least sufficient: `cellWidth` is easy to type and impossible to check without- seeing the cells land on the art. The canvas draws both now, and is named for- what it is rather than for one of the two.-- Where the cells fall is not decided there. `sheetGrid` in the SDK is the one- author of that and the runtime cuts by the same function, so a grid that reads- right in the inspector cannot cut differently at load — the editor only carries- the cells across the letterbox fit the border is already drawn through.--- **A sprite can be cut by another sprite's shape.** 2D needed a hole and had no way to- make one: a blood bar that fills, a torch clearing fog, a character seen through a- window. `SpriteMask` turns an entity's OWN `Sprite` into the stencil — not a second- texture field on a mask component, because everything a mask shape needs (texture,- size, pivot, flips, 9-slice) the sprite already says, and a second one is a second- thing to keep in step with what the author sees. While it is masking, the mask's- sprite is not drawn; turning it off puts the picture back, which is what makes- "is this masking?" answerable by looking.-- Cutting is opt-in per sprite (`Sprite.maskInteraction`: `VisibleInside` for a window,- `VisibleOutside` for a hole), so a mask added to a scene can never make an unrelated- sprite vanish.-- Reach is a RANGE, not a subtree. What a 2D mask cuts is rarely its own children — fog- belongs to no part of the torch clearing it — so a mask reaches the sprites drawn- after it, in the order the author already arranges by layer and order. That is also- the order its stencil is written in, so nothing had to be added to the sort key to- make the mask come first; a sprite at the mask's exact layer AND order is not cut at- all, because those two have no order between them. `UIMask` keeps the subtree rule,- because a UI tree IS its containment.-- `GfxStencilMode` gains `TestOutside` (compare NotEqual) on both backends — the engine- could only ever test INSIDE a stencil, so a hole was not expressible. The state flags- now resolve to a mode through one function rather than in each caller's words: the- first version of that mapping had no criterion over it, and sabotage proved it —- ignoring the outside bit entirely left every test green.-- The stencil clears on the same terms as depth, which it shares an attachment with. A- frame keeping the last one's stencil cuts along a mask that has since moved.-- The reach rule is a pure header (`SpriteMaskRange.hpp`) held by `test_sprite_mask_range`,- because a frame can show that SOME mask won and never which one the rule chose. Four- sabotages, each reddening its own case: reaching backwards, choosing the farthest mask- instead of the nearest, ignoring a stated range, and picking a mask that never got a- stencil ref — which would test ref 0, every unmasked pixel in the frame.-- What a frame CAN show is held by the `sprite-mask` pixel scene: one mask, both its- sides, and a bar that never asked to be cut. Dropping the resolver paints the frame- red; mapping `TestOutside` to Equal leaves the right half black. An editor check- carries it the rest of the way — through the scene file, the reconciler and the Add- Component list — and asks what no picture can: that the component can be added at- all, and that its range fields stay hidden until `limitRange` turns them on. And `space-shooter`- now draws its hull as one, because a capability no game has called is a promise with- nothing behind it — the fill is cut rather than scaled, so the art never stretches- with the number, and the lost segment is the same mask's other side.--- **A subtree can sort as one unit.** `sprite.order` is a promise about one sprite- against everything else in its layer, and that stops scaling the moment two- assembled characters overlap: raising a weapon over the other character raises it- over its own body too, and the only way out was globally unique orders across every- entity that might ever meet. `SortingGroup` states the layer and order a whole- subtree presents outward, and each member's own order becomes its place INSIDE the- group — so nothing outside can land between two members, which is the one thing a- per-sprite order cannot offer.-- The group takes over everything DERIVED from a layer, not just the key: the camera's- culling bit and the layer's ordering rule are asked of the group's layer too.- Leaving either on the member y-sorts a group through one sprite and not the next.-- Groups nest, and an inner one does not start a fresh identity — a weapon prefab- rigged under an arm would drift out of the character. It becomes one BLOCK in the- outer group instead, so it stays whole wherever the arm goes.-- Where the member's order LIVES is the whole design. The group owns the key's top- fields, so the member needs the highest field left, and it must be the same field in- every packing or two members of one group are incomparable — a group holds an opaque- prop under a blended character. [37:30] is the only field directly under stage in all- three layouts, and it is stamped there after the fact, which costs nothing outside a- group and inside one replaces a projection (depth, shader, world Y) the author's- order was overriding anyway.-- Held at four levels, each watched failing first: the bit layout in a new header-only- `test_sort_key` harness, the draw path's resolution in `test_batch_builder`, the- editor's picking — which mirrors all of this in `layerOrder.ts`, or a click selects- what the person cannot see — and an editor check on real pixels, where a member whose- own layer would put it on top is drawn underneath and a click agrees. Two of the engine cases were TRIVIALLY satisfied when- first written (a stated order outranks both depth and world Y, so it cannot be what- makes two layer rules disagree) and were rebuilt until sabotage reddened them.--## [0.63.0] - 2026-09-10### Addeddiff --git a/build-tools/tasks/shader-embeds.js b/build-tools/tasks/shader-embeds.jsindex 949a1f48f..7b950b6d0 100644--- a/build-tools/tasks/shader-embeds.js+++ b/build-tools/tasks/shader-embeds.js@@ -13,6 +13,16 @@ function toCppIdentifier(filename) {.replace(/[^A-Z0-9]/g, '_');}+/**+ * A whole-line comment carries nothing a player's GPU can use, and a third of the+ * engine's shader source is comment — bytes that ride the binary into every game.+ * Emptied, not removed: diagnostics are remapped to `.esshader` line numbers, so+ * dropping a line would move every error message after it.+ */+function stripComments(source) {+ return source.split('\n').map((line) => (line.trimStart().startsWith('//') ? '' : line)).join('\n');+}+export async function generateShaderEmbeds() {const rootDir = config.paths.root;const shadersDir = path.join(rootDir, 'src/esengine/data/shaders');@@ -39,7 +49,7 @@ export async function generateShaderEmbeds() {for (const file of files) {const content = await readFile(path.join(shadersDir, file), 'utf-8');const id = toCppIdentifier(file);- lines.push(`inline constexpr const char* ${id} = R"esshader(${content})esshader";`);+ lines.push(`inline constexpr const char* ${id} = R"esshader(${stripComments(content)})esshader";`);lines.push('');}diff --git a/desktop b/desktopindex e07acb39e..ebf6dfaf1 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit e07acb39ebd1494504bf1ea7b1095e35d93cd5ad+Subproject commit ebf6dfaf156704557e31f7b24e9cd79e871b8f01diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hppindex 7058d428a..7f777d843 100644--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp@@ -5,20 +5,20 @@ namespace esengine::ShaderEmbeds {inline constexpr const char* BATCH = R"esshader(#pragma shader "Batch"#pragma version 300 es-// Compile-time variant: when enabled the fragment stage treats the sampled-// alpha as a signed distance field (runtime glyph atlas) and-// derives crisp, resolution-independent coverage instead of sampling RGBA.+++#pragma feature SDF-// Compile-time variant: lit by the scene's 2D lights (Sprite.lit). Compiled as a-// Lit-domain shader, so applyLighting2D + LightConstants are injected.++#pragma feature LIT-// Compile-time variant: discard fragments the sprite draws as (near-)transparent.-// Selected for a STENCIL MASK draw, which runs this shader with color writes off:-// without the discard every transparent corner of the quad still writes stencil,-// so a circular mask sprite would clip a rectangle. Off for ordinary sprites, so-// they keep an unconditional (early-Z friendly) fragment path.+++++#pragma feature ALPHA_CLIP#pragma vertex@@ -55,8 +55,8 @@ void main() {#pragma end#pragma fragment-// highp: the SDF text branch needs precise distance + fwidth derivatives, and-// sprite sampling is unaffected by the wider range.++precision highp float;in vec4 v_color;@@ -69,9 +69,9 @@ in float v_sdfBias;in highp vec2 v_worldPos;#endif-// Up to 8 textures bound per multi-texture batch. GLSL ES 3.00 forbids indexing a-// sampler array with a non-uniform expression, so the slot is selected by a constant-// branch chain (the standard WebGL2 multi-texture batching technique).+++uniform sampler2D u_textures[8];out vec4 fragColor;@@ -87,32 +87,32 @@ void main() {else if (v_texIndex == 6) texColor = texture(u_textures[6], v_texCoord);else texColor = texture(u_textures[7], v_texCoord);#ifdef ES_LINEAR- // Vertex colors are authored sRGB; the sampled texel is already linear- // (sRGB texture formats decode in hardware). Alpha is coverage — never encoded.++vec4 tint = vec4(srgbToLinear(v_color.rgb), v_color.a);#elsevec4 tint = v_color;#endif#ifdef SDF- // The glyph atlas stores a signed distance in the alpha channel (RGB = 1).- // Distance ÷ fwidth = screen px from the edge; the ±0.5px clamp is exactly- // one pixel of linear coverage ramp (the msdfgen standard).- // v_sdfBias moves the edge outward before the ramp, which grows the glyph's- // own shape by that many distance units — an outline pass draws the same- // quads with it raised and its colour in the vertices.++++++float dist = texColor.a;float screenPxDist = (dist - 0.5 + v_sdfBias) / max(fwidth(dist), 1e-6);float coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);fragColor = vec4(tint.rgb, tint.a * coverage);#elif defined(LIT)- // Flat normal; the tinted color is the albedo. Normal maps need a material.+vec4 base = texColor * tint;fragColor = vec4(applyLighting2D(base.rgb, vec3(0.0, 0.0, 1.0), v_worldPos), base.a);#else#ifdef ALPHA_CLIP- // The SPRITE's alpha, not the tinted result: a mask graphic is routinely- // tinted to near-zero alpha so it masks without being seen, and testing the- // tinted value would discard the whole mask and clip everything away.+++if (texColor.a < 0.5) discard;#endiffragColor = texColor * tint;@@ -190,8 +190,8 @@ struct VSOut {#endif};-// textureSampleLevel(…, 0) keeps sampling uniform-flow-legal inside the-// constant branch chain; 2D sprites sample mip 0.++@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {let idx = i32(v.v_texIndex + 0.5);var texColor : vec4f;@@ -209,8 +209,8 @@ struct VSOut {let tint = v.v_color;#endif#ifdef SDF- // Same coverage math as the GLSL stage; fwidth here is in uniform control- // flow (main scope), which WGSL requires of derivative builtins.++let dist = texColor.a;let screenPxDist = (dist - 0.5 + v.v_sdfBias) / max(fwidth(dist), 1e-6);let coverage = clamp(screenPxDist + 0.5, 0.0, 1.0);@@ -220,7 +220,7 @@ struct VSOut {return vec4f(applyLighting2D(base.rgb, vec3f(0.0, 0.0, 1.0), v.v_worldPos), base.a);#else#ifdef ALPHA_CLIP- // See the GLSL stage: test the sprite's alpha, not the tinted result.+if (texColor.a < 0.5) { discard; }#endifreturn texColor * tint;@@ -243,14 +243,14 @@ out vec4 fragColor;void main() {vec4 c = texture(u_texture, v_texCoord);#ifdef ES_TONEMAP- // The output transform: scene radiance can exceed 1.0 on an HDR target,- // and this is the one place a chain maps it down. Before the OETF, which- // is a transfer function and not a look.+++c = vec4(acesFilmic(c.rgb), c.a);#endif#ifdef ES_LINEAR- // The one mandatory OETF: the chain upstream is linear (sRGB attachments- // decode on sample), the canvas backbuffer is plain UNORM.++fragColor = vec4(linearToSrgb(c.rgb), c.a);#elsefragColor = c;@@ -276,12 +276,12 @@ void main() {inline constexpr const char* LIGHTSHAPE2D = R"esshader(#pragma shader "LightShape2D"#pragma version 300 es-// The 2D light-shape mask: one channel per shaped light, carrying what that light's-// own cookie covers. A quad per light, drawn where the light is and turned with it,-// so a lantern's glow is the shape the artist drew rather than a circle.-//-// One draw per light rather than one for all four: each carries its own texture, and-// a channel it does not name receives zero — which reads as "this light is not here".++++++#pragma vertexlayout(location = 0) in vec2 a_position;@@ -309,8 +309,8 @@ uniform sampler2D u_cookie;out vec4 fragColor;void main() {- // Alpha alone: the shape is what the artist drew the edge of, and a colour here- // would be a second place a light's colour comes from.++fragColor = v_channel * texture(u_cookie, v_texCoord).a;}#pragma end@@ -351,43 +351,43 @@ struct VSOut {inline constexpr const char* MESH = R"esshader(#pragma shader "Mesh"#pragma version 300 es-// Lit domain for the LIGHTING it injects (LightConstants + applyLighting2D),-// not for its canonical vertex stage — that is only supplied to a shader which-// writes none, and this one writes its own to place local vertices by a model-// matrix. So the light math is shared with every 2D lit surface rather than-// copied, and the std140 block stays the engine's to own.+++++#pragma domain Lit-// What the GEOMETRY carries. A layout may not declare an attribute its shader-// does not consume, so the normal channel and the per-object normal matrix are-// inside this switch on both sides — whether or not the draw asks to be lit.+++#pragma feature MESH_NORMALS-// What the DRAW asks for. Orthogonal to the above on purpose: geometry with-// normals can be drawn unlit, and geometry without them can still take light-// (off a constant normal, which is what a 2D surface has).+++#pragma feature LIT-// Geometry deformed by joints. Its own transform is NOT read: a skinned mesh's-// node placement is ignored (glTF requires it) because the bones are already-// world-space, so the per-object record carries only a tint.+++#pragma feature SKINNED-// A normal map on top of those normals. Its tangent frame comes from the shared-// perturbNormal (screen-space derivatives), so the geometry needs no tangent-// channel — which is why this rides LIT rather than a vertex attribute.+++#pragma feature NORMAL_MAP-// The shadow-map pass: the same geometry, from the light, writing depth as colour-// instead of shading. A feature and not a second shader, because what has to be-// identical between the two passes is the VERTEX stage — a skinned occluder must-// land where its skinned self lands, and one copy of that is one that cannot drift.++++#pragma feature SHADOW_DEPTH-// GPU-resident geometry. Slot 0 is the mesh's own vertices, which are LOCAL-// space and are never rewritten; slot 1 is the per-object record the frame-// streams, so the same mesh drawn twice costs one more transform rather than-// one more copy of its vertices.++++#pragma vertexlayout(location = 0) in vec3 a_position;@@ -401,8 +401,8 @@ layout(location = 5) in uvec4 a_joints;layout(location = 6) in vec4 a_weights;#endif-// 8.. and not 3..: a channel's semantic IS its location, so adding normals to a-// mesh must not move the per-object record (see MESH_INSTANCE_FIRST_LOCATION).++#ifndef SKINNEDlayout(location = 8) in vec4 a_model0;layout(location = 9) in vec4 a_model1;@@ -411,16 +411,16 @@ layout(location = 11) in vec4 a_model3;#endiflayout(location = 12) in vec4 a_instTint;#if defined(MESH_NORMALS) && !defined(SKINNED)-// The normal matrix (inverse transpose of the model's 3x3), per object: under a-// non-uniform scale the model matrix skews a normal, and inverting one per-// vertex is the alternative.+++layout(location = 13) in vec3 a_nrm0;layout(location = 14) in vec3 a_nrm1;layout(location = 15) in vec3 a_nrm2;#endif#ifdef SKINNED-// This draw's pose, rewritten immediately before it (SkinConstants, binding 5).+layout(std140) uniform SkinConstants {mat4 u_bones[64];};@@ -430,24 +430,24 @@ out vec2 v_texCoord;out vec4 v_color;#ifdef LITout highp vec3 v_worldNormal;-// The full position, not just the plane's: a tangent frame is derived from how-// it changes across a fragment, which xy alone cannot say for a tilted surface.++out highp vec3 v_worldPos;#endif#ifdef SHADOW_DEPTH-// The clip position, and not the depth it divides down to. z/w is not affine across a-// triangle, so a stage that divides here hands the fragment an interpolation of the-// corners' quotients rather than the quotient at the fragment — off by more, the wider-// the depth range one triangle spans. An orthographic map never showed it (w is 1-// throughout), and a cube face looking along a floor is the case that does: the error-// there is worth several world units, which shadows the caster against itself.++++++out highp vec4 v_shadowClip;#endifvoid main() {#ifdef SKINNED- // The four bones this vertex is bound to, blended by their weights. The- // result is world-space, so no model matrix follows it.++mat4 skin = a_weights.x * u_bones[a_joints.x]+ a_weights.y * u_bones[a_joints.y]+ a_weights.z * u_bones[a_joints.z]@@ -469,7 +469,7 @@ void main() {#elif defined(MESH_NORMALS)v_worldNormal = mat3(a_nrm0, a_nrm1, a_nrm2) * a_normal;#else- // A surface with no normal channel faces the viewer, exactly as a sprite does.+v_worldNormal = vec3(0.0, 0.0, 1.0);#endifv_worldPos = world.xyz;@@ -499,9 +499,9 @@ out vec4 fragColor;void main() {#ifdef SHADOW_DEPTH- // The expression the receiver evaluates on u_shadowMatrix, evaluated here on the- // same matrix and at the same point: whatever each backend's clip z means, both- // sides mean it alike.+++fragColor = vec4(packDepth(clamp(v_shadowClip.z / v_shadowClip.w * 0.5 + 0.5,0.0, 1.0)), 1.0);#else@@ -511,10 +511,10 @@ void main() {#ifdef NORMAL_MAPN = perturbNormal(N, v_worldPos, v_texCoord, sampleNormal(u_normalMap, v_texCoord));#endif- // A rough dielectric, and the position it really has: a shadow is cast on a- // point in space, and xy is not one. Specular stays ON — switching it off is- // not a cheaper PBR, it is a different surface, and a mesh whose material- // says nothing must still be lit the way the same mesh out of a glTF is.++++fragColor = vec4(applyLightingPBR(base.rgb, N, v_worldPos, viewDirection(v_worldPos),0.0, 1.0, 1.0, 1.0), base.a);#else@@ -564,15 +564,15 @@ struct VSOut {@location(3) v_worldPos : vec3f,#endif#ifdef SHADOW_DEPTH- // The clip position, not the depth it divides down to — see the GLSL twin.+@location(4) v_shadowClip : vec4f,#endif};@vertex fn vs_main(v : VSIn) -> VSOut {#ifdef SKINNED- // The four bones this vertex is bound to, blended by their weights. The- // result is world-space, so no model matrix follows it.++let pose = v.a_weights.x * skin.bones[v.a_joints.x]+ v.a_weights.y * skin.bones[v.a_joints.y]+ v.a_weights.z * skin.bones[v.a_joints.z]@@ -598,7 +598,7 @@ struct VSOut {out.v_worldNormal = mat3x3f(v.a_nrm0, v.a_nrm1, v.a_nrm2) * v.a_normal;#endif#else- // A surface with no normal channel faces the viewer, exactly as a sprite does.+out.v_worldNormal = vec3f(0.0, 0.0, 1.0);#endifout.v_worldPos = world.xyz;@@ -615,20 +615,20 @@ struct VSOut {@group(1) @binding(9) var s1 : sampler;#endif#ifdef ES_RECEIVE_SHADOW-// The shadow map, on the slot the injected header samples. A fragment-only twin-// gets these from the batch texture contract; one that writes its own says so.++@group(1) @binding(2) var t2 : texture_2d<f32>;@group(1) @binding(10) var s2 : sampler;#endif#ifdef ES_ENV_MAP-// The environment's reflection, one slot on. Same reason as above — and without-// it the injected sampler names an identifier this twin never declared, which-// reaches anyone as an invalid pipeline that does not mention a shader.+++@group(1) @binding(3) var t3 : texture_2d<f32>;@group(1) @binding(11) var s3 : sampler;#endif-// The 2D shadow mask, on the top slot. Unconditional, because the injected-// lighting reads it for every Lit shader rather than behind a feature.++@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;@@ -647,9 +647,9 @@ struct VSOut {@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {#ifdef SHADOW_DEPTH- // The expression the receiver evaluates on u_shadowMatrix, evaluated here on the- // same matrix and at the same point: whatever each backend's clip z means, both- // sides mean it alike.+++return vec4f(packDepth(clamp(v.v_shadowClip.z / v.v_shadowClip.w * 0.5 + 0.5,0.0, 1.0)), 1.0);#else@@ -659,10 +659,10 @@ struct VSOut {#ifdef NORMAL_MAPN = perturbNormal(N, v.v_worldPos, v.v_texCoord, sampleNormal(t1, s1, v.v_texCoord));#endif- // A rough dielectric, and the position it really has: a shadow is cast on a- // point in space, and xy is not one. Specular stays ON — switching it off is- // not a cheaper PBR, it is a different surface, and a mesh whose material- // says nothing must still be lit the way the same mesh out of a glTF is.++++return vec4f(applyLightingPBR(base.rgb, N, v.v_worldPos, viewDirection(v.v_worldPos),0.0, 1.0, 1.0, 1.0), base.a);#else@@ -676,10 +676,10 @@ struct VSOut {inline constexpr const char* PARTICLE = R"esshader(#pragma shader "ParticleInstance"#pragma version 300 es-// Fragment-only, on the engine's canonical vertex stage under the PARTICLE-// feature: what turns instance data into a billboarded quad is the same stage a-// material is compiled against, so a custom particle material and this one are-// posed by one piece of arithmetic rather than two kept in step.++++#pragma fragmentprecision mediump float;@@ -696,8 +696,8 @@ void main() {}#pragma end-// VSOut and the t0/s0 texture contract are injected for a twin on the engine's-// vertex stage — declaring them here would declare them twice.++#pragma fragment wgsl@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {let texColor = textureSampleLevel(t0, s0, v.v_texCoord, 0.0);@@ -709,14 +709,14 @@ void main() {inline constexpr const char* SHADOW2D = R"esshader(#pragma shader "Shadow2D"#pragma version 300 es-// The 2D shadow mask: one channel per light that casts, drawn as the region each-// occluder's silhouette hides from it. The pass ADDS, which is what makes a-// source with width soft: its silhouette is drawn once per sample across the-// source, and a fragment collects a share for every sample hidden from it.-//-// `a_shadow` is the share this piece of geometry hides. `a_channel` is the-// light's own channel as a one-hot vector, which lets every light ride in one-// draw: the channels a vertex does not name receive zero.++++++++#pragma vertexlayout(location = 0) in vec2 a_position;@@ -904,13 +904,13 @@ inline constexpr const char* SKY = R"esshader(#pragma shader "Sky"#pragma version 300 es#pragma domain Lit-// The background half of an environment. The reflection in a metal ball and the-// sky behind it are the same baked panorama; without this only one of them was-// ever visible, and a scene lit by a sky sat in front of a flat clear colour.-//-// Geometry is a quad on the far plane, so the vertex stage needs no matrix of its-// own — the fragment's direction is the one from the eye through it, which is-// what viewDirection() already answers (negated: it points AT the viewer).+++++++#pragma vertexlayout(location = 0) in vec3 a_position;@@ -930,8 +930,8 @@ in highp vec3 v_worldPos;out vec4 fragColor;void main() {- // Mip 0: the sharpest level of the prefiltered atlas is the sky as it was- // photographed. The rougher ones exist to be reflected, not to be looked at.++fragColor = vec4(envSampleMip(-viewDirection(v_worldPos), 0.0), 1.0);}#pragma end@@ -954,21 +954,21 @@ struct VSOut {#pragma end#pragma fragment wgsl-// Slot 0 is bound and never read — a draw fills it so the walk that pins the-// atlas one slot on has somewhere to start. The atlas itself is on 3, and-// without these two the injected sampler names identifiers this twin never-// declared: an invalid pipeline that does not mention a shader.++++@group(1) @binding(0) var t0 : texture_2d<f32>;@group(1) @binding(8) var s0 : sampler;@group(1) @binding(3) var t3 : texture_2d<f32>;@group(1) @binding(11) var s3 : sampler;-// The 2D shadow mask, which the injected lighting reads for every Lit shader.+@group(1) @binding(7) var t7 : texture_2d<f32>;@group(1) @binding(15) var s7 : sampler;-// Declared again: each WGSL block is compiled on its own, so a struct defined in-// the vertex one is an undeclared name here — and that reaches anyone as an-// invalid pipeline with nothing in the log about a shader.+++struct VSOut {@builtin(position) pos : vec4f,@location(0) v_worldPos : vec3f,