lecodes-gl-lite 2.0.0

package/src/webgl/shaders.ts

@@ -0,0 +1,779 @@
+// GLSL 300 es shaders for the lite 3D engine. The shading model follows Filament's published BRDF
+// (GGX + Smith height-correlated visibility + Schlick fresnel, Lambert diffuse) with Filament's
+// photometric units: light intensities arrive in lux (sun) / nits-ish (IBL) and are pre-exposed by
+// the same default-camera exposure Filament uses (f/16, 1/125s, ISO 100), then tonemapped with an
+// ACES fit and sRGB-encoded. That keeps the SDK's real-world intensity values (sun 100 000, IBL
+// 20 000) producing the same overall brightness as the Filament build.
+
+// Filament default camera: EV100 = log2(N^2 / t * 100/S) with N=16, t=1/125, S=100 → ~14.965.
+// exposure = 1 / (1.2 * 2^EV100).
+export const EXPOSURE = 1 / (1.2 * Math.pow(2, Math.log2((16 * 16) / (1 / 125))))
+
+// ---- shared chunks ----------------------------------------------------------------------------
+
+const COMMON_VERT_HEADER = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+in vec3 normal;
+in vec2 uv;
+uniform mat4 modelMatrix;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+uniform mat3 normalMatrix;
+out vec3 vWorldPos;
+out vec3 vNormal;
+out vec2 vUv;
+`
+
+// Skinning chunk (same bone-texture layout as OGL's GLTFSkin).
+const SKIN_CHUNK = /* glsl */ `
+in vec4 skinIndex;
+in vec4 skinWeight;
+uniform sampler2D boneTexture;
+uniform int boneTextureSize;
+
+mat4 getBoneMatrix(const in float i) {
+  float j = i * 4.0;
+  float x = mod(j, float(boneTextureSize));
+  float y = floor(j / float(boneTextureSize));
+  float dx = 1.0 / float(boneTextureSize);
+  float dy = 1.0 / float(boneTextureSize);
+  y = dy * (y + 0.5);
+  vec4 v1 = texture(boneTexture, vec2(dx * (x + 0.5), y));
+  vec4 v2 = texture(boneTexture, vec2(dx * (x + 1.5), y));
+  vec4 v3 = texture(boneTexture, vec2(dx * (x + 2.5), y));
+  vec4 v4 = texture(boneTexture, vec2(dx * (x + 3.5), y));
+  return mat4(v1, v2, v3, v4);
+}
+
+mat4 getSkinMatrix() {
+  mat4 boneMatX = getBoneMatrix(skinIndex.x);
+  mat4 boneMatY = getBoneMatrix(skinIndex.y);
+  mat4 boneMatZ = getBoneMatrix(skinIndex.z);
+  mat4 boneMatW = getBoneMatrix(skinIndex.w);
+  return boneMatX * skinWeight.x + boneMatY * skinWeight.y + boneMatZ * skinWeight.z + boneMatW * skinWeight.w;
+}
+`
+
+// Morph-target (blendshape) chunk — the three.js r133+ approach: every target's deltas live in one
+// RGBA32F data texture fetched by gl_VertexID, so there is no vertex-attribute limit. Layout is
+// target-major: texel = targetIndex * vertexCount + vertexId; normal-delta blocks (when present)
+// follow all position blocks at offset count * vertexCount.
+const MORPH_CHUNK = /* glsl */ `
+uniform sampler2D uMorphTex;
+uniform int uMorphCount;        // active target count (capped by glb.ts)
+uniform int uMorphVertexCount;
+uniform int uMorphTexWidth;
+uniform float uMorphWeights[8];
+
+vec3 morphFetch(int idx) {
+  return texelFetch(uMorphTex, ivec2(idx % uMorphTexWidth, idx / uMorphTexWidth), 0).rgb;
+}
+`
+
+// INSTANCED (batching.ts defines it on a program's twin): the world matrix is the per-instance
+// `instanceMatrix` attribute and the view comes in separately — modelMatrix / modelViewMatrix /
+// normalMatrix go inactive. Same math either way, so a batch and a single can't shade differently.
+const vertex = (defines: string): string => /* glsl */ `${COMMON_VERT_HEADER}
+#ifdef INSTANCED
+in mat4 instanceMatrix;
+uniform mat4 viewMatrix;
+#endif
+${defines.includes('HAS_SKIN') ? SKIN_CHUNK : ''}
+${defines.includes('HAS_MORPH') ? MORPH_CHUNK : ''}
+${defines.includes('HAS_COLOR') ? 'in vec4 color;\nout vec4 vColor;' : ''}
+uniform mat4 shadowMatrix;
+out vec4 vShadowCoord;
+
+void main() {
+  vec4 pos = vec4(position, 1.0);
+  vec3 nrm = normal;
+  ${defines.includes('HAS_MORPH') ? /* glsl — morph BEFORE skinning, per glTF spec */ `
+  for (int t = 0; t < uMorphCount; t++) {
+    if (uMorphWeights[t] != 0.0) {
+      pos.xyz += uMorphWeights[t] * morphFetch(t * uMorphVertexCount + gl_VertexID);
+      ${defines.includes('HAS_MORPH_NORMALS') ? 'nrm += uMorphWeights[t] * morphFetch((uMorphCount + t) * uMorphVertexCount + gl_VertexID);' : ''}
+    }
+  }
+  ` : ''}
+  ${defines.includes('HAS_SKIN') ? `
+  mat4 skinMatrix = getSkinMatrix();
+  pos = skinMatrix * pos;
+  nrm = mat3(skinMatrix) * nrm;
+  ` : ''}
+  ${defines.includes('HAS_COLOR') ? 'vColor = color;' : ''}
+#ifdef INSTANCED
+  mat4 model = instanceMatrix;
+#else
+  mat4 model = modelMatrix;
+#endif
+  vec4 worldPos = model * pos;
+  vWorldPos = worldPos.xyz;
+  vNormal = normalize(mat3(model) * nrm);
+  vUv = uv;
+  vShadowCoord = shadowMatrix * worldPos;
+#ifdef INSTANCED
+  gl_Position = projectionMatrix * viewMatrix * worldPos;
+#else
+  gl_Position = projectionMatrix * modelViewMatrix * pos;
+#endif
+}
+`
+
+// Fragment lighting shared by lit + glTF PBR + custom lit materials (customMaterial.ts).
+// Requires uniforms:
+//   sunDirection (unit, TO the scene), sunColorIntensity (linear rgb * lux), iblLuminance (intensity),
+//   iblSH[9], envMap (prefiltered cube, 4 mips), shadowMap, shadowEnabled, exposure, cameraPosition.
+export const LIGHTING_CHUNK = /* glsl */ `
+uniform vec3 sunDirection;
+uniform vec4 sunColorIntensity; // rgb = linear color, a = intensity (lux)
+uniform float iblLuminance;
+uniform vec3 iblSH[9];
+uniform samplerCube envMap;
+uniform float envMapMaxLod;
+uniform sampler2D shadowMap;
+uniform float shadowEnabled;
+uniform float shadowMapSize;
+uniform float exposure;
+in vec4 vShadowCoord;
+
+#define PI 3.14159265359
+
+float D_GGX(float NoH, float a) {
+  float a2 = a * a;
+  float f = (NoH * a2 - NoH) * NoH + 1.0;
+  return a2 / (PI * f * f);
+}
+
+float V_SmithGGXCorrelated(float NoV, float NoL, float a) {
+  float a2 = a * a;
+  float GGXL = NoV * sqrt((-NoL * a2 + NoL) * NoL + a2);
+  float GGXV = NoL * sqrt((-NoV * a2 + NoV) * NoV + a2);
+  return 0.5 / (GGXV + GGXL + 1e-5);
+}
+
+vec3 F_Schlick(float u, vec3 f0) {
+  float f = pow(1.0 - u, 5.0);
+  return f0 + (vec3(1.0) - f0) * f;
+}
+
+vec3 evalSH(vec3 n) {
+  return max(
+    iblSH[0]
+    + iblSH[1] * n.y
+    + iblSH[2] * n.z
+    + iblSH[3] * n.x
+    + iblSH[4] * (n.y * n.x)
+    + iblSH[5] * (n.y * n.z)
+    + iblSH[6] * (3.0 * n.z * n.z - 1.0)
+    + iblSH[7] * (n.z * n.x)
+    + iblSH[8] * (n.x * n.x - n.y * n.y)
+  , vec3(0.0));
+}
+
+float sampleShadowPCF() {
+  if (shadowEnabled < 0.5) return 1.0;
+  vec3 coord = vShadowCoord.xyz / vShadowCoord.w;
+  coord = coord * 0.5 + 0.5;
+  if (coord.x < 0.0 || coord.x > 1.0 || coord.y < 0.0 || coord.y > 1.0 || coord.z > 1.0) return 1.0;
+  float bias = 0.0018;
+  float texel = 1.0 / shadowMapSize;
+  float sum = 0.0;
+  for (int x = -1; x <= 1; x++) {
+    for (int y = -1; y <= 1; y++) {
+      float depth = texture(shadowMap, coord.xy + vec2(float(x), float(y)) * texel).r;
+      sum += (coord.z - bias) > depth ? 0.0 : 1.0;
+    }
+  }
+  return sum / 9.0;
+}
+
+// diffuseColor: linear albedo (already metallic-adjusted); f0: specular reflectance at normal.
+vec3 shadePBR(vec3 n, vec3 v, vec3 diffuseColor, vec3 f0, float perceptualRoughness, float occlusion) {
+  float roughness = clamp(perceptualRoughness, 0.045, 1.0);
+  float a = roughness * roughness;
+  float NoV = abs(dot(n, v)) + 1e-5;
+
+  vec3 color = vec3(0.0);
+
+  // --- sun ---
+  if (sunColorIntensity.a > 0.0) {
+    vec3 l = normalize(-sunDirection);
+    float NoL = clamp(dot(n, l), 0.0, 1.0);
+    if (NoL > 0.0) {
+      vec3 h = normalize(v + l);
+      float NoH = clamp(dot(n, h), 0.0, 1.0);
+      float LoH = clamp(dot(l, h), 0.0, 1.0);
+      float D = D_GGX(NoH, a);
+      float V = V_SmithGGXCorrelated(NoV, NoL, a);
+      vec3 F = F_Schlick(LoH, f0);
+      vec3 Fr = D * V * F;
+      vec3 Fd = diffuseColor * (1.0 / PI);
+      float shadow = sampleShadowPCF();
+      // "illuminance" model: lux * NoL, pre-exposed
+      color += (Fd + Fr) * sunColorIntensity.rgb * (sunColorIntensity.a * exposure * NoL * shadow);
+    }
+  }
+
+  // --- IBL ---
+  if (iblLuminance > 0.0) {
+    // cmgen's SH coefficients are pre-convolved irradiance — no extra 1/PI (matches Filament).
+    vec3 irradiance = evalSH(n);
+    vec3 Fd = diffuseColor * irradiance;
+
+    vec3 r = reflect(-v, n);
+    float lod = roughness * envMapMaxLod;
+    vec3 prefiltered = textureLod(envMap, r, lod).rgb;
+    // Simple DFG approximation (Karis): avoids a DFG LUT.
+    vec3 specular = prefiltered * (f0 * (1.0 - roughness) + roughness * 0.25 * f0 + 0.05 * (1.0 - roughness));
+    color += (Fd + specular) * (iblLuminance * exposure * occlusion);
+  }
+
+  return color;
+}
+
+// ACES filmic fit (Narkowicz) + sRGB OETF — stands in for Filament's default ACES color grading.
+vec3 tonemap(vec3 x) {
+  const float A = 2.51; const float B = 0.03; const float C = 2.43; const float D = 0.59; const float E = 0.14;
+  vec3 t = clamp((x * (A * x + B)) / (x * (C * x + D) + E), 0.0, 1.0);
+  return pow(t, vec3(1.0 / 2.2));
+}
+`
+
+// ---- programs ---------------------------------------------------------------------------------
+
+export const litFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec3 cameraPosition;
+uniform vec3 baseColor;       // linear factor over baseColorMap (both default white)
+uniform sampler2D baseColorMap;
+uniform float roughness;
+uniform float metallic;
+${LIGHTING_CHUNK}
+out vec4 fragColor;
+
+void main() {
+  vec3 albedo = baseColor * texture(baseColorMap, vUv).rgb;
+  vec3 n = normalize(vNormal);
+  vec3 v = normalize(cameraPosition - vWorldPos);
+  if (dot(n, v) < 0.0) n = -n;
+  vec3 diffuseColor = albedo * (1.0 - metallic);
+  vec3 f0 = mix(vec3(0.04), albedo, metallic);
+  vec3 color = shadePBR(n, v, diffuseColor, f0, roughness, 1.0);
+  fragColor = vec4(tonemap(color), 1.0);
+}
+`
+
+// terrain.mat (docs/terrain-plan.md §1.5): four albedo layers + two packed normal-map textures
+// blended by a control map on the terrain's own grid; UV = the chunk's local XZ in metres (the SDK's
+// terrainMesh.ts writes it), so `tiling` is metres per repeat and the control map is addressed as
+// (uv / cellSize + 0.5) / gridSize. The tangent frame comes from screen-space derivatives (the lite
+// chunk geometry carries no tangents). No lightmap block here — lite has no bake.
+export const terrainFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec3 cameraPosition;
+uniform sampler2D control;
+uniform sampler2D albedo0;
+uniform sampler2D albedo1;
+uniform sampler2D albedo2;
+uniform sampler2D albedo3;
+uniform sampler2D normals01;
+uniform sampler2D normals23;
+uniform vec4 tiling;
+uniform vec4 roughness;
+uniform vec4 normalScale;
+uniform vec4 triplanar;
+uniform vec2 gridSize;
+uniform float cellSize;
+uniform vec3 tint;
+${LIGHTING_CHUNK}
+out vec4 fragColor;
+
+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;
+}
+
+void splatLayer(sampler2D alb, sampler2D pack, float slot, float tl, 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(tl, 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;
+      nrm += vec3(xy, sqrt(max(1.0 - dot(xy, xy), 0.0))) * w;
+    } else {
+      nrm += vec3(0.0, 0.0, 1.0) * w;
+    }
+  }
+}
+
+vec3 applyTangentNormal(vec3 nTangent, vec3 ng) {
+  vec3 pos_dx = dFdx(vWorldPos);
+  vec3 pos_dy = dFdy(vWorldPos);
+  vec2 tex_dx = dFdx(vUv);
+  vec2 tex_dy = dFdy(vUv);
+  float det = tex_dx.x * tex_dy.y - tex_dy.x * tex_dx.y;
+  if (abs(det) < 1e-8) return ng;
+  vec3 t = normalize(pos_dx * tex_dy.y - pos_dy * tex_dx.y);
+  t = normalize(t - ng * dot(ng, t));
+  vec3 b = normalize(cross(ng, t)) * sign(det);
+  return normalize(mat3(t, b, ng) * nTangent);
+}
+
+void main() {
+  vec2 cuv = (vUv / max(cellSize, 1e-4) + 0.5) / max(gridSize, vec2(1.0));
+  vec4 w = texture(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 ng = normalize(vNormal);
+  vec3 bw = abs(ng);
+  bw = bw / max(bw.x + bw.y + bw.z, 1e-4);
+  vec3 albedo = vec3(0.0);
+  vec3 nrm = vec3(0.0);
+  splatLayer(albedo0, normals01, 0.0, tiling.x, normalScale.x, triplanar.x, w.r, vUv, vWorldPos, bw, albedo, nrm);
+  splatLayer(albedo1, normals01, 1.0, tiling.y, normalScale.y, triplanar.y, w.g, vUv, vWorldPos, bw, albedo, nrm);
+  splatLayer(albedo2, normals23, 0.0, tiling.z, normalScale.z, triplanar.z, w.b, vUv, vWorldPos, bw, albedo, nrm);
+  splatLayer(albedo3, normals23, 1.0, tiling.w, normalScale.w, triplanar.w, w.a, vUv, vWorldPos, bw, albedo, nrm);
+  vec3 n = applyTangentNormal(normalize(nrm), ng);
+  vec3 v = normalize(cameraPosition - vWorldPos);
+  if (dot(ng, v) < 0.0) n = -n;
+  vec3 diffuseColor = albedo * tint;
+  vec3 color = shadePBR(n, v, diffuseColor, vec3(0.04), dot(roughness, w), 1.0);
+  fragColor = vec4(tonemap(color), 1.0);
+}
+`
+
+// The twin of unlit.mat: factor x map, both default white. OPAQUE — alpha plays no part (Filament's
+// unlit.mat declares baseColor as a float3 and ignores the map's alpha), so the fragment forces 1.
+export const unlitFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec4 baseColor;       // linear, premultiplied; factor over baseColorMap
+uniform sampler2D baseColorMap;
+out vec4 fragColor;
+
+vec3 tonemapUnlit(vec3 x) {
+  const float A = 2.51; const float B = 0.03; const float C = 2.43; const float D = 0.59; const float E = 0.14;
+  vec3 t = clamp((x * (A * x + B)) / (x * (C * x + D) + E), 0.0, 1.0);
+  return pow(t, vec3(1.0 / 2.2));
+}
+
+void main() {
+  vec4 c = baseColor * texture(baseColorMap, vUv);
+  fragColor = vec4(tonemapUnlit(c.rgb), 1.0);
+}
+`
+
+// The twin of unlit-transparent.mat: same maths on a float4 colour, PREMULTIPLIED at the end because
+// the blend func is (ONE, ONE_MINUS_SRC_ALPHA) — the straight-alpha inputs (a decoded PNG, and a
+// colour that PREMULTIPLIED_sRGB only converts without multiplying) are premultiplied exactly once,
+// after tonemapping. Getting this wrong is the classic bright halo around a faded sprite.
+export const unlitBlendFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec4 baseColor;       // linear, straight alpha; factor over baseColorMap
+uniform sampler2D baseColorMap;
+out vec4 fragColor;
+
+vec3 tonemapUnlit(vec3 x) {
+  const float A = 2.51; const float B = 0.03; const float C = 2.43; const float D = 0.59; const float E = 0.14;
+  vec3 t = clamp((x * (A * x + B)) / (x * (C * x + D) + E), 0.0, 1.0);
+  return pow(t, vec3(1.0 / 2.2));
+}
+
+void main() {
+  vec4 c = baseColor * texture(baseColorMap, vUv);
+  fragColor = vec4(tonemapUnlit(c.rgb) * c.a, c.a);
+}
+`
+
+// video.mat: unlit external sample, inverse-tonemapped by Filament so the pipeline round-trips.
+// Here we just pass the (sRGB-encoded) video texel through untouched.
+export const videoFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec2 vUv;
+in vec3 vWorldPos;
+in vec3 vNormal;
+uniform sampler2D baseColorMap;
+out vec4 fragColor;
+void main() {
+  fragColor = vec4(texture(baseColorMap, vUv).rgb, 1.0);
+}
+`
+
+// shadow.mat: invisible shadow-catcher plane (shadowMultiplier) — opacity = color.a where shadowed.
+export const shadowCatcherFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec4 color; // linear, premultiplied
+${LIGHTING_CHUNK}
+out vec4 fragColor;
+void main() {
+  float vis = sampleShadowPCF();
+  float shadowAmount = 1.0 - vis;
+  fragColor = vec4(color.rgb * shadowAmount, color.a * shadowAmount);
+}
+`
+
+// glTF PBR (metallic-roughness) — configured with #define flags per material.
+export const gltfVertex = (defines: string): string => vertex(defines)
+export const litVertex = vertex('')
+
+export const gltfFragment = (defines: string): string => /* glsl */ `#version 300 es
+precision highp float;
+${defines}
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+#ifdef HAS_COLOR
+in vec4 vColor;
+#endif
+uniform vec3 cameraPosition;
+uniform vec4 uBaseColorFactor;
+uniform float uMetallic;
+uniform float uRoughness;
+uniform vec3 uEmissive;
+uniform float uAlphaCutoff;
+#ifdef HAS_BASECOLOR_MAP
+uniform sampler2D uBaseColorMap;
+#endif
+#ifdef HAS_MR_MAP
+uniform sampler2D uMRMap;
+#endif
+#ifdef HAS_NORMAL_MAP
+uniform sampler2D uNormalMap;
+#endif
+#ifdef HAS_OCCLUSION_MAP
+uniform sampler2D uOcclusionMap;
+#endif
+#ifdef HAS_EMISSIVE_MAP
+uniform sampler2D uEmissiveMap;
+#endif
+${LIGHTING_CHUNK}
+out vec4 fragColor;
+
+#ifdef HAS_NORMAL_MAP
+vec3 getNormal() {
+  vec3 pos_dx = dFdx(vWorldPos);
+  vec3 pos_dy = dFdy(vWorldPos);
+  vec2 tex_dx = dFdx(vUv);
+  vec2 tex_dy = dFdy(vUv);
+  float det = tex_dx.x * tex_dy.y - tex_dy.x * tex_dx.y;
+  if (abs(det) < 1e-8) return normalize(vNormal);
+  vec3 t = normalize(pos_dx * tex_dy.y - pos_dy * tex_dx.y);
+  vec3 ng = normalize(vNormal);
+  t = normalize(t - ng * dot(ng, t));
+  vec3 b = normalize(cross(ng, t)) * sign(det);
+  mat3 tbn = mat3(t, b, ng);
+  vec3 n = texture(uNormalMap, vUv).rgb * 2.0 - 1.0;
+  return normalize(tbn * n);
+}
+#endif
+
+void main() {
+  vec4 base = uBaseColorFactor;
+#ifdef HAS_BASECOLOR_MAP
+  base *= texture(uBaseColorMap, vUv);
+#endif
+#ifdef HAS_COLOR
+  base *= vColor;
+#endif
+#ifdef ALPHA_MASK
+  if (base.a < uAlphaCutoff) discard;
+#endif
+
+#ifdef UNLIT
+  // KHR_materials_unlit: the base colour IS the shaded colour — no lights, no IBL, no exposure
+  // (Filament's UNLIT shading model does the same, then tone-maps in post like everything else).
+#ifdef ALPHA_BLEND
+  fragColor = vec4(tonemap(base.rgb), base.a);
+#else
+  fragColor = vec4(tonemap(base.rgb), 1.0);
+#endif
+  return;
+#endif
+
+  float metallic = uMetallic;
+  float roughness = uRoughness;
+#ifdef HAS_MR_MAP
+  vec3 mr = texture(uMRMap, vUv).rgb;
+  roughness *= mr.g;
+  metallic *= mr.b;
+#endif
+
+  float occlusion = 1.0;
+#ifdef HAS_OCCLUSION_MAP
+  occlusion = texture(uOcclusionMap, vUv).r;
+#endif
+
+#ifdef HAS_NORMAL_MAP
+  vec3 n = getNormal();
+#else
+  vec3 n = normalize(vNormal);
+#endif
+  vec3 v = normalize(cameraPosition - vWorldPos);
+#ifdef DOUBLE_SIDED
+  if (dot(n, v) < 0.0) n = -n;
+#endif
+
+  vec3 diffuseColor = base.rgb * (1.0 - metallic);
+  vec3 f0 = mix(vec3(0.04), base.rgb, metallic);
+  vec3 color = shadePBR(n, v, diffuseColor, f0, roughness, occlusion);
+
+  vec3 emissive = uEmissive;
+#ifdef HAS_EMISSIVE_MAP
+  emissive *= texture(uEmissiveMap, vUv).rgb;
+#endif
+  color += emissive * iblLuminance * exposure;
+
+#ifdef ALPHA_BLEND
+  fragColor = vec4(tonemap(color), base.a);
+#else
+  fragColor = vec4(tonemap(color), 1.0);
+#endif
+}
+`
+
+// ---- wireframe (editor viewport modes) --------------------------------------------------------
+// Solid-color fragment for the LINES companion meshes (createViewerLite _setWireframeMode). Reuses
+// the standard vertex shaders (litVertex / gltfVertex('HAS_SKIN')) so skinned wires pose correctly;
+// the extra varyings they emit are simply unused here.
+export const wireFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 vWorldPos;
+in vec3 vNormal;
+in vec2 vUv;
+uniform vec3 uWireColor;
+out vec4 fragColor;
+void main() { fragColor = vec4(uWireColor, 1.0); }
+`
+
+// ---- shadow (depth) pass ----------------------------------------------------------------------
+
+/** Depth-only vertex stage (shadow map, selection mask). `instanced` reads the world matrix from
+ *  the batch stream instead of the modelMatrix uniform (batching.ts). */
+export const depthVertex = (skin: boolean, instanced = false): string => /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+${skin ? 'in vec3 normal;\nin vec2 uv;' : ''}
+${instanced ? 'in mat4 instanceMatrix;' : 'uniform mat4 modelMatrix;'}
+uniform mat4 shadowViewProjection;
+${skin ? SKIN_CHUNK : ''}
+void main() {
+  vec4 pos = vec4(position, 1.0);
+  ${skin ? 'pos = getSkinMatrix() * pos;' : ''}
+  gl_Position = shadowViewProjection * ${instanced ? 'instanceMatrix' : 'modelMatrix'} * pos;
+}
+`
+
+export const depthFragment = /* glsl */ `#version 300 es
+precision highp float;
+out vec4 fragColor;
+void main() { fragColor = vec4(1.0); }
+`
+
+// ---- color helpers ----------------------------------------------------------------------------
+
+export const srgbToLinear = (c: number): number =>
+  c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4)
+
+/** JS-side twin of the shader tonemap — for values written outside a shader (the clear color). */
+export const tonemapJs = (x: number): number => {
+  const t = Math.min(1, Math.max(0, (x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14)))
+  return Math.pow(t, 1 / 2.2)
+}
+
+/** 0xRRGGBB → linear [r,g,b] (setUniformRgb / RgbType::sRGB). */
+export const hexToLinearRgb = (hex: number): [number, number, number] => [
+  srgbToLinear(((hex >>> 16) & 0xff) / 255),
+  srgbToLinear(((hex >>> 8) & 0xff) / 255),
+  srgbToLinear((hex & 0xff) / 255),
+]
+
+/** 0xRRGGBBAA → linear premultiplied [r,g,b,a] (setUniformRgba / RgbaType::PREMULTIPLIED_sRGB). */
+export const hexToLinearRgba = (hex: number): [number, number, number, number] => [
+  srgbToLinear(((hex >>> 24) & 0xff) / 255),
+  srgbToLinear(((hex >>> 16) & 0xff) / 255),
+  srgbToLinear(((hex >>> 8) & 0xff) / 255),
+  (hex & 0xff) / 255,
+]
+
+// ---- particles (creator-particles streams; twins of creator-gl/materials/src/particles*.mat) ----
+// The stream carries per-vertex color + custom (size, rotation, opacity, frame); the look (flipbook
+// cells, softness, emission, additive, billboarding / stretch / ribbon) is the shader, driven by the
+// same uniforms the Filament materials declare. Output is premultiplied, tonemapped like unlit.
+// Not here: soft particles (depthFade) — the lite pipeline has no depth prepass to read.
+
+const PARTICLE_FRAG_COMMON = /* glsl */ `
+uniform sampler2D baseColorMap;
+uniform vec2 sheetSize;      // (cols, rows) of the flipbook sheet, both >= 1 (the SDK primes it)
+uniform float emissive;
+uniform float additive;
+uniform float softness;
+uniform float depthFade;     // declared so the SDK's write lands somewhere; ignored (no depth buffer)
+
+vec3 tonemapParticle(vec3 x) {
+  const float A = 2.51; const float B = 0.03; const float C = 2.43; const float D = 0.59; const float E = 0.14;
+  vec3 t = clamp((x * (A * x + B)) / (x * (C * x + D) + E), 0.0, 1.0);
+  return pow(t, vec3(1.0 / 2.2));
+}
+// Integer cell math: a float floor(frame / cols) lands one row early at row starts on the GPU.
+vec2 sheetCell(int fi) {
+  int sx = int(sheetSize.x + 0.5);
+  return vec2(float(fi - (fi / sx) * sx), float(fi / sx));
+}
+`
+
+export const particlesPointVertex = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+in vec4 color;
+in vec4 custom;
+uniform mat4 modelMatrix;
+uniform mat4 viewMatrix;
+uniform mat4 projectionMatrix;
+uniform float perspScale;    // viewportHeightPx / (2 tan(fov/2)): a true world-space diameter
+out vec4 vColor;
+out vec4 vCustom;
+void main() {
+  vec4 viewPos = viewMatrix * modelMatrix * vec4(position, 1.0);
+  float z = max(-viewPos.z, 1e-3);
+  gl_PointSize = custom.x * perspScale / z;
+  vColor = color;
+  vCustom = custom;
+  gl_Position = projectionMatrix * viewPos;
+}
+`
+
+export const particlesPointFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec4 vColor;
+in vec4 vCustom;
+${PARTICLE_FRAG_COMMON}
+out vec4 fragColor;
+void main() {
+  vec2 uv = gl_PointCoord.xy;
+  float rot = vCustom.y;
+  if (rot != 0.0) {
+    float co = cos(rot);
+    float si = sin(rot);
+    vec2 p = uv - vec2(0.5);
+    uv = vec2(co * p.x - si * p.y, si * p.x + co * p.y) + vec2(0.5);
+    if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) discard;
+  }
+  int total = int(sheetSize.x + 0.5) * int(sheetSize.y + 0.5);
+  int fi = int(floor(vCustom.w) + 0.5);
+  fi = fi - (fi / total) * total;
+  vec4 tex = texture(baseColorMap, (sheetCell(fi) + uv) / sheetSize);
+  float radial = 1.0 - smoothstep(0.0, 0.5, length(gl_PointCoord.xy - vec2(0.5)));
+  float shape = mix(1.0, radial, clamp(softness, 0.0, 1.0));
+  float alpha = tex.a * vColor.a * vCustom.z * shape;
+  vec3 rgb = tex.rgb * vColor.rgb * (1.0 + emissive);
+  fragColor = vec4(tonemapParticle(rgb) * alpha, alpha * (1.0 - clamp(additive, 0.0, 1.0)));
+}
+`
+
+export const particlesQuadVertex = /* glsl */ `#version 300 es
+precision highp float;
+in vec3 position;
+in vec4 color;
+in vec4 custom;      // size, rotation, opacity, frame
+in vec3 aux;         // quad: velocity (stretch axis); ribbon: strip tangent — sim space
+in vec2 corner;      // quad: ±0.5 square; ribbon: (u01 - 0.5, ±0.5 side)
+uniform mat4 modelMatrix;
+uniform mat4 viewMatrix;
+uniform mat4 projectionMatrix;
+uniform float mode;      // 0 camera billboard, 1 velocity-stretched, 2 ribbon strip
+uniform float stretch;   // (mode 1) extra length per unit of speed: length = size + stretch · |v|
+out vec4 vColor;
+out vec4 vCustom;
+out vec4 vQuadUv;        // xy: in-cell uv, zw: the softness basis
+void main() {
+  vec4 wp = modelMatrix * vec4(position, 1.0);
+  vec3 a = mat3(modelMatrix) * aux;
+  // the camera's world axes: rows of the view rotation (= columns of its inverse)
+  vec3 camX = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
+  vec3 camY = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
+  vec3 camZ = vec3(viewMatrix[0][2], viewMatrix[1][2], viewMatrix[2][2]);   // toward the camera
+  vec3 offset;
+  vec2 suv = corner;
+  if (mode < 0.5) {
+    float co = cos(custom.y);
+    float si = sin(custom.y);
+    vec2 rc = vec2(co * corner.x - si * corner.y, si * corner.x + co * corner.y);
+    offset = (camX * rc.x + camY * rc.y) * custom.x;
+  } else if (mode < 1.5) {
+    float speed = length(a);
+    vec3 dir = speed > 1e-4 ? a / speed : camY;
+    vec3 y = dir - camZ * dot(dir, camZ);
+    float yl = length(y);
+    y = yl > 1e-4 ? y / yl : camY;
+    vec3 x = normalize(cross(y, camZ));
+    offset = x * corner.x * custom.x + y * corner.y * (custom.x + stretch * speed * yl);
+  } else {
+    vec3 x = cross(a, camZ);
+    float xl = length(x);
+    x = xl > 1e-4 ? x / xl : camX;
+    offset = x * corner.y * custom.x;
+    suv = vec2(0.0, corner.y);
+  }
+  wp.xyz += offset;
+  vColor = color;
+  vCustom = custom;
+  vQuadUv = vec4(corner.x + 0.5, 0.5 - corner.y, suv.x, suv.y);
+  gl_Position = projectionMatrix * viewMatrix * wp;
+}
+`
+
+export const particlesQuadFragment = /* glsl */ `#version 300 es
+precision highp float;
+in vec4 vColor;
+in vec4 vCustom;
+in vec4 vQuadUv;
+${PARTICLE_FRAG_COMMON}
+uniform sampler2D emissiveMap;
+uniform vec3 emissiveColor;
+uniform float frameBlend;
+out vec4 fragColor;
+void main() {
+  vec2 uv = vQuadUv.xy;
+  float total = sheetSize.x * sheetSize.y;
+  float fidx = mod(vCustom.w, total);
+  float frame = floor(fidx);
+  int fi = int(frame + 0.5);
+  vec2 tuv = (sheetCell(fi) + uv) / sheetSize;
+  vec4 tex = texture(baseColorMap, tuv);
+  vec3 em = texture(emissiveMap, tuv).rgb;
+  if (frameBlend > 0.5) {
+    int ni = min(fi + 1, int(total + 0.5) - 1);
+    vec2 tuv2 = (sheetCell(ni) + uv) / sheetSize;
+    float f = fidx - frame;
+    tex = mix(tex, texture(baseColorMap, tuv2), f);
+    em = mix(em, texture(emissiveMap, tuv2).rgb, f);
+  }
+  float radial = 1.0 - smoothstep(0.0, 0.5, length(vQuadUv.zw));
+  float shape = mix(1.0, radial, clamp(softness, 0.0, 1.0));
+  float alpha = tex.a * vColor.a * vCustom.z * shape;
+  vec3 rgb = tex.rgb * vColor.rgb * (1.0 + emissive) + em * emissiveColor;
+  fragColor = vec4(tonemapParticle(rgb) * alpha, alpha * (1.0 - clamp(additive, 0.0, 1.0)));
+}
+`