lecodes-cli 0.20.2 → 2.0.0

package/package.json

@@ -1,23 +1,26 @@
 {
   "name": "lecodes-cli",
-  "version": "0.20.2",
+  "version": "2.0.0",
   "dependencies": {
-    "@letary/chisel": "^0.10.0",
+    "@letary/chisel": "^0.13.0",
     "jimp": "^1.6.1",
-    "lecodes-sdk": "0.20.2"
+    "lecodes-sdk": "2.0.0"
   },
   "devDependencies": {
     "lecodes-design": "^0.9.0",
-    "lecodes-renderer": "0.20.2",
+    "lecodes-headless": "2.0.0",
     "qrcode-terminal": "^0.12.0",
     "lecodes-3d-editor": "^0.7.0",
     "lecodes-assets": "0.2.1",
     "lecodes-creator-nav": "0.19.0",
-    "lecodes-viewer-lite": "0.20.2"
+    "lecodes-gl-lite": "2.0.0",
+    "lecodes-web-frame": "2.0.0",
+    "lecodes-web-player": "2.0.0",
+    "lecodes-web-shared": "2.0.0"
   },
   "peerDependencies": {
     "lecodes-design": "^0.9.0",
-    "lecodes-renderer": "^0.20.2",
+    "lecodes-headless": "^2.0.0",
     "lecodes-3d-editor": "^0.7.0",
     "lecodes-assets": "^0.2.1"
   },
@@ -43,7 +46,7 @@
     "lecodes-design": {
       "optional": true
     },
-    "lecodes-renderer": {
+    "lecodes-headless": {
       "optional": true
     },
     "lecodes-3d-editor": {
@@ -57,9 +60,12 @@
     "icon": "bun scripts/make-icon.ts",
     "vendor-runtime": "bun scripts/vendor-runtime.ts",
     "sync-peers": "bun scripts/sync-peer-versions.ts",
-    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-renderer --external lecodes-design --external lecodes-3d-editor --external lecodes-assets --banner=\"#!/usr/bin/env node\"",
+    "build": "bun scripts/vendor-runtime.ts && bun build src/index.ts --target=node --outfile dist/index.js --external @letary/chisel --external lecodes-headless --external lecodes-design --external lecodes-3d-editor --external lecodes-assets --banner=\"#!/usr/bin/env node\"",
     "build:bin": "bun scripts/build-bin.ts",
     "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "docs": "bun scripts/gen-docs.ts",
+    "docs:check": "bun scripts/gen-docs.ts --check",
     "dev": "bun run src/index.ts",
     "prepublishOnly": "bun run sync-peers && bun run build"
   },

package/runtime/materials/decal-relief.mat

@@ -121,6 +121,12 @@ fragment {
             dot(variable_inv1.xyz, sw) + variable_inv1.w,
             dot(variable_inv2.xyz, sw) + variable_inv2.w);
         if (any(greaterThan(abs(local), vec3(0.5)))) discard;
+        // The caps: a trail segment's mitred joints. Each end edge is tilted by `cap` (unit slope)
+        // about the corner on the side where it stays put, cutting into the box on the other side —
+        // so two neighbouring segments meet on one shared line, no overlap and no wedge of a gap.
+        highp float capS = variable_rect.z, capE = variable_rect.w;
+        if (local.y < -0.5 + local.x * capS + 0.5 * abs(capS)) discard;
+        if (local.y > 0.5 + local.x * capE - 0.5 * abs(capE)) discard;
 
         float4 tint = getColor();
         alpha = tint.a;
@@ -156,7 +162,12 @@ fragment {
         if (edge > 0.0) alpha *= saturate((0.5 - abs(local.z)) / (0.5 * edge));
 
         highp vec2 uv = vec2(local.x + 0.5, 0.5 - local.y);
-        highp vec2 tuv = mix(variable_rect.xy, variable_rect.zw, uv);
+        // The atlas rect, packed two 11-bit values to a float (decals.h) to make room for the caps.
+        highp float p0 = floor(variable_rect.x + 0.5), p1 = floor(variable_rect.y + 0.5);
+        highp float u0i = floor(p0 / 2048.0), u1i = floor(p1 / 2048.0);
+        highp vec2 rect0 = vec2(u0i, p0 - u0i * 2048.0) / 2047.0;
+        highp vec2 rect1 = vec2(u1i, p1 - u1i * 2048.0) / 2047.0;
+        highp vec2 tuv = mix(rect0, rect1, uv);
 
         // The bent normal: the map's xy along the decal's right / up, z along the surface normal.
         vec3 T = normalize(variable_inv0.xyz);

package/runtime/materials/decal.mat

@@ -11,8 +11,11 @@
 // Per-vertex inputs (DECAL_VERTEX_FLOATS in decals.h, one interleaved buffer, 8 corners per decal):
 //   POSITION      — the box corner in the SET's space (the renderable's model space)
 //   CUSTOM0..2    — rows of the 3x4 inverse frame: unit box ← set space
-//   CUSTOM3       — atlas rect u0 v0 u1 v1 (v0 = the cell's top, image top = +Y of the box)
-//   COLOR         — tint rgba (a = opacity)
+//   CUSTOM3       — pack(u0,v0), pack(u1,v1) (the atlas rect, two 11-bit 0..1 values per float;
+//                   v0 = the cell's top, image top = +Y of the box), capStart, capEnd (tilt of the
+//                   bottom / top edge in unit space — a trail segment's mitred joints, 0 = square)
+//   COLOR         — tint rgba (a = opacity, already × the gradient end at each corner: −Y corners
+//                   carry alphaStart, +Y ones alphaEnd, so a trail darkens along its length)
 //   CUSTOM4       — born, life, fadeIn, fadeOut (seconds on the `time` clock; life 0 = forever)
 // Uniforms:
 //   baseColorMap  — the atlas
@@ -122,6 +125,12 @@ fragment {
             dot(variable_inv1.xyz, sw) + variable_inv1.w,
             dot(variable_inv2.xyz, sw) + variable_inv2.w);
         if (any(greaterThan(abs(local), vec3(0.5)))) discard;
+        // The caps: a trail segment's mitred joints. Each end edge is tilted by `cap` (unit slope)
+        // about the corner on the side where it stays put, cutting into the box on the other side —
+        // so two neighbouring segments meet on one shared line, no overlap and no wedge of a gap.
+        highp float capS = variable_rect.z, capE = variable_rect.w;
+        if (local.y < -0.5 + local.x * capS + 0.5 * abs(capS)) discard;
+        if (local.y > 0.5 + local.x * capE - 0.5 * abs(capE)) discard;
 
         float4 tint = getColor();
         alpha = tint.a;
@@ -161,7 +170,12 @@ fragment {
         if (edge > 0.0) alpha *= saturate((0.5 - abs(local.z)) / (0.5 * edge));
 
         highp vec2 uv = vec2(local.x + 0.5, 0.5 - local.y);
-        highp vec2 tuv = mix(variable_rect.xy, variable_rect.zw, uv);
+        // The atlas rect, packed two 11-bit values to a float (decals.h) to make room for the caps.
+        highp float p0 = floor(variable_rect.x + 0.5), p1 = floor(variable_rect.y + 0.5);
+        highp float u0i = floor(p0 / 2048.0), u1i = floor(p1 / 2048.0);
+        highp vec2 rect0 = vec2(u0i, p0 - u0i * 2048.0) / 2047.0;
+        highp vec2 rect1 = vec2(u1i, p1 - u1i * 2048.0) / 2047.0;
+        highp vec2 tuv = mix(rect0, rect1, uv);
         float4 tex = texture(materialParams_baseColorMap, tuv);
         alpha *= tex.a;
         if (alpha <= 0.002) discard;

package/runtime/materials/lightmap.mat

@@ -1,40 +1,89 @@
-// lightmap — a lit PBR material that multiplies a BAKED shadow mask into the result and adds the
-// BAKED direct light of the level's point lights (docs/lightmap-plan.md §3). gltfio hands GLB
-// primitives this material instead of the ubershader when the SDK loads a model with
-// `lightmap: true` (LightmapMaterialProvider in creator-gl/src/glb.cpp), so the base-colour
-// parameters use gltfio's own names and the AssetLoader fills them itself. Mesh receivers
-// (Mesh.plane) get it from the SDK directly.
+// lightmap — the material of a BAKED static (creator-bake, phase 1). gltfio hands a GLB's primitives this
+// material instead of the ubershader when the SDK loads a model with `lightmap: true` (the provider in
+// creator-gl/src/glb.cpp), so the glTF-side parameters use gltfio's own names and the AssetLoader fills
+// them itself. Mesh receivers get it from the SDK directly.
 //
-// Atlas channels: R = sun visibility, G = ambient occlusion. G goes to ambientOcclusion, which
-// filament applies to the IBL term exactly (diffuse + specular AO). R attenuates the sun through
-// postLightingColor (multiply) — it scales the WHOLE lit result, so `k` keeps the ambient share
-// alive in shadow: k = (ambient·G + sun·NoL·vis) / (ambient·G + sun·NoL), diffuse-exact.
-// The real-time sun still lights this surface, so dynamic casters keep their shadow-map shadows.
+// A static takes ALL of its diffuse light from the atlas: `lightmapLight` holds the irradiance E in lux
+// (BC6H, times lightScale) that the bake traced onto the surface — the sun, the sky and the lamps
+// together — and the pixel's diffuse is albedo x E / pi, Filament's own punctual diffuse. Nothing
+// real-time is added on top: the engine keeps the sun and the lamps off these renderables (light channels,
+// lightmapApply) and Filament's IBL — diffuse and specular — is switched off exactly (ambientOcclusion = 0,
+// specularAmbientOcclusion simple). The SPECULAR comes from the bake too: with the level's REFLECTION PROBES
+// bound (phase 4, `lightmapProbe` + the probe map under the aux page: prefiltered radiance traced from points of the
+// level, creator-bake/src/reflect.h) it is the split-sum response to the radiance the probes this texel SEES (baked)
+// hold along the reflection — blended per pixel, parallax-corrected by each probe's room box, at the material's
+// roughness — held down to this texel's own light where the probes see more than the surface does (a specular
+// occlusion from the bake, see the fragment); without them, the baked light as light from all over plus the
+// sky's SH radiance along the reflection through the baked sky visibility. No
+// highlight from the baked direction (fireflies, see the fragment). Plus the glTF emissive. So the picture on
+// a static is the bake, and a wrong picture is a wrong bake or a wrong material, never a shading estimate.
 //
-// The LIGHT atlas (lightmapLight, same rects) holds the point lights' direct irradiance E as
-// sRGB(E / lightScale): the bake traced colour × candela × filament's own falloff window × NoL ×
-// shadow rays, so the baked lamp matches the real-time one it replaces (the SDK switches the
-// real-time light off once the bake applies). It reaches the pixel as emissive = diffuseColor ×
-// E / π, exposure-weighted — the diffuse term filament's own punctual path would have produced.
-// No specular from baked lights (v1).
+// The aux atlas (`lightmapAux`, RGBA8 linear, the same rects): RGB = share x d (x 0.5 + 0.5) — the
+// directional SHARE of the baked light times its direction d — and A = sky visibility (phase 3,
+// creator-bake/src/direction.h). The
+// bake split every texel's light into an ambient part (uniform over the hemisphere) and one direction, so
+// a normal map's shading normal ns gets the irradiance those two would give it:
+//   E(ns) = E x [ (1 - share) (1 + n.ns) / 2  +  share max(0, d.ns) / (d.n) ]
+// exact for both parts, and E itself where the normal is flat. Under a grazing light (d.n < 0.1) the bake
+// fades the share out and the slope is capped. `reconstructIrradiance` in direction.h is the same formula;
+// bake-check tests it.
 //
-// Sampler budget: feature level 1 allows 9 per material (16 minus filament's 7 for a lit shader);
-// this one uses all 9 — nothing else can be added without dropping one.
+// DEBUG VIEWS (`debugMode`, level-wide through lightmapDebug): the material writes DATA to the pixel
+// and turns the lit path off (black base colour, no reflectance), so what is on screen is the number —
+// look at it under `toneMapping: 'linear'` for a faithful reading.
+//   1 lighting only: a white diffuse material under the camera's exposure     2 albedo (base colour, linear)
+//   3 geometric normal (x 0.5 + 0.5)                          4 shading normal (the normal map applied)
+//   5 the directional share (0 = ambient, 1 = one direction)   6 sky visibility
+//   7 the atlas: a texel checker, tinted per instance          8 the baked light's direction (x 0.5 + 0.5)
+//   9 false-colour lux: log10 over [debugParams.y, debugParams.z]   10 relief: E(ns) / E, grey 0.5 = 1 (flat)
+//   13 probe: the radiance the specular reflects (the probe along the reflection at the material's roughness, occluded;
+//      or the sky + baked light without a probe), under the camera's exposure like view 1
+//   14 the probe map: grey = the probes' share Wp of the reflection, tinted by the texel's probe pair (magenta = no entry)
+//   15 the sky's path of the reflection alone      16 the probes' path alone, after the occlusion (black = no probe)
+// On desktop both atlases are fetched bicubically (textureBicubic: a cubic B-spline through four bilinear taps) —
+// the texel grid stops showing on the diagonals of a shadow's edge; the bake's gutters (4 texels, chart-aware fill)
+// cover the wider 4x4 footprint. Mobile and iOS take the plain bilinear fetch (matc -TLIGHTMAP_FETCH, materials.json);
+// macOS (`materials-macos`) takes the desktop flags: the same MOBILE shader model as iOS, the desktop's quality.
+//
+// PRECISION: everything in LUX is `highp`, explicitly. The mobile shader model (matc -p mobile: the `materials` and
+// `materials-ios` targets) makes mediump the fragment default, and Filament's Metal path turns mediump into 16-bit
+// half (filamat GLSLPostProcessor: CreateConvertRelaxedToHalfPass) — max 65504. A sunlit texel is 100 000-180 000 lux
+// once the atlas is multiplied back by lightScale, so on macOS / iOS every baked static went infinite (flat white,
+// and bloom smeared it over the frame: the yard, 2026-09-17) while the desktop target (highp by default) was right.
+// The parameters in lux are `precision : high` for the same reason. Ratios and exposed values are O(1) and may stay.
+// The same for ATLAS COORDINATES, TEXEL INDICES, PROBE INDICES and WORLD POSITIONS: a half has 11 mantissa bits, so a
+// uv near 1 steps by 1/2048 (two texels of a 4096 page — the irradiance read as blocks on macOS, 2026-09-17), an
+// integer above 2048 cannot be odd (the texel checker, view 7, went flat), and 65534 / 65535 (the sky / none probe
+// sentinels) are not representable at all. `luv`, the bicubic taps, mapU16 and the probe ids are highp for that.
 material {
     name : lightmap,
     shadingModel : lit,
     doubleSided : true,
-    // glTF's UV origin is top-left, like gltfio's ubershader (base.mat.in): no flip — filament's
-    // default (true) would mirror both the props' base colour and the atlas rects vertically.
+    // opaque or masked: matc -TBLENDING (materials.json `variants`) — the masked twin is what the
+    // provider hands a glTF MASK material; BLEND materials (glass) are not lightmapped at all
+    blending : ${BLENDING},
+    // glTF's UV origin is top-left, like gltfio's ubershader (base.mat.in): no flip
     flipUV : false,
     requires : [ uv0, uv1 ],
-    postLightingBlending : multiply,
+    // Filament's own specular occlusion, fed ambientOcclusion = 0: the IBL — diffuse AND specular — is off
+    // on a baked surface. Occluding the specular through f0 alone (2026-09-16, phase 1) leaked the sky at
+    // grazing angles: Schlick's (1 - NoV)^5 term does not care about f0, so a basement floor mirrored the
+    // sky IBL whenever the camera looked along it. The sky reflection is the material's own now (skyRadianceSH
+    // x skyVis in the fragment); sharp interior reflections need local probes (a later phase).
+    specularAmbientOcclusion : simple,
     parameters : [
         { type : float4,    name : baseColorFactor },
         { type : sampler2d, name : baseColorMap },
         { type : float,     name : metallicFactor },
         { type : float,     name : roughnessFactor },
         { type : float3,    name : emissiveFactor },
+        // KHR_materials_emissive_strength (gltfio sets it, 1 without the extension): an HDR panel is factor 1 x strength 10
+        { type : float,     name : emissiveStrength },
+        // THE LEVEL'S RADIANCE OF EMISSION 1.0, cd / m2 (the bake's emissiveNits, level-wide): over 0 the glow is drawn
+        // SCENE-referred - emission x nits through the camera's exposure, the luminance the bake lit the room with - so a
+        // panel looks as bright as the light it gives. 0 = screen-referred as before (emission 1.0 = white at any exposure;
+        // an imported strength of 10 then blooms over the whole ceiling).
+        { type : float,     name : emissiveNits, precision : high },
         // set unconditionally by gltfio's AssetLoader (a missing uniform is a PANIC, not a no-op)
         { type : float,     name : normalScale },
         { type : float,     name : aoStrength },
@@ -43,139 +92,69 @@ material {
         { type : sampler2d, name : normalMap },
         { type : float,     name : hasNormalMap },
         // glTF metal-rough (B = metallic, G = roughness), occlusion (R) and emissive maps on UV0 —
-        // bound by the AssetLoader by name; absent = the shared 1x1 white, which is each map's
-        // identity under its factor (metallic 0 x 1, roughness x 1, AO 1, emissive 0 x 1)
+        // bound by the AssetLoader by name; absent = the shared 1x1 white, each map's identity
         { type : sampler2d, name : metallicRoughnessMap },
         { type : sampler2d, name : occlusionMap },
         { type : sampler2d, name : emissiveMap },
-        { type : sampler2d, name : lightmap },
-        // the point lights' baked irradiance, sRGB(E / lightScale) on the same rects; lightScale 0 = none
+        // the bake: irradiance (lux / lightScale) and the aux page, on uv1 * lightmapST.xy + lightmapST.zw
         { type : sampler2d, name : lightmapLight },
-        { type : float,     name : lightScale },
-        // the light store's curve: texel = sRGB(pow(E / lightScale, 1 / lightGamma)). 0/1 = the linear v2
-        // store, 2 = the square-root store bakes write since 2026-08-31 (headroom for the 1/d² peaks)
-        { type : float,     name : lightGamma },
-        // uv1 * st.xy + st.zw = the instance's rectangle of the atlas
-        { type : float4,    name : lightmapST },
-        // multiplier on the ambient (IBL) share in the shadow math: 1 = filament's own shadow
-        // darkness, >1 lighter shadows, <1 deeper
-        { type : float,     name : ambientScale },
-        // 1 = baked sun shadows at full strength, 0 = R ignored (AO only)
-        { type : float,     name : sunStrength },
-        // how much of the baked ambient occlusion applies: 1 = all of it, 0 = none (an interior lit
-        // by its ambient probe alone can need less than the geometric truth)
-        { type : float,     name : bakedAo },
-        // The light VOLUME for dynamic objects (docs/lightmap-plan.md §9): the same channels on a 3D
-        // grid over the level, sampled at the fragment's world position + probeMin.w along the normal.
-        // probeInvSize.w = the grid's depth nz (>= 1) selects it over the atlas (creator-gl binds it; an
-        // atlas rect resets it to 0). probeLight = the point lights' irradiance as an AMBIENT CUBE: six
-        // face slabs (+X −X +Y −Y +Z −Z) stacked along z, depth nz * 6, blended by the normal's n²
-        { type : sampler3d, name : probeVolume },
-        { type : sampler3d, name : probeLight },
-        { type : float4,    name : probeMin },
-        { type : float4,    name : probeInvSize }
+        { type : sampler2d, name : lightmapAux },
+        { type : float4,    name : lightmapST, precision : high },
+        // the level's reflection probes (phase 4, creator-bake/src/reflect.h): the octahedral ATLAS of every probe's
+        // roughness levels (radiance in lux / lightScale per steradian; level l = perceptual roughness l / (levels - 1)).
+        // WHICH probes a pixel reflects is baked: under every aux page sits its PROBE MAP (rows past the square page,
+        // read by texelFetch — see probeGather). probeParams = (bound, levels - 1, oct = level 0's tile edge, probes
+        // per atlas row); probeGrid.xyz / probeGridN.xyz = the origin / size of the range the map's 16-bit probe records
+        // are shares of. probeBall = k + 1 shows probe k alone, unoccluded (the debug mirror balls). Level-wide.
+        { type : sampler2d, name : lightmapProbe },
+        { type : float4,    name : probeParams },
+        { type : float4,    name : probeGrid, precision : high },
+        { type : float4,    name : probeGridN, precision : high },
+        { type : float,     name : probeBall },
+        // A SMALL STATIC the atlas left out (the bake's minSize; creator-bake/src/objects.h): no rect — its light was baked
+        // where it stands, as an AMBIENT CUBE: objectCube[+x -x +y -y +z -z] = (the irradiance rgb in lux a surface facing
+        // that way gets at that side of the object — sun, sky, lamps, bounce — and its sky visibility). objectProbes =
+        // (probe a, probe b, a's weight — what the probe map's byte holds for a texel; 65535 none, 65534 sky — and 1 = this
+        // mode is on). The atlas samplers stay bound to one of the level's pages: the probes' records sit under its aux image.
+        { type : float4[6], name : objectCube, precision : high },
+        { type : float4,    name : objectProbes, precision : high },
+        // A MOVER'S SUN SHADOW on the baked surface: sunDir = TO the sun (w = 1: the aux pages end in the SUN MAP - its
+        // levels' rows, level l of edge s = S >> l in s / 4 rows: texel (x, y) = channel x & 3 of pixel ((x >> 2) + (y & 3) s / 4,
+        // base(l) + (y >> 2)), the texel's baked share of the sun's disc; lightmap-shading.fs sunMapAt), sunLight = the sun's
+        // illuminance in lux, rgb, .w = the sun map's level count (the shader picks the level by the pixel's footprint). Where the real-time
+        // shadow map (movers only: the baked statics cast nothing) says "in shadow", the sun's part leaves the baked
+        // light - no double shadow: a texel the bake already shaded has no sun to lose.
+        { type : float4,    name : sunDir },
+        { type : float4,    name : sunLight, precision : high },
+        { type : float,     name : lightScale, precision : high },
+        { type : float,     name : debugMode },
+        { type : float4,    name : debugParams }
     ]
 }
 
 fragment {
+#include "lightmap-shading.fs"
+
     void material(inout MaterialInputs material) {
+        vec3 n = getWorldGeometricNormalVector();
+        vec3 ns = n;
         if (materialParams.hasNormalMap > 0.5) {
             vec3 tn = texture(materialParams_normalMap, getUV0()).xyz * 2.0 - 1.0;
             tn.xy *= materialParams.normalScale;
             material.normal = tn;
+            ns = normalize(getWorldTangentFrame() * tn);
         }
         prepareMaterial(material);
 
-        material.baseColor = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
         vec2 mr = texture(materialParams_metallicRoughnessMap, getUV0()).bg;
-        material.metallic = materialParams.metallicFactor * mr.x;
-        material.roughness = materialParams.roughnessFactor * mr.y;
-        vec3 glow = texture(materialParams_emissiveMap, getUV0()).rgb * materialParams.emissiveFactor;
-        float occ = 1.0 + materialParams.aoStrength * (texture(materialParams_occlusionMap, getUV0()).r - 1.0);
-
-        vec3 n = getWorldGeometricNormalVector();
-        vec3 ns = getWorldNormalVector();   // the shading normal (normal map applied)
-        vec3 luma = vec3(0.2126, 0.7152, 0.0722);
-        float lg = materialParams.lightGamma > 0.0 ? materialParams.lightGamma : 1.0;
-        vec2 lm;
-        vec3 baked;   // the point lights' irradiance E(n) on this pixel, physical units
-        vec3 l;       // the direction that light is taken to arrive from (the specular term below)
-        if (materialParams.probeInvSize.w > 0.5) {
-            // a dynamic object: the light volume at this pixel (trilinear, half a cell off the surface)
-            vec3 p = getUserWorldPosition() + n * materialParams.probeMin.w;
-            vec3 uvw = (p - materialParams.probeMin.xyz) * materialParams.probeInvSize.xyz;
-            lm = texture(materialParams_probeVolume, uvw).rg;
-            // the ambient cube: the face slab of each axis' sign, z clamped to the slab's own cell
-            // centres so the trilinear fetch never blends into the neighbouring face; decode each face
-            // (the store is a square root), then blend in linear irradiance by n²
-            float nz = materialParams.probeInvSize.w;
-            float wz = clamp(uvw.z, 0.5 / nz, 1.0 - 0.5 / nz);
-            vec3 fx = vec3(uvw.xy, ((ns.x >= 0.0 ? 0.0 : 1.0) + wz) / 6.0);
-            vec3 fy = vec3(uvw.xy, ((ns.y >= 0.0 ? 2.0 : 3.0) + wz) / 6.0);
-            vec3 fz = vec3(uvw.xy, ((ns.z >= 0.0 ? 4.0 : 5.0) + wz) / 6.0);
-            vec3 ex = pow(texture(materialParams_probeLight, fx).rgb, vec3(lg));
-            vec3 ey = pow(texture(materialParams_probeLight, fy).rgb, vec3(lg));
-            vec3 ez = pow(texture(materialParams_probeLight, fz).rgb, vec3(lg));
-            vec3 w2 = ns * ns;
-            baked = (w2.x * ex + w2.y * ey + w2.z * ez) * materialParams.lightScale;
-            // the dominant direction within the normal's octant: each face's energy along its axis
-            vec3 dirE = vec3(sign(ns.x) * dot(ex, luma), sign(ns.y) * dot(ey, luma), sign(ns.z) * dot(ez, luma));
-            l = dot(dirE, dirE) > 1e-12 ? normalize(dirE) : ns;
-        } else {
-            vec2 luv = getUV1() * materialParams.lightmapST.xy + materialParams.lightmapST.zw;
-            lm = texture(materialParams_lightmap, luv).rg;
-            baked = pow(texture(materialParams_lightmapLight, luv).rgb, vec3(lg)) * materialParams.lightScale;
-            l = ns;   // the atlas keeps no direction: a static's lamp light is taken along its normal
-        }
-        lm.g = mix(1.0, lm.g, materialParams.bakedAo);
-        material.ambientOcclusion = lm.g * occ;
-
-        // Baked point lights on the pixel, exposed here (emissive.w = 0 adds it as-is) so the glTF
-        // emissive can share the slot. Diffuse: albedo × (1 − metallic) × E / π — filament's own punctual
-        // diffuse. Specular: the same E through a GGX lobe from `l`, so METALS take baked light too — their
-        // diffuse is zero, and a rough steel table used to render darker than the floor it stands on because
-        // only the ambient probe reached it. L_out = f_spec · E_⊥ · NoL, and E(n) = E_⊥ · NoL is what the
-        // store holds. The lobe is kept no tighter than roughness 0.5: the stored E is light gathered from
-        // a room, not one bulb, and a mirror-sharp lobe would paint it as a highlight over the whole surface.
-        vec3 diffuseColor = material.baseColor.rgb * (1.0 - material.metallic);
-        vec3 specBrdf;
-        {
-            vec3 v = getWorldViewVector();
-            vec3 h = normalize(v + l);
-            float NoL = saturate(dot(ns, l));
-            float NoV = max(dot(ns, v), 1e-4);
-            float NoH = saturate(dot(ns, h));
-            float LoH = saturate(dot(l, h));
-            float pr = max(material.roughness, 0.5);
-            float a2 = pr * pr;
-            a2 *= a2;
-            float dd = NoH * NoH * (a2 - 1.0) + 1.0;
-            float D = a2 / (PI * dd * dd);
-            float V = 0.5 / max(NoL * sqrt(NoV * NoV * (1.0 - a2) + a2) + NoV * sqrt(NoL * NoL * (1.0 - a2) + a2), 1e-4);
-            vec3 f0 = mix(vec3(0.04), material.baseColor.rgb, material.metallic);
-            vec3 F = f0 + (1.0 - f0) * pow(1.0 - LoH, 5.0);
-            specBrdf = D * V * F;
-        }
-        material.emissive = vec4(glow + (diffuseColor / PI + specBrdf) * baked * getExposure(), 0.0);
+        float metallic = materialParams.metallicFactor * mr.x;
+        float roughness = materialParams.roughnessFactor * mr.y;
+        // highp, and nits x exposure FIRST (the PRECISION note in the header): the camera's own reading of emission 1.0 is
+        // 1.2 x 2^EV100 = 39 000 nits outdoors - times a strength of 10 it is past a half's 65 504 before the exposure
+        highp vec3 glow = texture(materialParams_emissiveMap, getUV0()).rgb * (materialParams.emissiveFactor * materialParams.emissiveStrength);
+        if (materialParams.emissiveNits > 0.0) glow *= (materialParams.emissiveNits * getExposure());
 
-        float vis = mix(1.0, lm.r, materialParams.sunStrength);
-        // The ambient share, from the SAME per-frame uniforms filament shades this pixel with
-        // (frameUniforms: the directional light + the IBL's SH, both exposure-premultiplied), so
-        // the floor is exactly the IBL-only brightness filament's own shadow map would leave.
-        vec3 sh = frameUniforms.iblSH[0].xyz
-            + frameUniforms.iblSH[1].xyz * n.y + frameUniforms.iblSH[2].xyz * n.z + frameUniforms.iblSH[3].xyz * n.x
-            + frameUniforms.iblSH[4].xyz * (n.y * n.x) + frameUniforms.iblSH[5].xyz * (n.y * n.z)
-            + frameUniforms.iblSH[6].xyz * (3.0 * n.z * n.z - 1.0) + frameUniforms.iblSH[7].xyz * (n.z * n.x)
-            + frameUniforms.iblSH[8].xyz * (n.x * n.x - n.y * n.y);
-        // diffuse terms in filament's units: IBL = albedo * E_sh * iblLuminance; sun = albedo * (color * intensity) * NoL / PI
-        float amb = max(dot(max(sh, 0.0), luma), 0.0) * frameUniforms.iblLuminance * materialParams.ambientScale * lm.g;
-        float nol = max(dot(n, frameUniforms.lightDirection), 0.0);
-        float sun = dot(frameUniforms.lightColorIntensity.rgb, luma) * frameUniforms.lightColorIntensity.w * nol / PI;
-        // the post-lighting multiply also scales the emissive slot the baked lamps ride in, so their
-        // share (same units: exposed irradiance / π) sits on both sides — a lamp in the sun's shadow
-        // is not dimmed by it
-        float lamp = dot(baked, luma) * (getExposure() / PI);
-        float k = (amb + sun * vis + lamp) / max(amb + sun + lamp, 1e-6);
-        material.postLightingColor = vec4(k, k, k, 1.0);
+        lightmapShade(material, n, ns, base, metallic, roughness, glow);
     }
 }

package/runtime/materials/particles-quad.mat

@@ -88,8 +88,12 @@ vertex {
             float3 x = normalize(cross(y, camZ));
             offset = x * corner.x * c0.x + y * corner.y * (c0.x + materialParams.stretch * speed * yl);
         } else {
-            // ribbon: extrude sideways from the strip tangent; corner.x carries u along the trail
-            float3 x = cross(aux, camZ);
+            // ribbon: extrude sideways across the strip; corner.x carries u along the trail.
+            // c0.y (the billboard's rotation, meaningless here) says which kind of aux this is:
+            //   0 — the strip TANGENT, crossed with the view so the strip faces the camera
+            //   1 — the width axis already resolved on the CPU (an oriented / blade-aligned strip,
+            //       blended back toward the camera as it goes edge-on; it owes the view nothing)
+            float3 x = c0.y > 0.5 ? aux : cross(aux, camZ);
             float xl = length(x);
             x = xl > 1e-4 ? x / xl : camX;
             offset = x * corner.y * c0.x;

package/runtime/materials/terrain-lightmap.mat

@@ -0,0 +1,123 @@
+// terrain-lightmap — THE BAKED TERRAIN: terrain.mat's surface (four splat layers blended by the control map, see its
+// header) shaded like lightmap.mat (its header is the model: the whole diffuse light is the baked irradiance atlas on
+// UV1, no real-time sun, no diffuse IBL; the sun's share comes back out where a mover's real-time shadow falls). The
+// shading is lightmap-shading.fs, the very code lightmap.mat runs — a terrain next to a baked wall cannot drift from it.
+//
+// UV1 is the terrain's global unit square (creator-gl/src/terrain.cpp): ONE atlas rect for the whole terrain, which
+// lightmapApply addresses through `lightmapST` on the terrain's single material instance.
+//
+// WHO USES IT: a scene file's `terrain:` node that is a lightmap static (sdk scene/defineScene.ts) is created with this
+// material instead of terrain.mat, like a model is loaded with lightmap.mat. Without a bound bake it is black, like
+// any lightmapped static.
+//
+// NO REFLECTION PROBES (LIGHTMAP_NO_PROBES): feature level 1 gives a material 9 samplers and the layers take 7 of them,
+// the atlas 2. Ground is rough and mostly under the sky: it reflects the sky's path (SH radiance x the baked sky
+// visibility), which is what lightmap.mat does wherever no probe is seen.
+material {
+    name : terrain_lightmap,
+    shadingModel : lit,
+    // geometric specular AA (Kaplanyan): the ground is a 1024² normal map at ×1.5–2 tiled every 2 m under a
+    // 100 000 lux sun — without this every minified texel is a sub-pixel mirror and the sand sparkles
+    // (Mountain, 2026-09-23; A/B with normalScale 0 showed nothing but the normal map does it)
+    specularAntiAliasing : true,
+    blending : ${BLENDING},
+    flipUV : false,
+    requires : [ uv0, uv1 ],
+    specularAmbientOcclusion : simple,
+    parameters : [
+        // ---- the surface: terrain.mat's
+        { type : sampler2d, name : control },
+        { type : sampler2d, name : albedo0 },
+        { type : sampler2d, name : albedo1 },
+        { type : sampler2d, name : albedo2 },
+        { type : sampler2d, name : albedo3 },
+        { type : sampler2d, name : normals01 },
+        { type : sampler2d, name : normals23 },
+        { type : float4,    name : tiling },
+        { type : float4,    name : roughness },
+        { type : float4,    name : normalScale },
+        { type : float4,    name : triplanar },
+        { type : float2,    name : gridSize },
+        { type : float,     name : cellSize },
+        { type : float3,    name : tint },
+        // ---- the bake: lightmap.mat's (the comments are there), without the probe atlas
+        { type : sampler2d, name : lightmapLight },
+        { type : sampler2d, name : lightmapAux },
+        { type : float4,    name : lightmapST, precision : high },
+        { type : float4,    name : probeParams },
+        { type : float4,    name : probeGrid, precision : high },
+        { type : float4,    name : probeGridN, precision : high },
+        { type : float,     name : probeBall },
+        { type : float4[6], name : objectCube, precision : high },
+        { type : float4,    name : objectProbes, precision : high },
+        { type : float4,    name : sunDir },
+        { type : float4,    name : sunLight, precision : high },
+        { type : float,     name : lightScale, precision : high },
+        { type : float,     name : debugMode },
+        { type : float4,    name : debugParams }
+    ]
+}
+
+fragment {
+#define LIGHTMAP_NO_PROBES
+#include "lightmap-shading.fs"
+
+    vec4 triplanarSample(sampler2D tex, highp vec3 p, vec3 bw, float s) {
+        return texture(tex, p.zy / s) * bw.x + texture(tex, p.xz / s) * bw.y + texture(tex, p.xy / s) * bw.z;
+    }
+
+    // `slot` 0 = this layer's normal XY sits in the pack's RG, 1 = in its BA
+    void splatLayer(sampler2D alb, sampler2D pack, float slot, float tiling, float nscale, float tri, float w,
+                    highp vec2 uv, highp vec3 wp, vec3 bw, float rf, inout vec3 albedo, inout vec3 nrm, inout float rough) {
+        if (w <= 0.0) return;
+        float s = max(tiling, 1e-3);
+        if (tri > 0.5) {
+            vec4 c = triplanarSample(alb, wp, bw, s);
+            albedo += c.rgb * w;
+            rough += rf * c.a * w;
+            nrm += vec3(0.0, 0.0, 1.0) * w;
+        } else {
+            highp vec2 luv = uv / s;
+            vec4 c = texture(alb, luv);
+            albedo += c.rgb * w;
+            rough += rf * c.a * w;
+            if (nscale > 0.0) {
+                vec4 p = texture(pack, luv);
+                vec2 xy = (slot > 0.5 ? p.ba : p.rg) * 2.0 - 1.0;
+                xy *= nscale;
+                float z = sqrt(max(1.0 - dot(xy, xy), 0.0));
+                nrm += vec3(xy, z) * w;
+            } else {
+                nrm += vec3(0.0, 0.0, 1.0) * w;
+            }
+        }
+    }
+
+    void material(inout MaterialInputs material) {
+        // metres and world positions are highp (lightmap.mat's PRECISION note: a half steps by centimetres at 100 m)
+        highp vec2 uv = getUV0();
+        highp vec2 cuv = (uv / max(materialParams.cellSize, 1e-4) + 0.5) / max(materialParams.gridSize, vec2(1.0));
+        vec4 w = texture(materialParams_control, cuv);
+        float ws = w.r + w.g + w.b + w.a;
+        w = ws > 1e-4 ? w / ws : vec4(1.0, 0.0, 0.0, 0.0);
+
+        highp vec3 wp = getUserWorldPosition();
+        vec3 gn = getWorldGeometricNormalVector();
+        vec3 bw = abs(gn);
+        bw = bw / max(bw.x + bw.y + bw.z, 1e-4);
+
+        vec3 albedo = vec3(0.0);
+        vec3 nrm = vec3(0.0);
+        float rough = 0.0;
+        splatLayer(materialParams_albedo0, materialParams_normals01, 0.0, materialParams.tiling.x, materialParams.normalScale.x, materialParams.triplanar.x, w.r, uv, wp, bw, materialParams.roughness.x, albedo, nrm, rough);
+        splatLayer(materialParams_albedo1, materialParams_normals01, 1.0, materialParams.tiling.y, materialParams.normalScale.y, materialParams.triplanar.y, w.g, uv, wp, bw, materialParams.roughness.y, albedo, nrm, rough);
+        splatLayer(materialParams_albedo2, materialParams_normals23, 0.0, materialParams.tiling.z, materialParams.normalScale.z, materialParams.triplanar.z, w.b, uv, wp, bw, materialParams.roughness.z, albedo, nrm, rough);
+        splatLayer(materialParams_albedo3, materialParams_normals23, 1.0, materialParams.tiling.w, materialParams.normalScale.w, materialParams.triplanar.w, w.a, uv, wp, bw, materialParams.roughness.w, albedo, nrm, rough);
+        vec3 tn = normalize(nrm);
+        material.normal = tn;
+        vec3 ns = normalize(getWorldTangentFrame() * tn);
+        prepareMaterial(material);
+
+        lightmapShade(material, gn, ns, vec4(albedo * materialParams.tint, 1.0), 0.0, rough, vec3(0.0));
+    }
+}