lecodes-cli 2.4.10 → 2.5.0

package/runtime/materials/foliage.mat

@@ -0,0 +1,232 @@
+// foliage: THE BARK — the OPAQUE material of the vegetation tier (trunks, limbs, stems; SDK `Model.load(…, { foliage })`
+// gives a model's opaque glTF materials this one, its alpha-MASK materials the cards' - foliage-cards.mat for a crown,
+// grass.mat for ground cover). One source per role since 2026-11-03 (the owner: a crown and a blade of grass are two
+// different things and had one shader; the full per-pixel card variant this file used to compile as `foliage-masked`
+// is gone, the lean cards are THE cards). The three share the wind (foliage-wind.vs) and this parameter list.
+// A LIT shader with custom surface shading (2026-09-23): Filament's lights loop hands each light with its shadow to
+// surfaceShading() — a Lambert with a faint GGX sheen — while the ambient is the material's own, written as emissive
+// with the IBL off: the scene's sky (SH) on the bark's normal, darkened by the baked per-vertex sky visibility and the
+// joints' cavity. A TREE IS A VOLUME IN THE AIR: it reads nothing from the ground — the ground's baked light under a
+// tree is the tree's own shadow (2026-09-19 .. 2026-11-03 it was read here, and a pine in full sun drew black).
+//   • WIND in the vertex shader (foliage-wind.vs; 2026-09-23, Unity HDRP's Wind.hlsl as NatureManufacture ships it):
+//     the plant ROTATES about its root by an angle from a scrolling noise field sampled at the root (the bend, one per
+//     plant, wandering off the mean wind with the turbulence and rising under the gusts). The per-material drag /
+//     stiffness / lean come from the GLB (`profile`); bark never shivers. The depth/shadow variants run the same
+//     vertex shader, so real-time shadows sway with the trunk.
+//   • TOUCH: up to 8 benders (world position + radius, `materialParams.benders`). A plant whose
+//     footprint a bender enters LEANS AWAY AS ONE — the direction comes from the plant's origin, the
+//     amount grows with the vertex' height over the plant's own height — so a trunk stays straight;
+//     `plant.z` (from the asset's measured height, creator-gl foliageBindAsset) gives shrubs the full lean, trees none.
+//   • VARIATION: a per-instance hash of the origin tints base colour a little, so 3 000 copies of one
+//     spruce stop reading as one spruce. No per-instance parameter: copies keep sharing one material
+//     instance (fork lecodes 0025) and Filament's automatic instancing can still merge them.
+//   • FADE: `fade.xy` = the distance range over which the plant thins to nothing, and the LOD pass detaches the
+//     group past `fade.y`.
+// The glTF-side parameters use gltfio's names (the AssetLoader fills them; an undeclared one it sets
+// would be a panic) plus the foliage blocks below, which creator-gl writes on creation and —
+// benders, wind — per frame (glb.cpp foliageUpdate). creator-gl writes EVERY block to every vegetation material,
+// so the three declare the same list even where one of them (the bark: `look`, `leaf.x`) reads only part of it.
+
+material {
+    name : foliage,
+    // lit + customSurfaceShading (2026-09-23): Filament runs the lights loop with each light's SHADOW (the sun's cascades
+    // - the crown shades its trunk), our surfaceShading() writes the bark's response; the IBL is switched off the way
+    // lightmap.mat does it (ambientOcclusion 0 + specularAmbientOcclusion simple) and the ambient is the material's own
+    shadingModel : lit,
+    customSurfaceShading : true,
+    specularAmbientOcclusion : simple,
+    doubleSided : true,
+    blending : opaque,
+    flipUV : false,
+    requires : [ uv0, uv1, tangents, color ],
+    variables : [ variation, radial ],
+    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 },
+        // ---- foliage ----
+        // THE WIND (2026-09-23, the model of Unity HDRP's Wind.hlsl as NatureManufacture ships it — see the vertex
+        // shader): xz = direction × wind speed (m/s), y = turbulence (the random part of the wind — in the pack's
+        // km/h × share units, 12 in its demo: its C# converts the speed to m/s but not this, and every drag / bend in
+        // its materials is authored against that), w = gust scale (0..1: how strong the gusts riding the gust noise are)
+        { type : float4,    name : wind },
+        // x = gust speed (the pack's km/h number, 20 in its demo: the gust pattern travels that many m/s and pushes
+        // by that much × gust), y = touch strength (m), z = colour variation (0..1), w = sun wrap (0..1)
+        { type : float4,    name : sway },
+        // xy = fade start / end distance (m; end 0 = no fade)
+        { type : float4,    name : fade },
+        // x = level-wide SHIVER multiplier on the material's shiver drag (1 = the profile as authored, 0 = none),
+        // y = LEAF SHADOW 0..1 — how much of a light's shadow a CARD takes (2026-09-23: a crown scatters light through
+        // itself, so its cards take the shadow map at ~0.6, not in full like bark; at 1 a distant crown is a dark
+        // silhouette whose only sunlit cards are the top layer), z = translucency 0..1 (sun through a thin leaf lit
+        // from behind), w = SKY AO 0..1 — how far the baked per-vertex sky visibility darkens the ambient
+        { type : float4,    name : leaf },
+        // per MATERIAL, the pack's own wind profile (glTF material extras `lecodes.wind`, written by lecodes-assets
+        // from the Unity material's `_Drag` / `_Stiffness` / `_InitialBend` / `_ShiverDrag`; creator-gl fills a default
+        // by the plant's size when the GLB has none): x = drag (how much of the wind the plant takes: trees 0.1, grass
+        // 1-2), y = stiffness (the bend's growth along the plant: ~1 = linear angle in the distance from the root),
+        // z = initial bend (a permanent lean downwind, trees 1), w = shiver drag (the leaves' own motion: needles
+        // 0.02, grass 0.1-0.2, bark 0)
+        { type : float4,    name : profile },
+        // the pack's `_ShiverDirectionality`: 0 = the leaves shiver along their normal, 1 = along the wind
+        { type : float,     name : shiverDir },
+        // THE LOOK OF THE CARDS (2026-09-23, level-wide, creator-gl foliageSetLook): x = canopy 0..1 — the card's shading
+        // normal blends from its own plane (0) to the crown's hull normal (1: the direction from the crown's centre, from
+        // the vertex shader), which is what hides the flat quads: a card is lit as the part of the volume it sits in;
+        // y = the cards' normal-map strength (a strong map brings the planes back); z = edge fade — a card seen edge-on
+        // dissolves over this much of |N·V| (no paper edges on the silhouette; the colour pass only); w = coverage —
+        // the alpha is scaled by 1 + w × mip level so a crown does not thin out as its atlas mips away (Castaño)
+        { type : float4,    name : look },
+        // the WIND NOISE, generated by creator-gl (glb.cpp foliageNoiseTexture): rgb = three tileable noise fields
+        // around 0.5, a = the gust field 0..1; read by world position with mips, so the trunk sees a blurred copy
+        { type : sampler2d, name : windNoise },
+        // per ASSET (creator-gl, from the GLB's bounds): x = plant height (m), y = footprint radius (m),
+        // z = touch multiplier (1 for a small plant, 0 for a tree)
+        { type : float4,    name : plant },
+        // xyz = world position, w = radius (0 = unused)
+        { type : float4[8], name : benders },
+        // per bender: xy = travel direction on the ground (unit, or 0 when still), z = speed weight 0..1
+        // (creator-gl smooths the velocity over ~0.2 s) — near a plant's centre the lean follows the
+        // travel direction instead of the radial one, so crossing a bush never flips it (2026-09-12)
+        { type : float4[8], name : benderMotion }
+    ]
+}
+
+vertex {
+#include "foliage-wind.vs"
+
+    void materialVertex(inout MaterialVertexInputs material) {
+        FoliageVertex f = foliageWind(material);
+        material.variation = vec4(f.hash, f.alive, f.tintN, f.vao);
+        // .w = the bark's baked CAVITY (COLOR_0.g, vertexAo.ts: short rays about the vertex normal - the limb joints), 1 = open
+        material.radial = vec4(f.hull, f.cavity);
+    }
+}
+
+fragment {
+    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);
+    }
+
+    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;
+    }
+
+    // from material() for surfaceShading(): THE SHADING NORMAL - the material's own (the mesh normal with its map), not
+    // Filament's
+    vec3 gNs = vec3(0.0, 1.0, 0.0);
+    float gCavity = 1.0;   // the joints' micro-shadow on the lights (material())
+
+    void material(inout MaterialInputs material) {
+        vec3 tn = vec3(0.0, 0.0, 1.0);
+        if (materialParams.hasNormalMap > 0.5) tn = texture(materialParams_normalMap, getUV0()).xyz * 2.0 - 1.0;
+        // written for matc's sake: an assignment to material.normal is what makes it emit the tangent frame
+        // (MATERIAL_NEEDS_TBN) that getWorldTangentFrame() below reads - without one the frame is zeros, the bark's normal
+        // normalised to NaN and every trunk went black (2026-09-23). The shading normal itself is the material's own (gNs)
+        material.normal = tn;
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
+        vec3 v = getWorldViewVector();
+        mat3 frame = getWorldTangentFrame();   // T, B, N of the mesh (flipped on a back face: double-sided)
+        // THE BARK: the mesh normal with its map at full strength
+        tn.xy *= materialParams.normalScale;
+        vec3 ns = normalize(frame * tn);
+        gNs = ns;
+        // THE JOINTS (2026-09-23): the bark's baked cavity (limb bases, the trunk under a limb) on the ambient in full and on
+        // the lights by half (a crevice is in the sun's micro-shadow too), plus the normal map's own cavity - a texel
+        // whose normal leans hard off the surface sits in a groove of the bark - on the ambient
+        float cavity = variable_radial.w;
+        gCavity = mix(1.0, cavity, 0.5);
+        cavity *= mix(1.0, clamp(tn.z, 0.0, 1.0), 0.5);
+        // the per-instance tint: warmer/darker to cooler/lighter across the hash, scaled by `variation`
+        float hash = variable_variation.x;
+        vec3 tint = mix(vec3(0.86, 0.94, 0.72), vec3(1.06, 1.02, 1.12), hash);
+        base.rgb *= mix(vec3(1.0), tint, materialParams.sway.z);
+        // the distance fade thins the card (the masked twin's cutoff does the cutting)
+        base.a *= variable_variation.y;
+
+        vec2 mr = texture(materialParams_metallicRoughnessMap, getUV0()).bg;
+        float metallic = materialParams.metallicFactor * mr.x;
+        float roughness = materialParams.roughnessFactor * mr.y;
+        float occ = 1.0 + materialParams.aoStrength * (texture(materialParams_occlusionMap, getUV0()).r - 1.0);
+        highp vec3 glow = texture(materialParams_emissiveMap, getUV0()).rgb * materialParams.emissiveFactor;
+        float NoV = max(dot(ns, v), 1e-4);
+        // the baked sky visibility of the vertex (crown interior, trunk under the crown) on the ambient — the sun keeps
+        // its shadow map; by leaf.w (the sky AO knob), the rest stays for the sky that leaks through a crown's gaps
+        float ao = occ * mix(1.0, variable_variation.w, clamp(materialParams.leaf.w, 0.0, 1.0)) * cavity;
+
+        vec3 diffuseColor = base.rgb * (1.0 - metallic);
+        vec3 f0 = mix(vec3(0.04), base.rgb, metallic);
+        vec3 E = envBrdfApprox(f0, roughness, NoV);
+
+        // THE AMBIENT is the material's own (Filament's IBL is off: ambientOcclusion 0 + specularAmbientOcclusion simple,
+        // lightmap.mat's way), added as emissive; the lights - the sun with its SHADOW MAP, the lamps - come through
+        // surfaceShading() below, per light
+        // the scene's sky on the shading normal, lit real-time (the tree's own depth is the vertex AO in `ao`)
+        vec3 ambD = diffuseColor * shIrradiance(ns) * (1.0 - E) * ao * frameUniforms.iblLuminance;
+        vec3 ambS = E * shIrradiance(reflect(-v, ns)) * ao * frameUniforms.iblLuminance;
+        highp vec3 color = ambD + ambS;
+
+        material.baseColor = base;
+        material.metallic = metallic;
+        material.roughness = roughness;
+        material.reflectance = 0.35;       // a faint sheen on the bark under grazing light (f0 ≈ 0.02; the lobe is in surfaceShading)
+        material.ambientOcclusion = 0.0;   // Filament's IBL off (the header of lightmap.mat)
+        material.emissive = vec4(color + glow, 0.0);
+    }
+
+    // PER LIGHT (Filament's loop: the sun first, then the lamps in range), with the light's shadow in `visibility` -
+    // the crown shades itself and its neighbours through the sun's cascades (2026-09-23; the unlit tier before this
+    // read no shadow map and the sun lit every needle alike). A WRAPPED Lambert (thin leaves let light through) plus
+    // the TRANSLUCENCY of a leaf lit from behind: the back-lit share (the light on the far side of the card; the normal
+    // faces the viewer, double-sided) narrowed toward the view line into the light, as HDRP's thin-surface transmission
+    // does.
+    vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
+        vec3 ns = gNs;
+        vec3 v = getWorldViewVector();
+        vec3 l = lightData.l;
+        float visibility = lightData.visibility;
+        float visibilityT = visibility;
+        float reach = lightData.colorIntensity.w * lightData.attenuation * visibility;
+        float reachT = lightData.colorIntensity.w * lightData.attenuation * visibilityT;
+        // the opaque variant (trunks, limbs, stems): a plain Lambert - wrapping the sun round a trunk lit its far side
+        // while the shadow map called that side shadow, a hard false terminator across the bark (2026-09-23) - plus a
+        // faint GGX sheen (f0 from `reflectance`, the ORM's roughness floored at 0.3: bark never sparkles)
+        float NoL = max(dot(ns, l), 0.0);
+        float through = 0.0;
+        vec3 spec = vec3(0.0);
+        if (NoL > 0.0) {
+            float NoV = max(dot(ns, v), 1e-4);
+            vec3 h = normalize(v + l);
+            float NoH = clamp(dot(ns, h), 0.0, 1.0), VoH = clamp(dot(v, h), 0.0, 1.0);
+            float a = max(shadingData.perceptualRoughness, 0.3); a *= a;
+            float a2 = a * a;
+            float dd = (NoH * a2 - NoH) * NoH + 1.0;
+            float D = a2 / (PI * dd * dd);
+            float Vis = 0.5 / max(NoL * sqrt(NoV * NoV * (1.0 - a2) + a2) + NoV * sqrt(NoL * NoL * (1.0 - a2) + a2), 1e-4);
+            vec3 F = shadingData.f0 + (vec3(1.0) - shadingData.f0) * pow(1.0 - VoH, 5.0);
+            spec = (D * Vis) * F * NoL;
+        }
+        return lightData.colorIntensity.rgb * reach * gCavity * (shadingData.diffuseColor * NoL / PI + spec);
+        return shadingData.diffuseColor * lightData.colorIntensity.rgb * (gCavity * (reach * NoL + reachT * through) / PI);
+    }
+}

package/runtime/materials/grass.mat

@@ -0,0 +1,244 @@
+// grass: the material of GROUND COVER (grass, ferns, heath, the low plants a terrain is carpeted with) - the plant
+// that IS the ground's surface (2026-11-03, split out of foliage-cards.mat; the owner: a crown and a grass blade are
+// two different things and had one shader). It shares the wind (foliage-wind.vs) and the parameters of foliage.mat,
+// and lights the way a blade of grass is lit: by THE GROUND IT STANDS ON. The ambient is the terrain's baked
+// irradiance under the vertex (the sky through the canopy, the bounce) and the sun comes through the ground's baked
+// share where the vertex's own sun ray meets it (a blade's foot is under it) - so grass under a pine stands in the
+// pine's baked shadow like the terrain does, past the shadow map's reach too - and its base takes the colour of the
+// soil (groundTint), which hides the seam with the ground. The crowns (foliage-cards.mat, foliage.mat) read nothing
+// from the ground: a tree is a volume in the air, and the ground under it is in its own shadow.
+// The fragment is foliage-cards.mat's LEAN one (2026-10-18): per-vertex lighting, one texture read, no derivatives.
+// The engine treats it as foliage (it declares `benders`) and writes the same blocks; the SDK picks it for the MASK
+// materials of a `Model.load({ foliage: 'grass' })`.
+
+material {
+    name : grass,
+    shadingModel : lit,
+    customSurfaceShading : true,
+    specularAmbientOcclusion : simple,
+    doubleSided : true,
+    blending : masked,
+    alphaToCoverage : true,
+    flipUV : false,
+    requires : [ uv0, color ],
+    variables : [ variation, radial, lightv, baked ],
+    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 },
+        // ---- foliage (foliage.mat has every comment) ----
+        { type : float4,    name : wind },
+        { type : float4,    name : sway },
+        { type : float4,    name : fade },
+        { type : float4,    name : leaf },
+        { type : float4,    name : profile },
+        { type : float,     name : shiverDir },
+        { type : float4,    name : look },
+        { type : sampler2d, name : windNoise },
+        { type : float4,    name : plant },
+        { type : float4[8], name : benders },
+        { type : float4[8], name : benderMotion },
+        // ---- THE GROUND'S LIGHT (foliage.mat's block, read PER VERTEX here; 2026-10-18, the Forest's baked ground) ----
+        // level-wide, written by creator-gl once a terrain's rect is bound (glb.cpp bindGround / bindOptions)
+        { type : float4,    name : ground, precision : high },
+        { type : float4,    name : groundInv, precision : high },
+        { type : float4,    name : groundST, precision : high },
+        { type : sampler2d, name : lightmapLight, precision : high },
+        { type : sampler2d, name : lightmapAux },
+        { type : float,     name : lightScale },
+        { type : float4,    name : sunDir },
+        { type : float4,    name : sunLight, precision : high },
+        // ---- THE GROUND'S COLOUR (2026-10-18, glb.cpp foliageSetGroundTint): the terrain's control map (its four layers'
+        // weights) and each layer's mean colour; a card's base takes the colour of the soil under it, its top its own
+        { type : sampler2d, name : groundControl },
+        { type : float4[4], name : groundTint },
+        { type : float4,    name : groundTintOrigin, precision : high },   // xy = the terrain's world xz origin, z = bound
+        { type : float4,    name : groundTintInv, precision : high }       // the inverse of its world xz axes
+    ]
+}
+
+vertex {
+#include "foliage-wind.vs"
+#include "lightmap-sunmap.fs"
+
+    // THE GROUND'S LIGHT AT A VERTEX: true when the plant stands over the bound terrain. `ambient` = the terrain texel's irradiance there without the
+    // sun's part (lux, on the up normal) — the sky through the canopy, the bounce. `sunShare` = the baked share of the
+    // sun's disc at the point where the sun ray through `uwp` meets the ground at the plant's base height (a blade's
+    // foot is under it): what shades that point shades the plant — a neighbour's crown, a wall — so a
+    // tree past the shadow map's reach still stands in its neighbour's shadow, and the grass under a pine in the
+    // pine's. `lod` picks the pages' level (a far vertex over one texel of 25 cm would flicker between texels as it sways).
+    // the crowns' level over the ground: a vertex this high takes the open sky's ambient and its own crown's softened shadow
+    #define CANOPY 12.0
+
+    bool groundLightV(highp vec3 uwp, highp float baseY, float lod, out highp vec3 ambient, out float sunShare) {
+        ambient = vec3(0.0); sunShare = 1.0;
+        if (materialParams.ground.z < 0.5) return false;
+        highp vec2 d = uwp.xz - materialParams.ground.xy;
+        highp vec2 g = vec2(dot(materialParams.groundInv.xy, d), dot(materialParams.groundInv.zw, d));
+        if (g.x < 0.0 || g.y < 0.0 || g.x > 1.0 || g.y > 1.0) return false;   // off the terrain
+        highp vec2 luv = g * materialParams.groundST.xy + materialParams.groundST.zw;
+        highp vec3 E = textureLod(materialParams_lightmapLight, luv, lod).rgb * materialParams.lightScale;
+        ambient = E;
+        if (materialParams.sunDir.w > 0.5) {
+            highp ivec2 auxSize = textureSize(materialParams_lightmapAux, 0);
+            highp int level = clamp(int(lod + 0.5), 0, max(sunMapLevels(), 1) - 1);
+            // the sun's part out of the ground's E under the vertex: its illuminance x the share there x the cosine on the
+            // ground, taken as flat
+            float shareHere = sunMapAt(luv, auxSize, level);
+            ambient = max(E - materialParams.sunLight.rgb * (shareHere * max(materialParams.sunDir.y, 0.0)), vec3(0.0));
+            // the sun ray through the vertex, followed down to the plant's base height
+            vec3 s = materialParams.sunDir.xyz;   // TO the sun
+            highp vec3 foot = uwp - s * ((uwp.y - baseY) / max(s.y, 0.05));
+            d = foot.xz - materialParams.ground.xy;
+            g = clamp(vec2(dot(materialParams.groundInv.xy, d), dot(materialParams.groundInv.zw, d)), 0.0, 1.0);
+            sunShare = sunMapAt(g * materialParams.groundST.xy + materialParams.groundST.zw, auxSize, level);
+        }
+        return true;
+    }
+
+    vec3 shIrradianceV(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);
+    }
+
+    void materialVertex(inout MaterialVertexInputs material) {
+        FoliageVertex f = foliageWind(material);
+        // COVERAGE from the distance (foliage.mat reads the atlas' mip level from the uv derivatives per pixel): the
+        // atlas texels under a pixel double every doubling of the distance past ~8 m, where a card is still read in
+        // full; `look.w` scales how much of that goes into the alpha
+        float lodEst = max(log2(max(f.dist, 1.0) / 8.0), 0.0);
+        material.radial = vec4(f.hull, lodEst);
+        // THE LIGHT, per vertex. Ambient = the sky's SH on the hull normal, as radiance under the camera's exposure
+        // (frameUniforms.iblLuminance holds it), darkened by the baked sky visibility by `leaf.w`. The sun = a wrapped
+        // Lambert on the hull (thin leaves let light past the terminator, `sway.w`) plus the translucency of a card lit
+        // from behind (`leaf.z`, narrowed toward the view line into the light; less deep in the crown), one scalar the
+        // fragment multiplies by the light's colour, intensity and SHADOW
+        float ao = mix(1.0, f.vao, clamp(materialParams.leaf.w, 0.0, 1.0));
+        vec3 skyAmbient = shIrradianceV(f.hull) * frameUniforms.iblLuminance;
+        vec3 ambient = skyAmbient;
+        float sunShare = 1.0;
+        float up = 1.0;   // the vertex's height over the ground as a share of the canopy's (1 without a ground)
+        highp vec3 gAmb;
+        if (groundLightV(f.uwp, f.uOrigin.y, lodEst, gAmb, sunShare)) {
+            // THE BAKED GROUND'S LIGHT (the function above): its ambient on the hull normal by the hemisphere formula
+            // lightmapShade uses for a tilted normal (the light comes from above), as radiance E / pi under the camera's
+            // exposure. The crown's base takes the ground's ambient (the sky through the canopy), its top the open sky's
+            // SH - blended by the vertex's height over the plant; a grass blade is all ground
+            // the hemisphere formula alone gave a down-facing hull nothing (black needles under a young pine, the owner
+            // 2026-10-18): what a card sees below is the ground, lit by that same E and reflecting a quarter of it
+            vec3 groundAmbient = gAmb * mix(0.25, 1.0, (1.0 + f.hull.y) * 0.5) / PI * frameUniforms.exposure;
+            // by the height OVER THE GROUND, not within the plant: a bush's top is under the same crowns as the ground
+            // beside it (a 1.5 m bush with the open sky's SH on its top was a lamp in the shade - the owner, 2026-10-18);
+            // the open sky is reached at the crowns' level, CANOPY metres up
+            up = clamp((f.uwp.y - f.uOrigin.y) / CANOPY, 0.0, 1.0);
+            ambient = mix(groundAmbient, skyAmbient, up);
+        }
+        ambient *= ao;
+        vec3 l = frameUniforms.lightDirection;
+        vec3 v = normalize(getWorldCameraPosition() - f.wp);
+        float wrap = clamp(materialParams.sway.w, 0.0, 1.0);
+        float NoL = max((dot(f.hull, l) + wrap) / (1.0 + wrap), 0.0);
+        float back = max(-dot(f.hull, l), 0.0);
+        float vl = pow(max(dot(-v, l), 0.0), 4.0);
+        float through = clamp(materialParams.leaf.z, 0.0, 1.0) * back * (0.5 + 0.5 * vl) * mix(1.0, f.vao, 0.5);
+        material.lightv = vec4(ambient, NoL);
+        // .x = the baked share of the sun at this vertex (1 without a bound ground): surfaceShading takes it as a second
+        // shadow map on the direct light, the stricter of the two, never the product. .y = the translucency, which takes
+        // the shadow map ALONE: the bake's 64-ray share through the crown put out the glow of a back-lit crown (the
+        // multiple scattering a real crown has and this model lacks; the owner, 2026-10-18 "лес довольно тёмный")
+        // .z = the height share: near the ground a shadow is a NEIGHBOUR's and lands in full, at the crowns' level it is the
+        // crown's own and is softened by leaf.y (the scattering a real crown has); the fragment weighs the shadow by it.
+        // (The plants' SHADOW LOD is the LOD pass's, per renderable - lod.cpp gFoliageCast - not this shader's: a card-level
+        // discard in the depth variant saved 0.6 ms of the pass's 6.8, the renderables' vertices and draws are the cost)
+        // THE GROUND'S COLOUR at the plant's base: the layers' weights under the PLANT (one colour per plant - a varying
+        // that differs per vertex could not carry a packed value) times their mean colours; the fragment blends the card's
+        // colour toward it by `baked.w` - all of it at the ground, none from ~70 % of the plant's height up (a grass
+        // blade's base is its soil, a bush's crown its own leaves; a tree's cards never reach it). The colour rides
+        // `variation.w` packed 7 bits a channel (matc allows four variables with the colour attribute; vao was unused there)
+        float gtPacked = 0.0, gtBlend = 0.0;
+        if (materialParams.groundTintOrigin.z > 0.5) {
+            highp vec2 td = f.uOrigin.xz - materialParams.groundTintOrigin.xy;
+            highp vec2 tg = vec2(dot(materialParams.groundTintInv.xy, td), dot(materialParams.groundTintInv.zw, td));
+            if (tg.x >= 0.0 && tg.y >= 0.0 && tg.x <= 1.0 && tg.y <= 1.0) {
+                vec4 w = textureLod(materialParams_groundControl, tg, 0.0);
+                float ws = max(w.x + w.y + w.z + w.w, 1e-3);
+                vec3 soil = (materialParams.groundTint[0].rgb * w.x + materialParams.groundTint[1].rgb * w.y
+                           + materialParams.groundTint[2].rgb * w.z + materialParams.groundTint[3].rgb * w.w) / ws;
+                float base = 1.0 - clamp((f.uwp.y - f.uOrigin.y) / max(0.7 * f.plantH, 0.05), 0.0, 1.0);
+                vec3 q = floor(clamp(soil, 0.0, 1.0) * 127.0 + 0.5);
+                gtPacked = q.r * 16384.0 + q.g * 128.0 + q.b;
+                gtBlend = base * 0.85;
+            }
+        }
+        material.variation = vec4(f.hash, f.alive, f.tintN, gtPacked);
+        material.baked = vec4(sunShare, through, up, gtBlend);
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColorFactor;
+        // the per-instance tint and the leaves' world-noise patches (foliage.mat's comments)
+        float hash = variable_variation.x;
+        vec3 tint = mix(vec3(0.86, 0.94, 0.72), vec3(1.06, 1.02, 1.12), hash);
+        base.rgb *= mix(vec3(1.0), tint, materialParams.sway.z) * (1.0 - 0.18 * variable_variation.z);
+        // the ground's colour at the base (the vertex shader's note): the soil's mean colour in place of the card's
+        if (variable_baked.w > 0.0) {
+            highp float pk = variable_variation.w;
+            vec3 soil = vec3(floor(pk / 16384.0), mod(floor(pk / 128.0), 128.0), mod(pk, 128.0)) / 127.0;
+            base.rgb = mix(base.rgb, soil, variable_baked.w);
+        }
+        // the distance fade thins the card; the coverage holds a far crown's share over the cutoff (colour pass only:
+        // the shadow map's caster is fattened below already)
+        base.a *= variable_variation.y;
+#if defined(VARIANT_DEPTH)
+        float cut = getMaskThreshold();
+        if (base.a >= 0.5 * cut) base.a = max(base.a, cut);
+#else
+        base.a = min(base.a * (1.0 + materialParams.look.w * variable_radial.w), 1.0);
+#endif
+        material.baseColor = base;
+        material.metallic = 0.0;
+        material.roughness = 1.0;
+        material.reflectance = 0.0;
+        material.ambientOcclusion = 0.0;   // Filament's IBL off: the ambient is the vertex shader's, below
+        material.emissive = vec4(base.rgb * variable_lightv.rgb, 0.0);
+    }
+
+    // PER LIGHT (the sun first): the vertex shader's wrapped Lambert + translucency scalar, times the light and its
+    // SHADOW (a card takes the shadow map by leaf.y only, foliage.mat's rule). The shadow is the STRICTER of the
+    // shadow map's and the baked ground's share at the vertex (groundLightV): past the map's reach the bake alone,
+    // within it the two agree on the same crowns and the min keeps them from doubling. A lamp gets the sun's scalar
+    // too — the lean tier is for cards seen from a distance, where a lamp's own angle on a leaf is not read
+    vec3 surfaceShading(const MaterialInputs materialInputs, const ShadingData shadingData, const LightData lightData) {
+        // the shadow MAP is always softened by leaf.y: it cannot tell a neighbour's shadow from the crown's own card-on-card
+        // one, and a young pine at full strength went black (2026-10-18). The BAKED share can: a neighbour's crown is in it
+        // through 64 alpha-tested rays, so it lands in full near the ground and softens to leaf.y at the crowns' level
+        float ky = clamp(materialParams.leaf.y, 0.0, 1.0);
+        float kB = mix(1.0, ky, variable_baked.z);
+        // the baked share is the SUN's: a lamp takes its own shadow map alone (foliage.mat's test for the sun)
+        bool sun = dot(lightData.l, frameUniforms.lightDirection) > 0.999;
+        float baked = sun ? mix(1.0, variable_baked.x, kB) : 1.0;
+        float lit = min(mix(1.0, lightData.visibility, ky), baked);   // the direct light
+        // the translucency takes the same two shadows at the HEIGHT weight (kB): a blade at the ground in a tree's baked shade
+        // gets none of the sun through it (the map alone leaked 30-40 % of the sun into every shaded clump, and all of it past
+        // castDistance - the owner, 2026-10-18 "трава светлая в тени"); a card at the crowns' level keeps leaf.y of it
+        float litT = sun ? mix(1.0, min(lightData.visibility, variable_baked.x), kB) : mix(1.0, lightData.visibility, ky);
+        float reach = lightData.colorIntensity.w * lightData.attenuation;
+        return shadingData.diffuseColor * lightData.colorIntensity.rgb * (reach * (lit * variable_lightv.w + litT * variable_baked.y) / PI);
+    }
+}

package/runtime/materials/particles-quad.mat

@@ -149,9 +149,11 @@ fragment {
         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
+        // geometry behind it. sampler0_structure is the scene depth — the colour pass's own depth
+        // after the opaque objects, bound to the blended half by fork patch 0017 while creator-gl's
+        // scene_depth.cpp sees a system with depthFade > 0 in the scene (full resolution, the
+        // pixel's own texel: a NEAREST read at the fragment's clip position is exact).
+        // With the capture 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

package/runtime/materials/particles.mat

@@ -95,9 +95,11 @@ fragment {
         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
+        // geometry behind it. sampler0_structure is the scene depth — the colour pass's own depth
+        // after the opaque objects, bound to the blended half by fork patch 0017 while creator-gl's
+        // scene_depth.cpp sees a system with depthFade > 0 in the scene (full resolution, the
+        // pixel's own texel: a NEAREST read at the fragment's clip position is exact).
+        // With the capture 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