lecodes-cli 0.19.2 → 0.20.1

package/runtime/materials/particles.mat

@@ -0,0 +1,121 @@
+// Default particle material — one universal point-sprite shader for every particle system
+// (SDK: Material.particles(), the default when `new Particles({...})` gets no material).
+//
+// Per-particle inputs come from the particles.cpp vertex stream:
+//   COLOR   — tint (the color/dynamicColor curves), multiplied into the texture
+//   CUSTOM0 — x: size (world units, diameter), y: rotation (radians),
+//             z: opacity, w: flipbook frame index
+// Per-system looks are uniforms (all default 0; Material.particles() primes them):
+//   sheetSize — (cols, rows) of the flipbook sheet the texture is cut into. The shader trusts
+//               both components ≥ 1 (no divide-by-zero guard here) — the SDK clamps; (1,1) =
+//               single image. A raw material instance MUST prime this before drawing.
+//   emissive  — extra brightness multiplier for a glow look (0 = off)
+//   additive  — 0 = alpha compositing (smoke), 1 = additive (fire/sparks); fractional blends mix.
+//               Works inside `blending: fade` because Filament blends premultiplied
+//               (ONE, ONE_MINUS_SRC_ALPHA): we premultiply rgb ourselves and scale down the
+//               written alpha, so dst attenuation fades out as `additive` rises.
+//   softness  — radial falloff so an untextured particle is a soft round dot, not a square
+//               (baseColorMap is host-primed to 1×1 white; the SDK sets softness=0 with a map)
+//
+// Sizing: perspScale (viewportHeightPx / (2·tan(fov/2))) is auto-published by the engine in
+// material-global slot 3 (scene.cpp updateShaderGlobalParams), so gl_PointSize = size·scale/depth
+// gives a true world-space diameter. Object vertex domain: particles ride the emitter's transform.
+
+material {
+    name : particles,
+    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 : depthFade }
+    ],
+    // `custom` carries (size, rotation, opacity, FRAME) and the frame index feeds the atlas uv, so
+    // this varying must stay full precision — see the highp note in the fragment stage.
+    variables : [
+        { name : custom, precision : high }
+    ],
+    blending : fade,
+    culling : none,
+    requires: [ color, custom0 ]
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        float4 viewPos = getViewFromWorldMatrix() * material.worldPosition;
+        float z = max(-viewPos.z, 1e-3);
+        gl_PointSize = getCustom0().x * getMaterialGlobal3().x / z;
+        material.custom = getCustom0();
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+
+        // EVERYTHING on the atlas-uv path is explicitly `highp`. matc's `-p mobile` profile lowers
+        // unqualified floats to `mediump`, which Apple GPUs really do execute as fp16 (desktop GL
+        // and desktop browsers quietly run mediump at fp32, which is why this only showed on iOS).
+        // In fp16, `cell + uv` for the last column lands in [7,8) where the ULP is 0.0039; divided
+        // by 8 that is ~1 whole texel of a 2048px sheet, so the sprite visibly stair-steps — and it
+        // degrades with the cell index (column 7 quantizes ~8x coarser than column 0).
+        highp float2 uv = gl_PointCoord.xy;
+
+        highp float rot = variable_custom.y;
+        if (rot != 0.0) {
+            highp float co = cos(rot);
+            highp float si = sin(rot);
+            highp float2 p = uv - float2(0.5, 0.5);
+            uv = float2(co * p.x - si * p.y, si * p.x + co * p.y) + float2(0.5, 0.5);
+            if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) {
+                discard;
+            }
+        }
+
+        highp float2 sheet = materialParams.sheetSize;
+        highp float frame = floor(variable_custom.w);
+        // integer cell math — float `floor(frame / sheet.x)` lands one row early at every row start
+        // on the GPU (6 * (1/6) floors to 0); see particles-quad.mat
+        int sx = int(sheet.x + 0.5);
+        int fi = int(frame + 0.5);
+        int total_i = sx * int(sheet.y + 0.5);
+        fi = fi - (fi / total_i) * total_i;
+        highp float2 cell = float2(float(fi - (fi / sx) * sx), float(fi / sx));
+        highp float2 tuv = (cell + uv) / sheet;
+
+        float4 tex = texture(materialParams_baseColorMap, tuv);
+        float4 tint = getColor();
+
+        // soft round falloff from the (unrotated) sprite center
+        float radial = 1.0 - smoothstep(0.0, 0.5, length(gl_PointCoord.xy - float2(0.5, 0.5)));
+        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
+        // (otherwise it is a 1x1 dummy, and this branch is off). 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;
+            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);
+
+        material.baseColor = float4(rgb * alpha, alpha * (1.0 - saturate(materialParams.additive)));
+    }
+}

package/runtime/materials/shadow.mat

@@ -0,0 +1,21 @@
+material {
+    name : "Invisible shadow plane",
+    shadingModel : unlit,
+    shadowMultiplier : true,
+    blending : transparent,
+    parameters : [
+        // Color and opacity of the projected shadow (RGBA)
+        {
+            type : float4,
+            name : color
+        }
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        // baseColor defines the color and opacity of the final shadow
+        material.baseColor = materialParams.color;
+    }
+}

package/runtime/materials/terrain.mat

@@ -0,0 +1,134 @@
+// terrain — the splat-map ground material (docs/terrain-plan.md §1.5). Up to four PBR layers
+// (albedo + optional normal map, per-layer tiling / roughness) blended by a control map's RGBA
+// weights (one texel per height sample); a layer may sample triplanar (rock on cliffs). UV0 is the
+// terrain's local XZ in metres (creator-gl/src/terrain.cpp writes it), so `tiling` reads as metres
+// per repeat and the control map is addressed as (uv / cellSize + 0.5) / gridSize.
+//
+// Sampler budget: feature level 1 (every host, WebGL included) allows 9 samplers per material, so the
+// normal maps come PACKED two per texture — normals01 = (layer 0 XY in RG, layer 1 XY in BA),
+// normals23 likewise; Z is reconstructed. `lecodes assets` packs them; an unset pack (the shared
+// 1x1 white) decodes to a flat normal, and normalScale 0 skips the read.
+//
+// Baked lighting: lightmap.mat's atlas block (R = sun visibility, G = AO on UV1 = the terrain's ONE
+// atlas rect; the light volume for movers is not needed — a terrain never moves), so a baked level
+// applies the atlas to this material directly, no swap. Every sampler defaults to the shared 1x1
+// white (applyIdentityDefaults): an unset layer is white, an unset lightmap is "fully lit".
+material {
+    name : terrain,
+    shadingModel : lit,
+    flipUV : false,
+    requires : [ uv0, uv1 ],
+    postLightingBlending : multiply,
+    parameters : [
+        { type : sampler2d, name : control },
+        { type : sampler2d, name : albedo0 },
+        { type : sampler2d, name : albedo1 },
+        { type : sampler2d, name : albedo2 },
+        { type : sampler2d, name : albedo3 },
+        { type : sampler2d, name : normals01 },
+        { type : sampler2d, name : normals23 },
+        // metres per texture repeat, per layer
+        { type : float4,    name : tiling },
+        { type : float4,    name : roughness },
+        // normal-map strength per layer; 0 = the layer has no normal map
+        { type : float4,    name : normalScale },
+        // 1 = sample that layer triplanar in world space (its normal map is then skipped)
+        { type : float4,    name : triplanar },
+        // samples along X and Z
+        { type : float2,    name : gridSize },
+        { type : float,     name : cellSize },
+        { type : float3,    name : tint },
+        { type : sampler2d, name : lightmap },
+        // the point lights' baked irradiance, sRGB(E / lightScale), same rect; lightScale 0 = none (the 9th sampler)
+        { type : sampler2d, name : lightmapLight },
+        { type : float,     name : lightScale },
+        // the light store's curve: texel = sRGB(pow(E / lightScale, 1 / lightGamma)); 0/1 = linear (v2 bakes), 2 = the square-root store
+        { type : float,     name : lightGamma },
+        { type : float4,    name : lightmapST },
+        { type : float,     name : ambientScale },
+        { type : float,     name : sunStrength },
+        // how much of the baked ambient occlusion applies (1 = all)
+        { type : float,     name : bakedAo }
+    ]
+}
+
+fragment {
+    vec4 triplanarSample(sampler2D tex, vec3 p, vec3 bw, float s) {
+        return texture(tex, p.zy / s) * bw.x + texture(tex, p.xz / s) * bw.y + texture(tex, p.xy / s) * bw.z;
+    }
+
+    // `slot` 0 = this layer's normal XY sits in the pack's RG, 1 = in its BA
+    void splatLayer(sampler2D alb, sampler2D pack, float slot, float tiling, float nscale, float tri, float w,
+                    vec2 uv, vec3 wp, vec3 bw, inout vec3 albedo, inout vec3 nrm) {
+        if (w <= 0.0) return;
+        float s = max(tiling, 1e-3);
+        if (tri > 0.5) {
+            albedo += triplanarSample(alb, wp, bw, s).rgb * w;
+            nrm += vec3(0.0, 0.0, 1.0) * w;
+        } else {
+            vec2 luv = uv / s;
+            albedo += texture(alb, luv).rgb * w;
+            if (nscale > 0.0) {
+                vec4 p = texture(pack, luv);
+                vec2 xy = (slot > 0.5 ? p.ba : p.rg) * 2.0 - 1.0;
+                xy *= nscale;
+                float z = sqrt(max(1.0 - dot(xy, xy), 0.0));
+                nrm += vec3(xy, z) * w;
+            } else {
+                nrm += vec3(0.0, 0.0, 1.0) * w;
+            }
+        }
+    }
+
+    void material(inout MaterialInputs material) {
+        vec2 uv = getUV0();
+        vec2 cuv = (uv / max(materialParams.cellSize, 1e-4) + 0.5) / max(materialParams.gridSize, vec2(1.0));
+        vec4 w = texture(materialParams_control, cuv);
+        float ws = w.r + w.g + w.b + w.a;
+        w = ws > 1e-4 ? w / ws : vec4(1.0, 0.0, 0.0, 0.0);
+
+        vec3 wp = getUserWorldPosition();
+        vec3 gn = getWorldGeometricNormalVector();
+        vec3 bw = abs(gn);
+        bw = bw / max(bw.x + bw.y + bw.z, 1e-4);
+
+        vec3 albedo = vec3(0.0);
+        vec3 nrm = vec3(0.0);
+        splatLayer(materialParams_albedo0, materialParams_normals01, 0.0, materialParams.tiling.x, materialParams.normalScale.x, materialParams.triplanar.x, w.r, uv, wp, bw, albedo, nrm);
+        splatLayer(materialParams_albedo1, materialParams_normals01, 1.0, materialParams.tiling.y, materialParams.normalScale.y, materialParams.triplanar.y, w.g, uv, wp, bw, albedo, nrm);
+        splatLayer(materialParams_albedo2, materialParams_normals23, 0.0, materialParams.tiling.z, materialParams.normalScale.z, materialParams.triplanar.z, w.b, uv, wp, bw, albedo, nrm);
+        splatLayer(materialParams_albedo3, materialParams_normals23, 1.0, materialParams.tiling.w, materialParams.normalScale.w, materialParams.triplanar.w, w.a, uv, wp, bw, albedo, nrm);
+        material.normal = normalize(nrm);
+        prepareMaterial(material);
+
+        material.baseColor = vec4(albedo * materialParams.tint, 1.0);
+        material.roughness = dot(materialParams.roughness, w);
+        material.metallic = 0.0;
+
+        // ---- baked lighting (lightmap.mat's atlas block) ----
+        vec3 n = gn;
+        vec2 luv = getUV1() * materialParams.lightmapST.xy + materialParams.lightmapST.zw;
+        vec2 lm = texture(materialParams_lightmap, luv).rg;
+        lm.g = mix(1.0, lm.g, materialParams.bakedAo);
+        material.ambientOcclusion = lm.g;
+        // the point lights' baked diffuse (lightmap.mat's emissive path; the terrain has no glTF emissive)
+        float lg = materialParams.lightGamma > 0.0 ? materialParams.lightGamma : 1.0;
+        vec3 baked = pow(texture(materialParams_lightmapLight, luv).rgb, vec3(lg)) * materialParams.lightScale;
+        material.emissive = vec4(material.baseColor.rgb * baked * (getExposure() / PI), 0.0);
+
+        float vis = mix(1.0, lm.r, materialParams.sunStrength);
+        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);
+        vec3 luma = vec3(0.2126, 0.7152, 0.0722);
+        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 baked lamps ride the emissive slot the multiply scales too: same share on both sides
+        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/unlit-transparent.mat

@@ -0,0 +1,42 @@
+// Unlit, ALPHA-BLENDED: the twin of unlit.mat for `Material.unlit({ transparent: true })`.
+//
+// Two differences from unlit.mat, and both are why this is a separate source rather than the same
+// shader compiled twice — blending is baked in by matc (a MaterialInstance cannot change it):
+//
+//   1. baseColor is a float4, so the colour carries its own alpha (`color: "#ffffff80"`). The opaque
+//      material keeps a float3, where an alpha would be a lie.
+//   2. the result is PREMULTIPLIED here. Filament's `blending : transparent` expects premultiplied
+//      source, and neither input is: creator-gl sends the colour as RgbaType::PREMULTIPLIED_sRGB,
+//      which only converts sRGB→linear and does NOT multiply (Color.h), and a decoded PNG is
+//      straight alpha too. So multiply once, at the end. (The pre-2026-08 unlit blended without
+//      this step, which is what made half-transparent textures read too bright at the edges.)
+//
+// Keep the colour × map maths in step with unlit.mat.
+
+material {
+    name : unlit_transparent,
+    shadingModel : unlit,
+    parameters : [
+        // baseColor multiplies baseColorMap (both white-primed by the host — see lit.mat), alpha included
+        {
+            type : float4,
+            name : baseColor
+        },
+        {
+            type : sampler2d,
+            name : baseColorMap
+        }
+    ],
+    blending : transparent,
+    requires: [
+        uv0
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        vec4 base = texture(materialParams_baseColorMap, getUV0()) * materialParams.baseColor;
+        material.baseColor = vec4(base.rgb * base.a, base.a);
+    }
+}

package/runtime/materials/unlit.mat

@@ -0,0 +1,44 @@
+// Unlit (flat) material: baseColor × baseColorMap, OPAQUE.
+//
+// Opaque is the default for the same reason lit.mat is: a blended draw writes no depth, is sorted
+// back-to-front by centre, and Filament drops it from the shadow pass (RenderPass.cpp's
+// filterTranslucentObjects) — so a "flat colour" cube used to occlude nothing and cast no shadow.
+// Alpha is meaningless here: baseColor is a float3 and the map's alpha channel is ignored.
+//
+// The blended twin is unlit-transparent.mat (float4 baseColor, premultiplied). It is a SEPARATE
+// source, not a variant: blending has to be baked in at compile time (a MaterialInstance can't
+// change it), and the two shaders differ in the colour type and the premultiply anyway. Keep an
+// edit to the colour/map maths in step across both — they are ten lines each, side by side.
+//
+// baseColorMap is a plain sampler2d on EVERY target. Apple used to compile its own variant with a
+// samplerExternal map (plus a `useBaseColorMap` bool to branch on), which made Material.unlit refuse
+// an ordinary texture there — filament rejects a SAMPLER_2D bound to an external parameter. Camera
+// passthrough has its own camera.mat / camera_obj.mat, so that split is gone: one source, one
+// behaviour, and the flag with it (nothing in the SDK has emitted `useBaseColorMap` for a while).
+
+material {
+    name : unlit,
+    shadingModel : unlit,
+    parameters : [
+        // baseColor multiplies baseColorMap (white-primed by the host) — see lit.mat
+        {
+            type : float3,
+            name : baseColor
+        },
+        {
+            type : sampler2d,
+            name : baseColorMap
+        }
+    ],
+    requires: [
+        uv0
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = texture(materialParams_baseColorMap, getUV0());
+        material.baseColor.rgb *= materialParams.baseColor;
+    }
+}

package/runtime/materials/video.mat

@@ -0,0 +1,31 @@
+// Video material — samples the frame a media player hands the engine as a texture.
+//
+// The sampler is EXTERNAL because that is what the platforms which actually play video give us:
+// Android a SurfaceTexture (GL_TEXTURE_EXTERNAL_OES), Apple an AVPlayerItemVideoOutput texture.
+// Desktop OpenGL has no external samplers and uploads frames as ordinary RGBA8 instead — it has no
+// video decode yet (parity `gl-media-texture`: desktop = todo), so the desktop build compiles this
+// material only to keep one source per target; whoever wires video up there decides then whether
+// the desktop blob needs its own sampler2d variant.
+
+material {
+    name : video,
+    shadingModel : unlit,
+    parameters : [
+        {
+            type : samplerExternal,
+            name : baseColorMap
+        }
+    ],
+    requires: [
+        uv0
+    ]
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        // inverseTonemapSRGB round-trips the View's tonemapper, so the decoded frame displays with
+        // its true colors instead of washed-out/over-bright.
+        material.baseColor.rgb = inverseTonemapSRGB(texture(materialParams_baseColorMap, getUV0()).rgb);
+    }
+}