lecodes-cli 0.20.0 → 0.20.1

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "lecodes-cli",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "dependencies": {
     "@letary/chisel": "^0.10.0",
     "jimp": "^1.6.1",
-    "lecodes-sdk": "0.20.0"
+    "lecodes-sdk": "workspace:*"
   },
   "devDependencies": {
-    "lecodes-design": "link:lecodes-design",
-    "lecodes-renderer": "0.20.0",
+    "lecodes-design": "^0.9.0",
+    "lecodes-renderer": "workspace:*",
     "qrcode-terminal": "^0.12.0",
-    "lecodes-3d-editor": "link:lecodes-3d-editor",
-    "lecodes-assets": "0.2.1",
-    "lecodes-creator-nav": "0.19.0",
-    "lecodes-viewer-lite": "0.20.0"
+    "lecodes-3d-editor": "^0.7.0",
+    "lecodes-assets": "workspace:*",
+    "lecodes-creator-nav": "workspace:*",
+    "lecodes-viewer-lite": "workspace:*"
   },
   "peerDependencies": {
     "lecodes-design": "^0.9.0",

package/runtime/materials/decal-relief.mat

@@ -0,0 +1,178 @@
+// Relief decal material (SDK: Material.decal({ normalMap }) — a DecalSet with a `normalMap`). The
+// projection is decal.mat's: the box, the depth-aware bilinear structure read, the unit-space
+// test, the atlas rect, the life fade. What differs is WHAT it paints: not a colour but a change
+// of the surface's own lighting. A forward renderer has already shaded the wall when the decal is
+// drawn, so the normal map cannot bend the wall's normal; instead this shader shades the surface
+// point twice — with the normal reconstructed from the depth buffer, and with that normal bent by
+// the map in the decal's tangent frame — and multiplies the frame buffer by the ratio (`blending :
+// multiply`). A footprint or a dent thus shows relief on ANY surface, whatever its albedo, and
+// needs no colour of its own; a bullet hole adds its colour map on top (useColor: the crater
+// darkens, the map's alpha is its coverage).
+//
+// Lighting = the same per-frame terms filament shades the pixel with (lightmap.mat's recipe): the
+// IBL's SH irradiance for the normal + the directional light's NoL, both exposure-premultiplied.
+// No shadow-map read is possible from here, so the sun term applies in shadow too: relief in a
+// shadowed area reads slightly sunlit. Normal maps are tangent-space, +X = the image's right,
+// +Y = its top (OpenGL convention), stored LINEAR (Texture.fromPixels srgb:false / a linear KTX2).
+//
+// Per-vertex inputs and the uniforms time / edge / angleFade: as decal.mat. Extra uniforms:
+//   normalMap — the tangent-space atlas (same cell grid as baseColorMap)
+//   bump      — normal xy scale (1 = as authored)
+//   useColor  — 1: multiply the colour map in (rgb by its alpha); 0: relief only (footprints)
+
+material {
+    name : decal_relief,
+    shadingModel : unlit,
+    parameters : [
+        { type : sampler2d, name : baseColorMap },
+        { type : sampler2d, name : normalMap },
+        { type : float, name : time, precision : high },
+        { type : float, name : edge },
+        { type : float, name : angleFade },
+        { type : float, name : bump },
+        { type : float, name : useColor }
+    ],
+    variables : [
+        { name : inv0, precision : high },
+        { name : inv1, precision : high },
+        { name : inv2, precision : high },
+        { name : rect, precision : high }
+    ],
+    blending : multiply,
+    culling : front,
+    depthWrite : false,
+    depthCulling : false,
+    requires : [ color, custom0, custom1, custom2, custom3, custom4 ]
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        highp mat4 invDecal = transpose(mat4(getCustom0(), getCustom1(), getCustom2(), vec4(0.0, 0.0, 0.0, 1.0)));
+        highp mat4 total = invDecal * inverse(getWorldFromModelMatrix());
+        material.inv0 = vec4(total[0][0], total[1][0], total[2][0], total[3][0]);
+        material.inv1 = vec4(total[0][1], total[1][1], total[2][1], total[3][1]);
+        material.inv2 = vec4(total[0][2], total[1][2], total[2][2], total[3][2]);
+        material.rect = getCustom3();
+
+        highp vec4 l = getCustom4();
+        highp float age = materialParams.time - l.x;
+        float a = 1.0;
+        if (l.z > 0.0) a *= saturate(age / l.z);
+        if (l.y > 0.0) {
+            a *= l.w > 0.0 ? saturate((l.y - age) / l.w) : 1.0;
+            if (age >= l.y) a = 0.0;
+        }
+        material.color.a *= a;
+    }
+}
+
+fragment {
+    // Diffuse irradiance filament would give a white surface with normal n: the IBL's SH + the sun.
+    float lightOf(const highp vec3 n) {
+        const vec3 luma = vec3(0.2126, 0.7152, 0.0722);
+        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);
+        float amb = max(dot(max(sh, vec3(0.0)), luma), 0.0) * frameUniforms.iblLuminance;
+        float nol = max(dot(n, frameUniforms.lightDirection), 0.0);
+        float sun = dot(frameUniforms.lightColorIntensity.rgb, luma) * frameUniforms.lightColorIntensity.w * nol / PI;
+        return amb + sun;
+    }
+
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec3 value = vec3(1.0);
+        float alpha = 0.0;
+#if !defined(VARIANT_DEPTH)
+        highp vec3 wp = getWorldPosition();
+        highp vec4 clip = getClipFromWorldMatrix() * vec4(wp, 1.0);
+        highp vec2 suv = clip.xy * (0.5 / clip.w) + 0.5;
+        highp mat4 p = getViewFromClipMatrix();
+        // depth-aware bilinear structure read — see decal.mat
+        highp vec2 ssz = vec2(textureSize(sampler0_structure, 0));
+        highp vec2 ts = 1.0 / ssz;
+        highp vec2 pix = suv * ssz - 0.5;
+        highp vec2 base = (floor(pix) + 0.5) * ts;
+        highp vec2 fr = fract(pix);
+        highp float d00 = textureLod(sampler0_structure, uvToRenderTargetUV(base), 0.0).r;
+        highp float d10 = textureLod(sampler0_structure, uvToRenderTargetUV(base + vec2(ts.x, 0.0)), 0.0).r;
+        highp float d01 = textureLod(sampler0_structure, uvToRenderTargetUV(base + vec2(0.0, ts.y)), 0.0).r;
+        highp float d11 = textureLod(sampler0_structure, uvToRenderTargetUV(base + ts), 0.0).r;
+        highp float z00 = (d00 * p[2].z + p[3].z) / max(d00 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z10 = (d10 * p[2].z + p[3].z) / max(d10 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z01 = (d01 * p[2].z + p[3].z) / max(d01 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z11 = (d11 * p[2].z + p[3].z) / max(d11 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float zRef = fr.x < 0.5 ? (fr.y < 0.5 ? z00 : z01) : (fr.y < 0.5 ? z10 : z11);
+        highp float tol = max(0.05 * abs(zRef), 0.03);
+        highp float w00 = (1.0 - fr.x) * (1.0 - fr.y) * step(abs(z00 - zRef), tol);
+        highp float w10 = fr.x * (1.0 - fr.y) * step(abs(z10 - zRef), tol);
+        highp float w01 = (1.0 - fr.x) * fr.y * step(abs(z01 - zRef), tol);
+        highp float w11 = fr.x * fr.y * step(abs(z11 - zRef), tol);
+        highp float wsum = max(w00 + w10 + w01 + w11, 1e-6);
+        highp float sceneDepth = (d00 * w00 + d10 * w10 + d01 * w01 + d11 * w11) / wsum;
+        highp vec4 vc = p * vec4(suv * 2.0 - 1.0, sceneDepth, 1.0);
+        highp vec3 sv = vc.xyz / vc.w;
+        highp vec3 sw = (getWorldFromViewMatrix() * vec4(sv, 1.0)).xyz;
+
+        highp vec3 local = vec3(
+            dot(variable_inv0.xyz, sw) + variable_inv0.w,
+            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;
+
+        float4 tint = getColor();
+        alpha = tint.a;
+
+        // The surface normal from texel centres of the structure buffer (see decal.mat) — needed
+        // here always: it is the normal the relief bends.
+        highp vec2 sel = vec2(fr.x < 0.5 ? 0.0 : ts.x, fr.y < 0.5 ? 0.0 : ts.y);
+        highp vec2 cuv = base + sel;
+        highp float dc = fr.x < 0.5 ? (fr.y < 0.5 ? d00 : d01) : (fr.y < 0.5 ? d10 : d11);
+        highp float dl = textureLod(sampler0_structure, uvToRenderTargetUV(cuv - vec2(ts.x, 0.0)), 0.0).r;
+        highp float dr = textureLod(sampler0_structure, uvToRenderTargetUV(cuv + vec2(ts.x, 0.0)), 0.0).r;
+        highp float dd = textureLod(sampler0_structure, uvToRenderTargetUV(cuv - vec2(0.0, ts.y)), 0.0).r;
+        highp float du = textureLod(sampler0_structure, uvToRenderTargetUV(cuv + vec2(0.0, ts.y)), 0.0).r;
+        highp vec2 ndc = cuv * 2.0 - 1.0;
+        highp vec4 vcc = p * vec4(ndc, dc, 1.0);
+        highp vec4 vl = p * vec4(ndc - vec2(2.0 * ts.x, 0.0), dl, 1.0);
+        highp vec4 vr = p * vec4(ndc + vec2(2.0 * ts.x, 0.0), dr, 1.0);
+        highp vec4 vd = p * vec4(ndc - vec2(0.0, 2.0 * ts.y), dd, 1.0);
+        highp vec4 vu = p * vec4(ndc + vec2(0.0, 2.0 * ts.y), du, 1.0);
+        highp vec3 sc = vcc.xyz / vcc.w;
+        highp vec3 ex = abs(dr - dc) < abs(dl - dc) ? vr.xyz / vr.w - sc : sc - vl.xyz / vl.w;
+        highp vec3 ey = abs(du - dc) < abs(dd - dc) ? vu.xyz / vu.w - sc : sc - vd.xyz / vd.w;
+        highp vec3 nv = cross(ex, ey);
+        highp float nl = length(nv);
+        highp vec3 axis = normalize(variable_inv2.xyz);
+        highp vec3 N = nl > 0.0 ? normalize(mat3(getWorldFromViewMatrix()) * (nv / nl)) : axis;
+        if (dot(N, axis) < 0.0) N = -N;             // the cross product's sign follows the screen
+        if (materialParams.angleFade > 0.0) {
+            float facing = abs(dot(N, axis));
+            alpha *= smoothstep(materialParams.angleFade, materialParams.angleFade + 0.2, facing);
+        }
+        float edge = materialParams.edge;
+        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 bent normal: the map's xy along the decal's right / up, z along the surface normal.
+        vec3 T = normalize(variable_inv0.xyz);
+        vec3 B = normalize(variable_inv1.xyz);
+        vec3 m = texture(materialParams_normalMap, tuv).xyz * 2.0 - 1.0;
+        m.xy *= materialParams.bump;
+        vec3 Nb = normalize(T * m.x + B * m.y + N * max(m.z, 0.05));
+        float ratio = lightOf(Nb) / max(lightOf(N), 1e-4);
+        value = vec3(ratio);
+        if (materialParams.useColor > 0.5) {
+            float4 tex = texture(materialParams_baseColorMap, tuv);
+            value *= mix(vec3(1.0), tex.rgb * tint.rgb, tex.a);
+        }
+        if (alpha <= 0.002) discard;
+#endif
+        // multiply blending: the frame buffer is scaled by this; 1 = untouched
+        material.baseColor = float4(mix(vec3(1.0), value, alpha), 1.0);
+    }
+}

package/runtime/materials/decal.mat

@@ -0,0 +1,172 @@
+// Projected decal material (SDK: Material.decal({ map }); native DecalSet in creator-gl
+// src/decals.cpp). One DecalSet is ONE renderable of unit boxes. The fragment stage does not shade
+// the box: it reads the scene depth behind the fragment (Filament's structure buffer, bound to the
+// colour pass by creator-gl patch 0017 while a set has live decals), reconstructs the scene point
+// on the fragment's eye ray, maps it into the decal's unit space with the inverse frame the vertex
+// carries, discards outside the box and samples the atlas cell there. So a decal lands on whatever
+// opaque surface sits inside its box — floor, wall, corner, stairs, a curved rock — with no
+// geometry access at all. It never lands on blended things (particles, glass, other decals): they
+// are not in the structure pass.
+//
+// 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)
+//   CUSTOM4       — born, life, fadeIn, fadeOut (seconds on the `time` clock; life 0 = forever)
+// Uniforms:
+//   baseColorMap  — the atlas
+//   time          — creator-gl's decal clock (sim seconds), written every frame by updateDecals
+//   edge          — soft fraction of the box's half depth at both Z ends (0 = hard cut), so an
+//                   oblique surface leaves the box gently
+//   angleFade     — cosine below which a surface facing away from the projection axis fades out
+//                   (0.3 ≈ 72°): keeps a floor hit off the wall it meets. 0 = project onto anything
+//   emissive      — HDR boost of the texture colour (0 = none)
+// State: `culling : front` keeps the box's FAR faces, `depthCulling : false` draws them even when a
+// wall (or the camera, standing inside a floor decal's box) is in front — the projection test is
+// the only visibility test. depthWrite off, no shadows.
+
+material {
+    name : decal,
+    shadingModel : unlit,
+    parameters : [
+        { type : sampler2d, name : baseColorMap },
+        { type : float, name : time, precision : high },
+        { type : float, name : edge },
+        { type : float, name : angleFade },
+        { type : float, name : emissive }
+    ],
+    variables : [
+        { name : inv0, precision : high },
+        { name : inv1, precision : high },
+        { name : inv2, precision : high },
+        { name : rect, precision : high }
+    ],
+    blending : fade,
+    culling : front,
+    depthWrite : false,
+    depthCulling : false,
+    requires : [ color, custom0, custom1, custom2, custom3, custom4 ]
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        // unit box ← set space (CPU rows) composed with set space ← world (the renderable's model
+        // transform, inverted here: the set node may sit under a moving parent)
+        highp mat4 invDecal = transpose(mat4(getCustom0(), getCustom1(), getCustom2(), vec4(0.0, 0.0, 0.0, 1.0)));
+        highp mat4 total = invDecal * inverse(getWorldFromModelMatrix());
+        material.inv0 = vec4(total[0][0], total[1][0], total[2][0], total[3][0]);
+        material.inv1 = vec4(total[0][1], total[1][1], total[2][1], total[3][1]);
+        material.inv2 = vec4(total[0][2], total[1][2], total[2][2], total[3][2]);
+        material.rect = getCustom3();
+
+        // Life: fade in over fadeIn, hold, fade out over the last fadeOut seconds; nothing after life.
+        highp vec4 l = getCustom4();
+        highp float age = materialParams.time - l.x;
+        float a = 1.0;
+        if (l.z > 0.0) a *= saturate(age / l.z);
+        if (l.y > 0.0) {
+            a *= l.w > 0.0 ? saturate((l.y - age) / l.w) : 1.0;
+            if (age >= l.y) a = 0.0;
+        }
+        material.color.a *= a;
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        float alpha = 0.0;
+        float3 rgb = float3(0.0);
+#if !defined(VARIANT_DEPTH)
+        // The scene point behind this fragment: the structure buffer's depth on the same eye ray.
+        // Depth goes through Filament's SSR linearizeDepth formula (reversed-Z, far at infinity);
+        // clip z is the stored depth itself, so viewFromClip * (ndc.xy, depth, 1) is a view point.
+        highp vec3 wp = getWorldPosition();
+        highp vec4 clip = getClipFromWorldMatrix() * vec4(wp, 1.0);
+        highp vec2 suv = clip.xy * (0.5 / clip.w) + 0.5;
+        highp mat4 p = getViewFromClipMatrix();
+        // Depth-aware BILINEAR read of the structure buffer. Filament binds it NEAREST and at half
+        // resolution, so a plain read quantises the projection to 2x2-pixel blocks (stair-stepped
+        // edges, blocky uv at oblique views). Hardware depth is affine in screen space on a plane,
+        // so interpolating the RAW depth between the four texel centres is exact there. Across a
+        // silhouette a mix would float in the air: taps whose linear depth strays from the nearest
+        // texel by more than a few percent are dropped (weights renormalised).
+        highp vec2 ssz = vec2(textureSize(sampler0_structure, 0));
+        highp vec2 ts = 1.0 / ssz;
+        highp vec2 pix = suv * ssz - 0.5;
+        highp vec2 base = (floor(pix) + 0.5) * ts;
+        highp vec2 fr = fract(pix);
+        highp float d00 = textureLod(sampler0_structure, uvToRenderTargetUV(base), 0.0).r;
+        highp float d10 = textureLod(sampler0_structure, uvToRenderTargetUV(base + vec2(ts.x, 0.0)), 0.0).r;
+        highp float d01 = textureLod(sampler0_structure, uvToRenderTargetUV(base + vec2(0.0, ts.y)), 0.0).r;
+        highp float d11 = textureLod(sampler0_structure, uvToRenderTargetUV(base + ts), 0.0).r;
+        highp float z00 = (d00 * p[2].z + p[3].z) / max(d00 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z10 = (d10 * p[2].z + p[3].z) / max(d10 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z01 = (d01 * p[2].z + p[3].z) / max(d01 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float z11 = (d11 * p[2].z + p[3].z) / max(d11 * p[2].w + p[3].w, 1.0 / 16777216.0);
+        highp float zRef = fr.x < 0.5 ? (fr.y < 0.5 ? z00 : z01) : (fr.y < 0.5 ? z10 : z11);
+        highp float tol = max(0.05 * abs(zRef), 0.03);
+        highp float w00 = (1.0 - fr.x) * (1.0 - fr.y) * step(abs(z00 - zRef), tol);
+        highp float w10 = fr.x * (1.0 - fr.y) * step(abs(z10 - zRef), tol);
+        highp float w01 = (1.0 - fr.x) * fr.y * step(abs(z01 - zRef), tol);
+        highp float w11 = fr.x * fr.y * step(abs(z11 - zRef), tol);
+        highp float wsum = max(w00 + w10 + w01 + w11, 1e-6);
+        highp float sceneDepth = (d00 * w00 + d10 * w10 + d01 * w01 + d11 * w11) / wsum;
+        highp vec4 vc = p * vec4(suv * 2.0 - 1.0, sceneDepth, 1.0);
+        highp vec3 sv = vc.xyz / vc.w;
+        highp vec3 sw = (getWorldFromViewMatrix() * vec4(sv, 1.0)).xyz;
+
+        highp vec3 local = vec3(
+            dot(variable_inv0.xyz, sw) + variable_inv0.w,
+            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;
+
+        float4 tint = getColor();
+        alpha = tint.a;
+
+        // Surface facing for the angle fade (a floor decal reaching a wall). The normal comes from
+        // the structure buffer's own texels — NOT screen derivatives: the buffer is half-res, so a
+        // 2x2 quad often reads one texel and dFdx/dFdy then describe the view plane, not the
+        // surface. Every point here is a TEXEL CENTRE (the nearest one and its four neighbours):
+        // mixing the bilinear centre with nearest neighbours makes the differences wobble at texel
+        // frequency, which reads as hatching on a wall. Per axis the neighbour closer in depth wins
+        // (a silhouette is crossed on one side only).
+        if (materialParams.angleFade > 0.0) {
+            highp vec2 sel = vec2(fr.x < 0.5 ? 0.0 : ts.x, fr.y < 0.5 ? 0.0 : ts.y);
+            highp vec2 cuv = base + sel;                                   // nearest texel centre
+            highp float dc = fr.x < 0.5 ? (fr.y < 0.5 ? d00 : d01) : (fr.y < 0.5 ? d10 : d11);
+            highp float dl = textureLod(sampler0_structure, uvToRenderTargetUV(cuv - vec2(ts.x, 0.0)), 0.0).r;
+            highp float dr = textureLod(sampler0_structure, uvToRenderTargetUV(cuv + vec2(ts.x, 0.0)), 0.0).r;
+            highp float dd = textureLod(sampler0_structure, uvToRenderTargetUV(cuv - vec2(0.0, ts.y)), 0.0).r;
+            highp float du = textureLod(sampler0_structure, uvToRenderTargetUV(cuv + vec2(0.0, ts.y)), 0.0).r;
+            highp vec2 ndc = cuv * 2.0 - 1.0;
+            highp vec4 vcc = p * vec4(ndc, dc, 1.0);
+            highp vec4 vl = p * vec4(ndc - vec2(2.0 * ts.x, 0.0), dl, 1.0);
+            highp vec4 vr = p * vec4(ndc + vec2(2.0 * ts.x, 0.0), dr, 1.0);
+            highp vec4 vd = p * vec4(ndc - vec2(0.0, 2.0 * ts.y), dd, 1.0);
+            highp vec4 vu = p * vec4(ndc + vec2(0.0, 2.0 * ts.y), du, 1.0);
+            highp vec3 sc = vcc.xyz / vcc.w;
+            highp vec3 ex = abs(dr - dc) < abs(dl - dc) ? vr.xyz / vr.w - sc : sc - vl.xyz / vl.w;
+            highp vec3 ey = abs(du - dc) < abs(dd - dc) ? vu.xyz / vu.w - sc : sc - vd.xyz / vd.w;
+            highp vec3 nv = cross(ex, ey);
+            highp float nl = length(nv);
+            highp vec3 axisView = mat3(getViewFromWorldMatrix()) * normalize(variable_inv2.xyz);
+            float facing = nl > 0.0 ? abs(dot(nv / nl, axisView)) : 1.0;
+            alpha *= smoothstep(materialParams.angleFade, materialParams.angleFade + 0.2, facing);
+        }
+        // Soft Z ends of the box, so an oblique surface leaves the box without a hard cut.
+        float edge = materialParams.edge;
+        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);
+        float4 tex = texture(materialParams_baseColorMap, tuv);
+        alpha *= tex.a;
+        if (alpha <= 0.002) discard;
+        rgb = tex.rgb * tint.rgb * (1.0 + materialParams.emissive);
+#endif
+        material.baseColor = float4(rgb * alpha, alpha);
+    }
+}

package/runtime/materials/lightmap-baked-lite.mat

@@ -0,0 +1,175 @@
+// lightmap-baked-lite: the lightmap material's CHEAPEST tier (SDK `Material.lightmapShading =
+// "baked-lite"`). lightmap-baked (the unlit twin with hand-written lighting) with the per-pixel texture
+// reads cut on the LEVEL: a static (the atlas path) reads base colour, emissive and the two atlas pages
+// only — no normal map (the geometric normal shades), no metallic/roughness map, no occlusion map (the
+// atlas' baked AO stays). A dynamic object (the volume path: weapons, hands, bots — few pixels) keeps
+// every read of lightmap-baked, so the gun in front of the camera looks the same on every tier.
+// Emissive MUST stay: the lamps and signs glow through it.
+//
+// Trap (2026-09-07): with the metallic/roughness map gone, `metallicFactor` alone is WRONG — every
+// pack material here declares metallicFactor 1 and lets the map carry the metalness, so the factor
+// made the whole level fully metallic (diffuse 0 → a dark scene, a dark rifle). Without the map a
+// static is a dielectric (metallic 0, roughness = the factor floored at 0.6).
+// Measured on fps-demo's shooting range at 1920x1080 (integrated GPU, LOW preset): a 3-read probe of
+// this shape ran +20 % over lightmap-baked (62–69 vs 48–59 fps); at 1280x720 only +3–5 % — texture
+// bandwidth is the remaining per-pixel bill at the target resolution.
+// Keep the parameter list IDENTICAL to lightmap.mat (see lightmap-baked.mat): every parameter is set
+// by creator-gl whether the shader reads it or not, and an undeclared uniform is a panic.
+
+material {
+    name : lightmap_baked_lite,
+    shadingModel : unlit,
+    doubleSided : true,
+    flipUV : false,
+    requires : [ uv0, uv1, tangents ],
+    parameters : [
+        { type : float4,    name : baseColorFactor },
+        { type : sampler2d, name : baseColorMap },
+        { type : float,     name : metallicFactor },
+        { type : float,     name : roughnessFactor },
+        { type : float3,    name : emissiveFactor },
+        { type : float,     name : normalScale },
+        { type : float,     name : aoStrength },
+        { type : sampler2d, name : normalMap },
+        { type : float,     name : hasNormalMap },
+        { type : sampler2d, name : metallicRoughnessMap },
+        { type : sampler2d, name : occlusionMap },
+        { type : sampler2d, name : emissiveMap },
+        { type : sampler2d, name : lightmap },
+        { type : sampler2d, name : lightmapLight },
+        { type : float,     name : lightScale },
+        { type : float,     name : lightGamma },
+        { type : float4,    name : lightmapST },
+        { type : float,     name : ambientScale },
+        { type : float,     name : sunStrength },
+        { type : float,     name : bakedAo },
+        { type : sampler3d, name : probeVolume },
+        { type : sampler3d, name : probeLight },
+        { type : float4,    name : probeMin },
+        { type : float4,    name : probeInvSize }
+    ]
+}
+
+fragment {
+    // filament's SH irradiance (Lambert baked into the coefficients, like Irradiance_SphericalHarmonics)
+    vec3 shIrradiance(const vec3 n) {
+        return max(
+            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), 0.0);
+    }
+
+    // Karis' analytic DFG (UE4 mobile): the split-sum's E term without the LUT
+    vec3 envBrdfApprox(const vec3 f0, float roughness, float NoV) {
+        vec4 c0 = vec4(-1.0, -0.0275, -0.572, 0.022);
+        vec4 c1 = vec4(1.0, 0.0425, 1.04, -0.04);
+        vec4 r = roughness * c0 + c1;
+        float a004 = min(r.x * r.x, exp2(-9.28 * NoV)) * r.x + r.y;
+        vec2 ab = vec2(-1.04, 1.04) * a004 + r.zw;
+        return f0 * ab.x + ab.y;
+    }
+
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
+        // a dynamic object (volume-lit) keeps lightmap-baked's reads; a static reads nothing but base,
+        // emissive and the atlas — and without its metal/rough map it is a dielectric (see the header)
+        bool dyn = materialParams.probeInvSize.w > 0.5;
+        float metallic = 0.0;
+        float roughness = max(materialParams.roughnessFactor, 0.6);
+        float occ = 1.0;
+        if (dyn) {
+            vec2 mr = texture(materialParams_metallicRoughnessMap, getUV0()).bg;
+            metallic = materialParams.metallicFactor * mr.x;
+            roughness = materialParams.roughnessFactor * mr.y;
+            occ = 1.0 + materialParams.aoStrength * (texture(materialParams_occlusionMap, getUV0()).r - 1.0);
+        }
+        vec3 glow = texture(materialParams_emissiveMap, getUV0()).rgb * materialParams.emissiveFactor;
+        vec3 n = getWorldGeometricNormalVector();
+        vec3 ns = n;
+        if (dyn && materialParams.hasNormalMap > 0.5) {
+            vec3 tn = texture(materialParams_normalMap, getUV0()).xyz * 2.0 - 1.0;
+            tn.xy *= materialParams.normalScale;
+            // unlit has no vertex tangent frame (MATERIAL_NEEDS_TBN is lit-only): build one from the
+            // screen-space derivatives of position and uv0 (Schueler's cotangent frame)
+            highp vec3 p = getWorldPosition();
+            highp vec2 uv = getUV0();
+            highp vec3 dp1 = dFdx(p), dp2 = dFdy(p);
+            highp vec2 duv1 = dFdx(uv), duv2 = dFdy(uv);
+            highp vec3 dp2perp = cross(dp2, n), dp1perp = cross(n, dp1);
+            highp vec3 T = dp2perp * duv1.x + dp1perp * duv2.x;
+            highp vec3 B = dp2perp * duv1.y + dp1perp * duv2.y;
+            highp float invmax = inversesqrt(max(dot(T, T), dot(B, B)));
+            ns = normalize(mat3(T * invmax, B * invmax, n) * tn);
+        }
+        vec3 v = getWorldViewVector();
+        float NoV = max(dot(ns, v), 1e-4);
+        vec3 luma = vec3(0.2126, 0.7152, 0.0722);
+        float lg = materialParams.lightGamma > 0.0 ? materialParams.lightGamma : 1.0;
+
+        // the baked lamps: the volume for a dynamic object, the atlas for a static — as lightmap.mat
+        vec2 lm;
+        vec3 baked;
+        vec3 l;
+        if (materialParams.probeInvSize.w > 0.5) {
+            vec3 p = getUserWorldPosition() + n * materialParams.probeMin.w;
+            vec3 uvw = (p - materialParams.probeMin.xyz) * materialParams.probeInvSize.xyz;
+            lm = texture(materialParams_probeVolume, uvw).rg;
+            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;
+            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;
+        }
+        lm.g = mix(1.0, lm.g, materialParams.bakedAo);
+        float ao = lm.g * occ;
+        float vis = mix(1.0, lm.r, materialParams.sunStrength);
+
+        vec3 diffuseColor = base.rgb * (1.0 - metallic);
+        vec3 f0 = mix(vec3(0.04), base.rgb, metallic);
+        vec3 E = envBrdfApprox(f0, roughness, NoV);
+
+        vec3 ambD = diffuseColor * shIrradiance(ns) * (1.0 - E) * ao * frameUniforms.iblLuminance;
+        vec3 ambS = E * shIrradiance(reflect(-v, ns)) * ao * frameUniforms.iblLuminance;
+        vec3 color = (ambD + ambS) * materialParams.ambientScale;
+
+        // the sun (a level with one): Lambert × the atlas' visibility mask; pre-exposed like filament's own
+        float sunW = frameUniforms.lightColorIntensity.w;
+        if (sunW > 0.0) {
+            float NoL = max(dot(ns, frameUniforms.lightDirection), 0.0);
+            color += diffuseColor * frameUniforms.lightColorIntensity.rgb * (sunW * NoL * vis / PI);
+        }
+
+        // the baked lamps: diffuse + the cheap specular lobe lightmap.mat also uses (physical units × exposure)
+        {
+            vec3 h = normalize(v + l);
+            float NoL = max(dot(ns, l), 0.0);
+            float NoH = max(dot(ns, h), 0.0);
+            float LoH = max(dot(l, h), 0.0);
+            float pr = max(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 F = f0 + (1.0 - f0) * pow(1.0 - LoH, 5.0);
+            color += (diffuseColor / PI + D * V * F) * baked * getExposure();
+        }
+
+        material.baseColor = vec4(color + glow, 1.0);
+    }
+}