lecodes-cli 0.20.0 → 0.20.2

package/runtime/materials/lightmap-baked.mat

@@ -0,0 +1,176 @@
+// lightmap-baked: the lightmap material's CHEAP twin (SDK `Material.lightmapShading = "baked"`, a
+// graphics-quality tier). Same parameters, same atlas / volume reads, the same picture on a level whose
+// light is baked — but an UNLIT shading model with the lighting written out by hand, so the fragment
+// skips filament's lit path (prefiltered-cubemap IBL specular + DFG LUT, the froxel loop over dynamic
+// lights, sun shadows, energy compensation, multi-bounce AO).
+//
+// Measured on fps-demo's shooting range (2146 lightmapped props, 1280x720, integrated GPU): the lit
+// material renders at ~62 fps, this one at ~91 — the same +45 % a no-shading stub gave, so the lit
+// path was the cost. Filtering the light variants out of the lit material (variantFilter) gave only
+// +10 %: the IBL evaluation is the expensive half, not the light loops. Mean frame brightness matches
+// the lit material within 1 %.
+//
+// What it drops, deliberately:
+//   - real-time point lights: a muzzle flash / fireball no longer lights the level (the baked lamps
+//     still do — they come from the atlas / volume, not the light list);
+//   - the sun is unshadowed Lambert × the atlas' sun mask (R) — on a DYNAMIC object no shadows;
+//   - IBL specular is approximated: the SH irradiance at the reflected direction × an analytic DFG
+//     (Karis' EnvBRDFApprox) — right for rough surfaces, a blurred reflection on mirrors.
+// Two traps, learnt the hard way (probes in the 2026-09-07 session):
+//   - unlit has NO vertex tangent frame (MATERIAL_NEEDS_TBN is lit-only): getWorldTangentFrame() returns
+//     garbage, NoV collapses to 0 and the specular lobe explodes to white. The frame is built here from
+//     screen-space derivatives of position and uv0 (Schueler's cotangent frame);
+//   - the SH coefficients are NOT pre-exposed (the CPU stores them raw); filament multiplies its Fd/Fr by
+//     iblLuminance in the shader, so this one does too.
+// Keep the parameter list IDENTICAL to lightmap.mat: creator-gl's lightmapSetOptions / bindVolume set
+// every one of them on every lightmap-material instance, and an undeclared uniform is a panic.
+
+material {
+    name : lightmap_baked,
+    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;
+        vec2 mr = texture(materialParams_metallicRoughnessMap, getUV0()).bg;
+        float metallic = materialParams.metallicFactor * mr.x;
+        float 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 = n;
+        if (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);
+    }
+}

package/runtime/materials/lightmap.mat

@@ -0,0 +1,181 @@
+// 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.
+//
+// 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.
+//
+// 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).
+//
+// 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.
+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.
+    flipUV : false,
+    requires : [ uv0, uv1 ],
+    postLightingBlending : multiply,
+    parameters : [
+        { type : float4,    name : baseColorFactor },
+        { type : sampler2d, name : baseColorMap },
+        { type : float,     name : metallicFactor },
+        { type : float,     name : roughnessFactor },
+        { type : float3,    name : emissiveFactor },
+        // set unconditionally by gltfio's AssetLoader (a missing uniform is a PANIC, not a no-op)
+        { type : float,     name : normalScale },
+        { type : float,     name : aoStrength },
+        // glTF normal map on UV0 (the AssetLoader binds it by name); hasNormalMap gates the read —
+        // the provider sets it from the material key, Mesh receivers leave it 0
+        { 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)
+        { 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
+        { 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 }
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        if (materialParams.hasNormalMap > 0.5) {
+            vec3 tn = texture(materialParams_normalMap, getUV0()).xyz * 2.0 - 1.0;
+            tn.xy *= materialParams.normalScale;
+            material.normal = tn;
+        }
+        prepareMaterial(material);
+
+        material.baseColor = 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 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);
+    }
+}

package/runtime/materials/lit.mat

@@ -0,0 +1,43 @@
+
+material {
+    name : lit,
+    shadingModel : lit,
+    parameters : [
+        // The color must be passed in linear space, not sRGB.
+        // baseColor multiplies baseColorMap (glTF-style factor x map). The host primes
+        // baseColor to white and binds a 1x1 white texture to an unset baseColorMap
+        // (createMaterialInstance in creator-gl/src/material.cpp), so either half alone
+        // shows through unchanged — no useBaseColorMap branch, no unset-sampler warning.
+        {
+            type : float3,
+            name : baseColor
+        },
+        {
+            type : sampler2d,
+            name : baseColorMap
+        },
+        {
+            type : float,
+            name : roughness
+        },
+        {
+            type : float,
+            name : metallic
+        }
+    ],
+    requires: [
+        uv0
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+
+        material.baseColor = texture(materialParams_baseColorMap, getUV0());
+        material.baseColor.rgb *= materialParams.baseColor;
+
+        material.roughness = materialParams.roughness;
+        material.metallic = materialParams.metallic;
+    }
+}

package/runtime/materials/particles-quad.mat

@@ -0,0 +1,179 @@
+// Quad particle material — real camera-facing quads for particle systems and ribbon trails
+// (SDK: Material.particles({ render: 'quad' | 'stretch' | 'ribbon' }); native RenderMode 1/2
+// builds the matching vertex stream in particles.cpp). The point-sprite particles.mat stays the
+// default: this variant exists because the vertex FORMAT changes — the fragment look (sheet /
+// emissive / additive / softness) is identical and driven by the same uniforms.
+//
+// Per-vertex inputs (QuadVertex in particles.h, one interleaved buffer):
+//   COLOR   — tint, multiplied into the texture
+//   CUSTOM0 — x: size (world units), y: rotation (radians, billboard only), z: opacity, w: frame
+//   CUSTOM1 — aux: velocity (stretch axis, mode 1) or strip tangent (mode 2), sim space
+//   CUSTOM2 — corner: quad ±0.5 square; ribbon (u01 - 0.5, ±0.5 side)
+// Mode uniforms:
+//   mode    — 0 camera billboard, 1 velocity-stretched, 2 ribbon strip
+//   stretch — (mode 1) extra length in world units per unit of speed: length = size + stretch·|v|
+// Look uniforms beyond the point-sprite set:
+//   emissiveMap / emissiveColor — a second sheet (same grid) ADDED as emissiveMap.rgb × emissiveColor,
+//             keyed by the base sheet's alpha but NOT tinted by the particle colour (Unity's
+//             Particles/Standard _EmissionMap contract: a fireball is a smoke albedo that tints to
+//             black over life plus an emission sheet that keeps glowing until alpha runs out).
+//             emissiveColor defaults to 0 → the unset (white dummy) sampler adds nothing.
+//   frameBlend — 1: crossfade each frame with the next one by the fractional index (Unity's
+//             blended flipbook); 0: snap. The partner frame never wraps past the last cell.
+//   depthFade — soft particles: metres over which a sprite fades out as it cuts into the scene
+//             geometry behind it (0 = off). Reads Filament's structure (depth) buffer, see the
+//             fragment stage + creator-gl patch 0017.
+// The offset is added to worldPosition AFTER the model transform, so size stays in world units
+// regardless of entity scale — matching the point-sprite path. aux is stored in sim space
+// (invWorld-multiplied when the system is world-space) and restored here by the model matrix.
+
+material {
+    name : particles_quad,
+    shadingModel : unlit,
+    parameters : [
+        { type : sampler2d, name : baseColorMap },
+        { type : float2, name : sheetSize, precision : high },
+        { type : float, name : emissive },
+        { type : float, name : additive },
+        { type : float, name : softness },
+        { type : float, name : mode },
+        { type : float, name : stretch },
+        { type : sampler2d, name : emissiveMap },
+        { type : float3, name : emissiveColor },
+        { type : float, name : frameBlend },
+        { type : float, name : depthFade }
+    ],
+    // Both varyings feed the atlas uv (`custom.w` is the frame index, `quaduv.xy` the in-cell uv),
+    // so they must stay full precision — a mediump varying is already quantized on arrival, before
+    // any highp math in the fragment could help. See the note in the fragment stage.
+    variables : [
+        { name : custom, precision : high },
+        { name : quaduv, precision : high }
+    ],
+    blending : fade,
+    culling : none,
+    requires: [ color, custom0, custom1, custom2 ]
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        float4 c0 = getCustom0();
+        float3 aux = (getWorldFromModelMatrix() * float4(getCustom1().xyz, 0.0)).xyz;
+        float2 corner = getCustom2().xy;
+
+        float3 camX = getWorldFromViewMatrix()[0].xyz;
+        float3 camY = getWorldFromViewMatrix()[1].xyz;
+        float3 camZ = getWorldFromViewMatrix()[2].xyz;   // toward the camera
+
+        float m = materialParams.mode;
+        float3 offset;
+        float2 suv = corner;                             // softness/uv basis (pre-rotation)
+        if (m < 0.5) {
+            // camera billboard — rotate the corner, texture rides along (no fragment discard)
+            float co = cos(c0.y);
+            float si = sin(c0.y);
+            float2 rc = float2(co * corner.x - si * corner.y, si * corner.x + co * corner.y);
+            offset = (camX * rc.x + camY * rc.y) * c0.x;
+        } else if (m < 1.5) {
+            // stretched along velocity, projected to the view plane
+            float speed = length(aux);
+            float3 dir = speed > 1e-4 ? aux / speed : camY;
+            // Project the axis onto the view plane; its length (0..1 for a unit dir) is how much of
+            // the streak the viewer can see — a streak flying straight at / away from the camera
+            // must collapse to a dot, not be drawn full length along the (numerically random)
+            // residual direction.
+            float3 y = dir - camZ * dot(dir, camZ);
+            float yl = length(y);
+            y = yl > 1e-4 ? y / yl : camY;
+            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);
+            float xl = length(x);
+            x = xl > 1e-4 ? x / xl : camX;
+            offset = x * corner.y * c0.x;
+            suv = float2(0.0, corner.y);                 // soft falloff across the width only
+        }
+
+        material.worldPosition.xyz += offset;
+        material.custom = c0;
+        material.quaduv = float4(corner.x + 0.5, 0.5 - corner.y, suv.x, suv.y);
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+
+        // `highp` throughout the atlas-uv path: matc's `-p mobile` profile lowers unqualified floats
+        // to `mediump`, which Apple GPUs execute as real fp16 (desktop GL/browsers run mediump at
+        // fp32, hiding it). In fp16 `cell + uv` for the last column sits in [7,8) where the ULP is
+        // 0.0039 — ~1 texel of a 2048px sheet after the divide — so sprites stair-step, worse the
+        // higher the cell index.
+        highp float2 uv = variable_quaduv.xy;
+
+        highp float2 sheet = materialParams.sheetSize;
+        highp float total = sheet.x * sheet.y;
+        highp float fidx = mod(variable_custom.w, total);
+        highp float frame = floor(fidx);
+        // Integer cell math: `floor(frame / sheet.x)` in float is evaluated as frame * (1/sheet.x) on
+        // the GPU and 6 * 0.16666667 floors to 0 — every row start sampled the PREVIOUS row's first
+        // cell for a few frames (a fireball flashing a bright fire cell mid fade-out, five times per
+        // life: the "flicker").
+        int sx = int(sheet.x + 0.5);
+        int fi = int(frame + 0.5);
+        highp float2 cell = float2(float(fi - (fi / sx) * sx), float(fi / sx));
+        highp float2 tuv = (cell + uv) / sheet;
+
+        float4 tex = texture(materialParams_baseColorMap, tuv);
+        float3 em = texture(materialParams_emissiveMap, tuv).rgb;
+        if (materialParams.frameBlend > 0.5) {
+            // the next cell, clamped to the last one (a wrap would flash frame 0 at the end of life)
+            int ni = min(fi + 1, int(total + 0.5) - 1);
+            highp float2 cell2 = float2(float(ni - (ni / sx) * sx), float(ni / sx));
+            highp float2 tuv2 = (cell2 + uv) / sheet;
+            float f = fidx - frame;
+            tex = mix(tex, texture(materialParams_baseColorMap, tuv2), f);
+            em = mix(em, texture(materialParams_emissiveMap, tuv2).rgb, f);
+        }
+        float4 tint = getColor();
+
+        float radial = 1.0 - smoothstep(0.0, 0.5, length(variable_quaduv.zw));
+        float shape = mix(1.0, radial, saturate(materialParams.softness));
+
+        float alpha = tex.a * tint.a * variable_custom.z * shape;
+
+        // Soft particles (depthFade > 0, metres): fade the sprite out where it cuts into the scene
+        // geometry behind it. sampler0_structure is Filament's depth ("structure") buffer — bound
+        // to the colour pass by patch 0017 while creator-gl sees a drawn system with depthFade > 0.
+        // With the structure pass OFF (setDepthEffects(false) = the LOW graphics tier, or a scene
+        // nothing asked it for) filament binds a 1x1 dummy that reads 1.0 — in reversed-Z that is
+        // the NEAR plane, i.e. "the scene is in front of every sprite", so the fade would take the
+        // whole system to alpha 0 and it would VANISH instead of turning hard. Real geometry never
+        // reaches 1.0 (the buffer clears to 0 = far, and the near plane is clipped away), so
+        // `sceneDepth < 1.0` is the "this depth buffer is real" test.
+        // The fragment is reprojected to render-target uv the way Filament's own SSR does
+        // (surface_light_indirect.fs), and both depths are linearized with the SSR linearizeDepth
+        // formula (reversed-Z, far at infinity).
+        // (not in the depth/shadow/picking variants: their per-view layout has no structure sampler)
+#if !defined(VARIANT_DEPTH)
+        if (materialParams.depthFade > 0.0) {
+            highp vec3 wp = getWorldPosition();
+            highp vec4 clip = getClipFromWorldMatrix() * vec4(wp, 1.0);
+            highp vec2 suv = clip.xy * (0.5 / clip.w) + 0.5;
+            highp float sceneDepth = textureLod(sampler0_structure, uvToRenderTargetUV(suv), 0.0).r;
+            if (sceneDepth < 1.0) {
+                highp mat4 p = getViewFromClipMatrix();
+                highp float sceneZ = (sceneDepth * p[2].z + p[3].z) / max(sceneDepth * p[2].w + p[3].w, 1.0 / 16777216.0);
+                highp float fragZ = (getViewFromWorldMatrix() * vec4(wp, 1.0)).z;
+                // both are view-space z (negative ahead): fragZ - sceneZ = how far the scene is behind
+                alpha *= saturate((fragZ - sceneZ) / materialParams.depthFade);
+            }
+        }
+#endif
+        float3 rgb = tex.rgb * tint.rgb * (1.0 + materialParams.emissive) + em * materialParams.emissiveColor;
+
+        material.baseColor = float4(rgb * alpha, alpha * (1.0 - saturate(materialParams.additive)));
+    }
+}