@solidrt/3d 0.0.58 → 0.0.59

package/src/glsl.ts

@@ -1,7 +1,7 @@
 // The exported lighting GLSL: string constants an app composes into its
 // own shaderMaterial sources with plain template literals - the same
 // pieces the package's lit materials are built from (sceneSource is the
-// whole scene in one set; the lit, standard and unlit programs are
+// whole scene in one set; the phong, standard and unlit programs are
 // assembled from it), so a custom material never becomes second-class
 // (no preprocessor, no include resolver; the policy is argued in
 // okf/notes/3d-differentiators.md).
@@ -16,7 +16,7 @@
 // every function returns its raw term, weighting and color belong to the
 // caller.
 
-import type { CullMode, InstanceAttribute } from "@solidrt/core/gpu"
+import type { CullMode, VertexAttribute } from "@solidrt/core/gpu"
 
 // core/gpu's glsl tag, aliased locally (it is String.raw) so this module
 // stays runtime-pure: no flux:gpu import, so the checks/ rigs and any
@@ -24,7 +24,7 @@ import type { CullMode, InstanceAttribute } from "@solidrt/core/gpu"
 let glsl = String.raw
 
 /** The cap of the scene's light list (directional, spot and point nodes
- * alike; the hemisphere ambient is not in it) and of the `lit` fragment;
+ * alike; the hemisphere ambient is not in it) and of the stock lit fragments;
  * a custom fragment composes LIGHT_SLOTS and LIGHT_LOOKUP and loops to
  * `uLightCount`. A shader-source constant, so it is fixed for the app
  * (see okf/backlog/app-runtime-config.md). */
@@ -44,29 +44,31 @@ export const MAX_CASCADES = 4
  * every light is a fully cascaded sun. */
 export const MAX_SHADOW_MAPS = 8
 
-/** The instance attributes an instanced mesh's material declares
- * (`shaderMaterialClass({ instanceAttributes: INSTANCE_MATRIX_ATTRIBUTES
- * })`): the four vec4 columns of the per-instance matrix the spatial core
- * writes - the instance's placement inside the mesh (createInstancedMesh,
- * addInstance). Read them through INSTANCE_MATRIX. Slot 0, the core's
- * record; an app's own per-instance floats go in slot 1 (the style
- * record, see INSTANCE_COLOR_ATTRIBUTES). */
-export const INSTANCE_MATRIX_ATTRIBUTES: InstanceAttribute[] = [
-  { name: "iModel0", format: "vec4" },
-  { name: "iModel1", format: "vec4" },
-  { name: "iModel2", format: "vec4" },
-  { name: "iModel3", format: "vec4" },
+/** The record layout an instanced mesh's material declares as its first
+ * instance buffer (`shaderMaterialClass({ instanceBuffers: [{ attributes:
+ * INSTANCE_MATRIX_ATTRIBUTES }] })`): the four vec4 columns of the
+ * per-instance matrix the spatial core writes - the instance's placement
+ * inside the mesh (createInstancedMesh, addInstance). Read them through
+ * INSTANCE_MATRIX. An app's own per-instance values go in the second
+ * instance buffer (the style record, see INSTANCE_COLOR_ATTRIBUTES). */
+export const INSTANCE_MATRIX_ATTRIBUTES: VertexAttribute[] = [
+  { name: "iModel0", format: "float32x4" },
+  { name: "iModel1", format: "float32x4" },
+  { name: "iModel2", format: "float32x4" },
+  { name: "iModel3", format: "float32x4" },
 ]
 
 /** The per-instance color the stock materials read with `instanceColors`
  * (`in vec4 iColor`, premultiplied linear like aColor, forwarded as
- * vColor): a slot-1 attribute, so it is the instance's STYLE record -
- * app-owned, written with setInstanceStyle(instance, [r, g, b, a]) - beside
- * the core's matrix in slot 0. A custom class appends it (or any slot-1
- * layout of its own) to INSTANCE_MATRIX_ATTRIBUTES; the stock materials
- * start every instance at white. Three's instanceColor, Godot's
- * MultiMesh instance color. */
-export const INSTANCE_COLOR_ATTRIBUTES: InstanceAttribute[] = [{ name: "iColor", format: "vec4", slot: 1 }]
+ * vColor): the second instance buffer's layout, so it is the instance's
+ * STYLE record - app-owned, written with setInstanceStyle(instance, [r,
+ * g, b, a]) - beside the core's matrix in the first. A custom class
+ * declares it (or any style layout of its own) as its second instance
+ * buffer; the stock materials start every instance at white. Stored as
+ * half floats: 8 bytes per instance, and a linear color at 10-bit
+ * mantissa precision shows none of the banding an 8-bit unorm would in
+ * the darks. Three's instanceColor, Godot's MultiMesh instance color. */
+export const INSTANCE_COLOR_ATTRIBUTES: VertexAttribute[] = [{ name: "iColor", format: "float16x4" }]
 
 /**
  * The vertex-stage declarations over INSTANCE_MATRIX_ATTRIBUTES:
@@ -106,7 +108,9 @@ export const INSTANCE_MATRIX = glsl`
  * `normalize(uCamPos - vWorldPos)`.
  */
 /** The skinned-layout declarations a vertex stage splices in: the
- * aJoints/aWeights channels, the `uBones` palette and `mat4 boneAt(int)`.
+ * aJoints (integer input, fed by the layout's uint8x4 or uint16x4 joint
+ * channel) and aWeights channels, the `uBones` palette and `mat4
+ * boneAt(uint)`.
  * The palette is a float texture, not a uniform array, so rig size is
  * bounded only by texture height (>= 2048 everywhere), never by the
  * vertex uniform budget: an rgba32f texture 4 texels wide, one row per
@@ -115,12 +119,13 @@ export const INSTANCE_MATRIX = glsl`
  * skinned mesh). Pair with
  * SKIN_MATRIX in main(). */
 export const SKIN_DECLS = glsl`
-  in vec4 aJoints;
+  in uvec4 aJoints;
   in vec4 aWeights;
   uniform sampler2D uBones;
-  mat4 boneAt(int j) {
-    return mat4(texelFetch(uBones, ivec2(0, j), 0), texelFetch(uBones, ivec2(1, j), 0),
-      texelFetch(uBones, ivec2(2, j), 0), texelFetch(uBones, ivec2(3, j), 0));
+  mat4 boneAt(uint j) {
+    int row = int(j);
+    return mat4(texelFetch(uBones, ivec2(0, row), 0), texelFetch(uBones, ivec2(1, row), 0),
+      texelFetch(uBones, ivec2(2, row), 0), texelFetch(uBones, ivec2(3, row), 0));
   }
 `
 /** The linear-blend skin matrix, spliced into main() after SKIN_DECLS:
@@ -128,25 +133,81 @@ export const SKIN_DECLS = glsl`
  * through `mat3(skin)` - exact for rigid bones, the standard
  * approximation under bone scale. */
 export const SKIN_MATRIX = glsl`
-    mat4 skin = aWeights.x * boneAt(int(aJoints.x)) + aWeights.y * boneAt(int(aJoints.y)) +
-      aWeights.z * boneAt(int(aJoints.z)) + aWeights.w * boneAt(int(aJoints.w));
+    mat4 skin = aWeights.x * boneAt(aJoints.x) + aWeights.y * boneAt(aJoints.y) +
+      aWeights.z * boneAt(aJoints.z) + aWeights.w * boneAt(aJoints.w);
 `
 
+/** The morph-target declarations a vertex stage splices in: `uMorphs`,
+ * the geometry's targets packed sparse by vertex (see MorphTargets in
+ * geometry.ts: a header texel per vertex, then two-texel entries), laid
+ * into rows of `uMorphWidth` texels; `uMorphWeights`, the weights texture
+ * (four weights per texel, one row per weights owner - the spatial core
+ * writes it from the node's register), read at row `uMorphRow +
+ * gl_InstanceID`: a plain mesh's one row, or on an instanced mesh the
+ * instance's own row, its record slot (the population's texture has a
+ * row per slot), so every copy morphs by its own weights with no
+ * per-record data. Pair with MORPH_APPLY in main(). The geometry's GPU
+ * buffers bind uMorphs, the mesh's morph owner (the population, when
+ * instanced) binds uMorphWeights and the two ints. */
+export const MORPH_DECLS = glsl`
+  uniform sampler2D uMorphs;
+  uniform sampler2D uMorphWeights;
+  uniform int uMorphWidth;
+  uniform int uMorphRow;
+  vec4 morphTexel(int i) {
+    return texelFetch(uMorphs, ivec2(i % uMorphWidth, i / uMorphWidth), 0);
+  }
+  float morphWeight(int t) {
+    vec4 four = texelFetch(uMorphWeights, ivec2(t >> 2, uMorphRow + gl_InstanceID), 0);
+    int c = t & 3;
+    return c == 0 ? four.x : c == 1 ? four.y : c == 2 ? four.z : four.w;
+  }
+`
+/** The morph displacement, spliced into main() after MORPH_DECLS: walks
+ * this vertex's entries (gl_VertexID indexes the headers) and leaves
+ * `vec3 morphPos` and `vec3 morphNormal`, the base channels plus each
+ * target's delta times its weight - apply the skin matrix (when any) and
+ * uModel to THESE. Zero-weight targets still cost their fetches; a
+ * vertex no target moves costs one. The normal form needs `aNormal`;
+ * MORPH_APPLY_POSITION is the same walk for a stage without one. */
+export const MORPH_APPLY = morphApply(true)
+export const MORPH_APPLY_POSITION = morphApply(false)
+
+function morphApply(normals: boolean): string {
+  return glsl`
+    vec3 morphPos = aPos;
+    ${normals ? "vec3 morphNormal = aNormal;" : ""}
+    {
+      vec4 morphHead = morphTexel(gl_VertexID);
+      int morphAt = int(morphHead.x);
+      int morphCount = int(morphHead.y);
+      for (int k = 0; k < morphCount; k++) {
+        vec4 entry = morphTexel(morphAt + 2 * k);
+        float w = morphWeight(int(entry.x));
+        morphPos += w * entry.yzw;
+        ${normals ? "morphNormal += w * morphTexel(morphAt + 2 * k + 1).xyz;" : ""}
+      }
+    }
+`
+}
+
 // The per-instance placement, spliced into a vertex stage's position and
-// normal math for an instanced material: the skin (when any) first, then
-// the instance's matrix inside the mesh, then uModel - so a skinned
-// instanced fleet poses every copy by the one shared palette and places
-// each by its own record.
-function instancedPosition(skinned: boolean, instanced: boolean): string {
-  let local = skinned ? "(skin * vec4(aPos, 1.0))" : "vec4(aPos, 1.0)"
+// normal math for an instanced material: the morph (when any) and then
+// the skin (when any) first, then the instance's matrix inside the mesh,
+// then uModel - so a skinned instanced fleet poses every copy by the one
+// shared palette and places each by its own record.
+function instancedPosition(skinned: boolean, instanced: boolean, morphed = false): string {
+  let base = morphed ? "morphPos" : "aPos"
+  let local = skinned ? `(skin * vec4(${base}, 1.0))` : `vec4(${base}, 1.0)`
   return instanced ? `uModel * (instanceMatrix() * ${local})` : `uModel * ${local}`
 }
-function instancedNormal(skinned: boolean, instanced: boolean): string {
-  let local = skinned ? "(mat3(skin) * aNormal)" : "aNormal"
+function instancedNormal(skinned: boolean, instanced: boolean, morphed = false): string {
+  let base = morphed ? "morphNormal" : "aNormal"
+  let local = skinned ? `(mat3(skin) * ${base})` : base
   return instanced ? `mat3(uNormal) * (instanceNormalMatrix() * ${local})` : `mat3(uNormal) * ${local}`
 }
 
-// The one lit vertex template: the standard prefix always, aColor and
+// The one lit vertex template: the base prefix always, aColor and
 // aUV2 only when the fragment reads them (an `in` the source mentions
 // makes the material require that channel, so the blocks must be absent,
 // not inactive), the skin blocks only for a skinned material (they make
@@ -154,7 +215,7 @@ function instancedNormal(skinned: boolean, instanced: boolean): string {
 // and color only for an instanced one. vColor carries the vertex color,
 // the instance color, or their product. LIT_VERTEX / LIT_VERTEX_COLORED
 // are its two named forms; litVertex(o) picks per option set.
-function litVertexSource(colored: boolean, uv2: boolean, skinned: boolean, instanced: boolean, instanceColors: boolean): string {
+function litVertexSource(colored: boolean, uv2: boolean, skinned: boolean, instanced: boolean, instanceColors: boolean, morphed = false): string {
   let color = colored && instanceColors ? "aColor * iColor" : colored ? "aColor" : instanceColors ? "iColor" : ""
   return glsl`
   in vec3 aPos;
@@ -162,6 +223,7 @@ function litVertexSource(colored: boolean, uv2: boolean, skinned: boolean, insta
   in vec2 aUV;
   ${colored ? "in vec4 aColor;" : ""}
   ${uv2 ? "in vec2 aUV2;" : ""}
+  ${morphed ? MORPH_DECLS : ""}
   ${skinned ? SKIN_DECLS : ""}
   ${instanced ? INSTANCE_MATRIX : ""}
   ${instanceColors ? "in vec4 iColor;" : ""}
@@ -175,11 +237,12 @@ function litVertexSource(colored: boolean, uv2: boolean, skinned: boolean, insta
   ${uv2 ? "out vec2 vUv2;" : ""}
 
   void main() {
+    ${morphed ? MORPH_APPLY : ""}
     ${skinned ? SKIN_MATRIX : ""}
-    vec4 world = ${instancedPosition(skinned, instanced)};
+    vec4 world = ${instancedPosition(skinned, instanced, morphed)};
     gl_Position = uViewProj * world;
     vWorldPos = world.xyz;
-    vNormal = ${instancedNormal(skinned, instanced)};
+    vNormal = ${instancedNormal(skinned, instanced, morphed)};
     vUv = aUV;
     ${color ? `vColor = ${color};` : ""}
     ${uv2 ? "vUv2 = aUV2;" : ""}
@@ -308,7 +371,7 @@ export const PBR = glsl`
  * folded in) and `uLightParams[i]` (cosInner, cosOuter, distance, decay
  * - the cone cosines a spot fades between, the falloff cutoff and
  * exponent a spot or point attenuates by; unused for a directional).
- * Compose it before LIGHT_LOOKUP; `lit` is the shape.
+ * Compose it before LIGHT_LOOKUP; the stock lit program is the shape.
  */
 export const LIGHT_SLOTS = glsl`
   uniform int uLightCount;
@@ -331,7 +394,7 @@ export const LIGHT_SLOTS = glsl`
  * zero at `distance` (0 = no cutoff; Three's punctual-light falloff), a
  * spot's additionally faded across its cone from cosInner to cosOuter.
  * Zero means the light cannot reach the fragment - skip its shadow
- * lookup and its terms (`lit` does exactly that).
+ * lookup and its terms (the stock lit program does exactly that).
  */
 export const LIGHT_LOOKUP = glsl`
   // Floors the falloff divisors so a fragment at the light's own
@@ -447,7 +510,7 @@ export const FOG = glsl`
  * and `vec3 linearToSrgb(vec3)`, clamped at zero. An "rgba8-srgb" texture
  * decodes in hardware and needs neither; these serve pixels a format
  * cannot tag (a render target sampled as a map) and the output stage.
- * OUTPUT includes this set - never compose both.
+ * RESOLVE includes this set - never compose both.
  */
 export const SRGB = glsl`
   vec3 srgbToLinear(vec3 c) {
@@ -461,25 +524,48 @@ export const SRGB = glsl`
 `
 
 /**
- * The output stage every library fragment ends with: `vec4
- * outputColor(vec3 rgb, float alpha)` takes the PREMULTIPLIED linear
- * result and its alpha, applies the scene's exposure and tone mapping
- * (`uniform float uExposure`; `uniform float uToneMapping`, 0 none, 1
- * ACES - the shared params scene.setExposure / setToneMapping write),
- * encodes to sRGB and returns the premultiplied pixel the target holds.
- * It un-premultiplies inside so the encode is exact at partial alpha.
- * Compose it last in a custom fragment: `fragColor = outputColor(rgb,
- * alpha);` - a fragment that writes fragColor directly writes final
- * encoded pixels and skips exposure and tone mapping. Includes SRGB.
+ * The LOD cross-fade: `uLodFade` is (threshold, side) - the scene writes
+ * the band position of the level this entry draws (see createLod's
+ * `fade`), `[1, 1]` when solid. Inside a band the nearer level keeps the
+ * fragments whose screen hash falls below the threshold (side 1) and the
+ * farther level the rest (side -1): a partition, so nothing draws twice
+ * and nothing is missed. Call `lodFade()` first thing in main. Every
+ * stock fragment composes it; a custom class that declares `uLodFade`
+ * opts in (the scene detects the name, like uNormal).
  */
-export const OUTPUT = glsl`
+export const LOD_FADE = glsl`
+  uniform vec2 uLodFade;
+  // Interleaved gradient noise (Jimenez 2014): a screen-position hash
+  // whose pattern stays put as the band moves, so the dissolve reads as
+  // a steady grain rather than a crawl.
+  float lodHash(vec2 p) {
+    return fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715))));
+  }
+  void lodFade() {
+    if (uLodFade.x < 1.0) {
+      if ((lodHash(gl_FragCoord.xy) - uLodFade.x) * uLodFade.y >= 0.0) discard;
+    }
+  }
+`
+
+/**
+ * The resolve set: the display stage of a target, run ONCE per pixel by
+ * the resolve pass that turns a scene buffer (premultiplied linear light,
+ * half float where the device renders it) into the displayed rgba8
+ * pixels. `vec4 resolveColor(vec3 rgb, float alpha)` takes a buffer
+ * texel, applies the scene's exposure and tone mapping (`uniform float
+ * uExposure`; `uniform float uToneMapping`, 0 none, 1 ACES, 2 AgX, 3
+ * Neutral - the shared params scene.setExposure / setToneMapping
+ * write), clamps, encodes to
+ * sRGB with an ordered dither against 8-bit banding, and returns the
+ * premultiplied pixel. It un-premultiplies inside so the encode is exact
+ * at partial alpha. A custom resolve (SceneOptions.resolve) gets this set
+ * declared and ends with it; a scene fragment never composes it - a
+ * fragment writes linear light (see sceneOutput). Includes SRGB.
+ */
+export const RESOLVE = glsl`
   uniform float uExposure;
   uniform float uToneMapping;
-  // 1 (the scene's default) clamps and encodes to sRGB for display; 0
-  // writes linear light unclamped, what a reflection probe's faces hold
-  // so the environment lookups read radiance (the scene sets it per
-  // target; an 8-bit target clamps it on write regardless).
-  uniform float uOutputEncode;
   ${SRGB}
   // Stephen Hill's fit of the ACES RRT and ODT (Three's ACESFilmic, Godot's
   // ACES): the matrices between sRGB and the fit's working space, and the
@@ -503,18 +589,176 @@ export const OUTPUT = glsl`
     c = acesFit(c);
     return clamp(ACES_OUTPUT * c, 0.0, 1.0);
   }
-  vec4 outputColor(vec3 rgb, float alpha) {
+  // AgX (Blender's, through Filament and Three's AgXToneMapping): rec
+  // 2020 primaries in, an inset toward gray, log2 encoding over the
+  // scene's dynamic range, the sigmoid, the outset, back to sRGB
+  // primaries. The 6th-order fit of the sigmoid is the iolite
+  // approximation Three ships.
+  const mat3 AGX_SRGB_TO_REC2020 = mat3(
+    0.6274, 0.0691, 0.0164,
+    0.3293, 0.9195, 0.0880,
+    0.0433, 0.0113, 0.8956);
+  const mat3 AGX_REC2020_TO_SRGB = mat3(
+    1.6605, -0.1246, -0.0182,
+    -0.5876, 1.1329, -0.1006,
+    -0.0728, -0.0083, 1.1187);
+  const mat3 AGX_INSET = mat3(
+    0.856627153315983, 0.137318972929847, 0.11189821299995,
+    0.0951212405381588, 0.761241990602591, 0.0767994186031903,
+    0.0482516061458583, 0.101439036467562, 0.811302368396859);
+  const mat3 AGX_OUTSET = mat3(
+    1.1271005818144368, -0.1413297634984383, -0.14132976349843826,
+    -0.11060664309660323, 1.157823702216272, -0.11060664309660294,
+    -0.016493938717834573, -0.016493938717834257, 1.2519364065950405);
+  // log2 of middle gray (0.18) at the range's ends, 10 stops below and
+  // 6.5 above.
+  const float AGX_MIN_EV = -12.47393;
+  const float AGX_MAX_EV = 4.026069;
+  // The encoded value's display gamma before the primaries go back.
+  const float AGX_GAMMA = 2.2;
+  vec3 agxSigmoid(vec3 x) {
+    vec3 x2 = x * x;
+    vec3 x4 = x2 * x2;
+    return 15.5 * x4 * x2 - 40.14 * x4 * x + 31.96 * x4 - 6.868 * x2 * x + 0.4298 * x2 + 0.1191 * x - 0.00232;
+  }
+  vec3 agxToneMap(vec3 c) {
+    c = AGX_INSET * (AGX_SRGB_TO_REC2020 * c);
+    c = log2(max(c, vec3(1e-10)));
+    c = clamp((c - AGX_MIN_EV) / (AGX_MAX_EV - AGX_MIN_EV), 0.0, 1.0);
+    c = AGX_OUTSET * agxSigmoid(c);
+    c = pow(max(c, vec3(0.0)), vec3(AGX_GAMMA));
+    return clamp(AGX_REC2020_TO_SRGB * c, 0.0, 1.0);
+  }
+  // Khronos PBR Neutral (Three's NeutralToneMapping, Unity's Neutral):
+  // hue-preserving, a black-level lift below a knee, then a soft peak
+  // compression above START_COMPRESSION that desaturates toward white.
+  const float NEUTRAL_START_COMPRESSION = 0.8 - 0.04;
+  const float NEUTRAL_DESATURATION = 0.15;
+  const float NEUTRAL_KNEE = 0.08;
+  const float NEUTRAL_KNEE_CURVE = 6.25;
+  const float NEUTRAL_OFFSET = 0.04;
+  vec3 neutralToneMap(vec3 c) {
+    float x = min(c.r, min(c.g, c.b));
+    float offset = x < NEUTRAL_KNEE ? x - NEUTRAL_KNEE_CURVE * x * x : NEUTRAL_OFFSET;
+    c -= offset;
+    float peak = max(c.r, max(c.g, c.b));
+    if (peak < NEUTRAL_START_COMPRESSION) return max(c, vec3(0.0));
+    float d = 1.0 - NEUTRAL_START_COMPRESSION;
+    float newPeak = 1.0 - d * d / (peak + d - NEUTRAL_START_COMPRESSION);
+    c *= newPeak / peak;
+    float g = 1.0 - 1.0 / (NEUTRAL_DESATURATION * (peak - newPeak) + 1.0);
+    return clamp(mix(c, vec3(newPeak), g), 0.0, 1.0);
+  }
+  // Debanding: one 8-bit step of interleaved gradient noise (Jimenez
+  // 2014) centered on zero, added to the encoded value before the target
+  // quantizes it, so a slow gradient dithers instead of stepping.
+  const float DITHER_STEP = 1.0 / 255.0;
+  float resolveDither(vec2 p) {
+    return fract(52.9829189 * fract(dot(p, vec2(0.06711056, 0.00583715)))) - 0.5;
+  }
+  vec4 resolveColor(vec3 rgb, float alpha) {
     vec3 c = alpha > 0.0 ? rgb / alpha : rgb;
     c *= uExposure;
-    if (uToneMapping > 0.5) c = acesToneMap(c);
-    // Linear output keeps its range (a half-float probe holds a sun's
-    // radiance); the display encode is 8-bit and clamps first.
-    if (uOutputEncode > 0.5) c = linearToSrgb(clamp(c, 0.0, 1.0));
-    else c = max(c, vec3(0.0));
+    if (uToneMapping > 2.5) c = neutralToneMap(c);
+    else if (uToneMapping > 1.5) c = agxToneMap(c);
+    else if (uToneMapping > 0.5) c = acesToneMap(c);
+    c = linearToSrgb(clamp(c, 0.0, 1.0));
+    c += resolveDither(gl_FragCoord.xy) * DITHER_STEP;
     return vec4(c * alpha, alpha);
   }
 `
 
+/**
+ * The default resolve fragment (SceneOptions.resolve when absent): one
+ * sample of the scene buffer through resolveColor. The contract a custom
+ * resolve gets: `vUV` (0..1, origin top-left), `iResolution`, `fragColor`,
+ * `uniform sampler2D uScene` (the buffer, premultiplied linear) and the
+ * RESOLVE set, all declared by the preamble; any name written through
+ * scene.setParams (uExposure and uToneMapping among them) is readable.
+ * Start a grade from this source and end in resolveColor.
+ */
+export const DEFAULT_RESOLVE = glsl`
+  void main() {
+    vec4 s = texture(uScene, vUV);
+    fragColor = resolveColor(s.rgb, s.a);
+  }
+`
+
+/**
+ * The default resolve while the stock bloom is on (SceneOptions.bloom):
+ * the buffer's texel plus the blurred excess the bloom chain rendered,
+ * bound on the resolve target as `uniform sampler2D uBloom` with its
+ * weight in `uniform float uBloomIntensity` - both declared by the
+ * source, not the preamble. The glow is LIGHT over the pixel whatever it
+ * covers: the alpha grows with the glow's brightness (a premultiplied
+ * light layer), so it shows over a transparent backdrop - a view with no
+ * clearColor composited over UI - and an opaque pixel is exactly the
+ * sum. A custom resolve composes the stock bloom by declaring the same
+ * two names and adding the term; start from this.
+ */
+export const BLOOM_RESOLVE = glsl`
+  uniform sampler2D uBloom;
+  uniform float uBloomIntensity;
+  void main() {
+    vec4 s = texture(uScene, vUV);
+    vec3 glow = texture(uBloom, vUV).rgb * uBloomIntensity;
+    float coverage = clamp(max(glow.r, max(glow.g, glow.b)), 0.0, 1.0);
+    fragColor = resolveColor(s.rgb + glow, max(s.a, coverage));
+  }
+`
+
+/**
+ * The stock bloom's threshold pass (a shader texture over the buffer):
+ * the texel's excess over `uniform float uThreshold` by its brightest
+ * channel, so a colored highlight keeps its hue, black below it.
+ */
+export const BLOOM_THRESHOLD = glsl`
+  uniform sampler2D uSource;
+  uniform float uThreshold;
+  void main() {
+    vec4 s = texture(uSource, vUV);
+    vec3 c = s.a > 0.0 ? s.rgb / s.a : s.rgb;
+    float peak = max(max(c.r, c.g), c.b);
+    float keep = max(peak - uThreshold, 0.0) / max(peak, 0.0001);
+    fragColor = vec4(c * keep, 1.0);
+  }
+`
+
+/**
+ * The stock bloom's blur pass: a 9-tap gaussian along `uniform vec2
+ * uDir` (one texel step on the given axis), run across then down per
+ * round of the chain.
+ */
+export const BLOOM_BLUR = glsl`
+  uniform sampler2D uSource;
+  uniform vec2 uDir;
+  const float WEIGHT[5] = float[5](0.2270270270, 0.1945945946, 0.1216216216, 0.0540540541, 0.0162162162);
+  void main() {
+    vec2 step = uDir / iResolution;
+    vec3 sum = texture(uSource, vUV).rgb * WEIGHT[0];
+    for (int i = 1; i < 5; i++) {
+      vec2 o = step * float(i);
+      sum += texture(uSource, vUV + o).rgb * WEIGHT[i];
+      sum += texture(uSource, vUV - o).rgb * WEIGHT[i];
+    }
+    fragColor = vec4(sum, 1.0);
+  }
+`
+
+/**
+ * A resolve source as a shader-texture fragment of your own: `uniform
+ * sampler2D uScene` and the RESOLVE set declared over `source` (default
+ * DEFAULT_RESOLVE), the engine preamble supplying vUV, iResolution and
+ * fragColor. The way an app resolves a buffer the library does not - the
+ * atlas its tiled views (`into`) render linear light into:
+ * `createShaderTexture(resolveFragment(), w, h, resolveParams(opts), {
+ * textures: { uScene: atlas } })`. A shader target validates its params
+ * strictly, so write both uExposure and uToneMapping (resolveParams does).
+ */
+export function resolveFragment(source: string = DEFAULT_RESOLVE): string {
+  return "uniform sampler2D uScene;\n" + RESOLVE + "\n" + source
+}
+
 /**
  * The scene's environment as a reflecting program declares it: `uEnv`
  * (a samplerCube the scene binds on every receiving target - a 1x1 black
@@ -539,7 +783,7 @@ export const OUTPUT = glsl`
  * camera) at roughness `sqrt(2 / (shininess + 2))`, so a wide sheen
  * reflects a blurred environment and a mirror dot a sharp one. `envWeight(n, v,
  * reflectivity)` is the Schlick fresnel weight: `reflectivity` face-on,
- * 1 at grazing, 0 with no environment. `lit` applies them as
+ * 1 at grazing, 0 with no environment. `phong` applies them as
  * `rgb = mix(rgb, envReflection(n, v, uShininess), envWeight(n, v,
  * uReflectivity))` - Three's MixOperation with a fresnel weight. Every
  * lookup is a plain `texture(uEnv, dir)` in world space: a cube map here
@@ -593,7 +837,8 @@ export const ENVIRONMENT = glsl`
  * LIGHT_SLOTS, this, SHADOW, then SHADOW_LOOKUP (in that order - the
  * lookup reads the light type and position for a point light's face
  * select) and multiplies
- * light i's term by `lightShadow(i, worldPos, n)` - `lit` is the shape. A
+ * light i's term by `lightShadow(i, worldPos, n)` - the stock lit program
+ * is the shape. A
  * material that does not receive composes none of it, so it declares no
  * sampler for nothing.
  */
@@ -731,7 +976,7 @@ export const SHADOW_LOOKUP = glsl`
 
 /**
  * The material defaults every Surface starts from (`surfaceOf`) and the
- * `lit`/`standard` options fall back to: one table, so a custom fragment
+ * `phong`/`standard` options fall back to: one table, so a custom fragment
  * that builds its own Surface and a stock material agree on what
  * "unspecified" means.
  */
@@ -765,7 +1010,7 @@ export const SURFACE_DEFAULTS = {
  * `Surface surfaceOf(vec4 base, vec3 normal)` fills the rest with
  * SURFACE_DEFAULTS (no emissive, no ambient), so a fragment sets only
  * what it means. One struct for both light models, as Godot and Unity
- * have it, so a `surface` function (litFragment's slot) has one
+ * have it, so a `surface` function (phongFragment's slot) has one
  * signature whatever material it sits in; the model that shades reads
  * its own fields and ignores the other's. Included by sceneSource - never
  * compose both.
@@ -811,19 +1056,21 @@ export type SceneSourceOptions = {
    * diffuse and the split-sum specular. False declares no environment
    * cube and shades with the lights alone. Needs `lights`. */
   env?: boolean
-  /** Fog inside sceneOutput. False leaves the fog set out. */
-  fog?: boolean
+  /** Fog inside sceneOutput. False leaves the fog set out; "additive"
+   * composes fogAdditive instead of fog, the form a `blend: "add"` draw
+   * needs (it fades toward black, not the fog color). */
+  fog?: boolean | "additive"
 }
 
 /**
  * The scene as a program declares it, in one set: everything a fragment
  * needs to be a citizen of the scene - lit by its lights, shadowed by its
- * casters, reflecting its environment, fogged, exposed, tone mapped and
- * encoded like the stock materials, because the stock materials are
- * built from this very source. It declares `uCamPos`, `uHemiSky` /
- * `uHemiGround`, LIGHT_SLOTS + LIGHT_LOOKUP, the SHADOW trio, the pure
- * light functions (HEMISPHERE, LAMBERT, BLINN_SPECULAR, PBR),
- * ENVIRONMENT, FOG and OUTPUT (per the flags), SURFACE, and exports:
+ * casters, reflecting its environment and fogged like the stock
+ * materials, because the stock materials are built from this very
+ * source. It declares `uCamPos`, `uHemiSky` / `uHemiGround`, LIGHT_SLOTS
+ * + LIGHT_LOOKUP, the SHADOW trio, the pure light functions (HEMISPHERE,
+ * LAMBERT, BLINN_SPECULAR, PBR), ENVIRONMENT and FOG (per the flags),
+ * SURFACE, and exports:
  *
  *   struct SceneLight { vec3 dir; vec3 color; };
  *   SceneLight sceneLight(int i, vec3 position, vec3 normal);
@@ -838,7 +1085,7 @@ export type SceneSourceOptions = {
  * `uLightCount` (URP's GetAdditionalLight, Godot's light() inputs), and
  * the one that makes a spot light impossible to render as a directional.
  *
- * The shade functions are the whole light loop of `lit` (Blinn-Phong)
+ * The shade functions are the whole light loop of `phong` (Blinn-Phong)
  * and `standard` (GGX): hemisphere plus `Surface.ambient` plus every
  * light's diffuse and specular, the environment term, then the emissive,
  * returning linear PREMULTIPLIED rgb. A term added by hand after them is
@@ -848,8 +1095,12 @@ export type SceneSourceOptions = {
  * stage carries the world position in.
  *
  * `sceneOutput` is the tail every library fragment ends with: fog over
- * the premultiplied color, then OUTPUT's exposure, tone mapping and
- * encode - the one place a post effect or a scene buffer change lands.
+ * the premultiplied color, clamped at zero, and that is the pixel the
+ * scene buffer holds - LINEAR light, unclamped above (a sun disc of 40
+ * stays 40 in a half-float buffer). Exposure, tone mapping and the sRGB
+ * encode happen once per pixel in the target's resolve pass (RESOLVE),
+ * never in a scene fragment: a fragment that writes fragColor directly
+ * writes linear premultiplied light too.
  *
  *   ${SCENE}
  *   void main() {
@@ -866,7 +1117,7 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
   let lights = o.lights !== false
   let receiveShadow = lights && o.receiveShadow !== false
   let env = lights && o.env !== false
-  let fog = o.fog !== false
+  let fog = o.fog ?? true
   return glsl`
     ${SURFACE}
     ${lights || fog ? "uniform vec3 uCamPos;" : ""}
@@ -895,12 +1146,11 @@ export function sceneSource(o: SceneSourceOptions = {}): string {
     }
     ${env ? ENVIRONMENT : ""}
     ${fog ? FOG : ""}
-    ${OUTPUT}
     ${lights ? sceneShadeSource(receiveShadow, env) : ""}
 
     vec4 sceneOutput(vec3 rgb, float alpha, vec3 position) {
-      ${fog ? "rgb = fog(rgb, alpha, position, uCamPos);" : ""}
-      return outputColor(rgb, alpha);
+      ${fog === "additive" ? "rgb = fogAdditive(rgb, position, uCamPos);" : fog ? "rgb = fog(rgb, alpha, position, uCamPos);" : ""}
+      return vec4(max(rgb, vec3(0.0)), alpha);
     }
   `
 }
@@ -910,7 +1160,8 @@ export const SCENE = sceneSource()
 
 // The light accessor and the two shade functions, over the sets
 // sceneSource composed before them. A light that cannot reach the point
-// is skipped whole (no shadow tap, no terms), the gate `lit` always had.
+// is skipped whole (no shadow tap, no terms), the gate the stock lit
+// program always had.
 function sceneShadeSource(receiveShadow: boolean, env: boolean): string {
   return glsl`
     struct SceneLight {
@@ -1021,8 +1272,10 @@ export type LitSourceOptions = {
    * alpha falls below it (the cutoff is a per-entry uniform, so one
    * program serves every value). */
   alphaTest?: boolean
-  /** Compose the scene's fog over the result (default true). */
-  fog?: boolean
+  /** Compose the scene's fog over the result (default true); "additive"
+   * for a `blend: "add"` program, which fades toward black instead of the
+   * fog color (see FOG). */
+  fog?: boolean | "additive"
   /** Bend the lit normal by a tangent-space normal map (NORMAL_MAP:
    * `uniform sampler2D uNormalMap` scaled by `uniform float
    * uNormalScale`), sampled at the same uv as uMap. The frame comes from
@@ -1064,6 +1317,13 @@ export type LitSourceOptions = {
    * the spatial flush writes it). The vertex stage then requires that layout
    * and something must bind `uBones`; the fragment is unchanged. */
   skinned?: boolean
+  /** Displace positions and normals by the geometry's morph targets
+   * (MORPH_DECLS and MORPH_APPLY, before the skin): the vertex stage then
+   * declares `uMorphs`, `uMorphWeights`, `uMorphWidth` and `uMorphRow`,
+   * which the scene binds from the geometry's packed targets and the
+   * mesh's morph owner (a mesh whose geometry carries none is rejected
+   * at add()); the fragment is unchanged. */
+  morph?: boolean
   /** Place each copy by its instance matrix (INSTANCE_MATRIX under
    * uModel, normals through instanceNormalMatrix): the vertex stage of a
    * material for createInstancedMesh. The class then declares
@@ -1104,7 +1364,7 @@ export type StandardSourceOptions = Omit<LitSourceOptions, "specularMap" | "env"
 }
 
 // The resolved option set: every flag concrete, every slot a string, so
-// the builders below never re-apply a default and `lit`'s class key and
+// the builders below never re-apply a default and a stock material's class key and
 // its program cannot drift apart.
 type LitSource = {
   map: boolean
@@ -1114,7 +1374,7 @@ type LitSource = {
   receiveShadow: boolean
   cull: CullMode
   alphaTest: boolean
-  fog: boolean
+  fog: boolean | "additive"
   normalMap: boolean
   emissive: boolean
   emissiveMap: boolean
@@ -1125,9 +1385,10 @@ type LitSource = {
   skinned: boolean
   instanced: boolean
   instanceColors: boolean
+  morph: boolean
   prelude: string
   surface: string
-  // The light model: Blinn-Phong (`lit`) or GGX metalness/roughness
+  // The light model: Blinn-Phong (`phong`) or GGX metalness/roughness
   // (`standard`, which also samples the environment unconditionally).
   brdf: "blinn" | "ggx"
   metalnessMap: boolean
@@ -1143,7 +1404,7 @@ function resolveLit(o: LitSourceOptions): LitSource {
     receiveShadow: o.receiveShadow !== false,
     cull: o.cull ?? "back",
     alphaTest: o.alphaTest === true,
-    fog: o.fog !== false,
+    fog: o.fog ?? true,
     normalMap: o.normalMap === true,
     emissive: o.emissive === true || o.emissiveMap === true,
     emissiveMap: o.emissiveMap === true,
@@ -1154,6 +1415,7 @@ function resolveLit(o: LitSourceOptions): LitSource {
     skinned: o.skinned === true,
     instanced: o.instanced === true || o.instanceColors === true,
     instanceColors: o.instanceColors === true,
+    morph: o.morph === true,
     prelude: o.prelude ?? "",
     surface: o.surface ?? "",
     brdf: "blinn",
@@ -1221,20 +1483,20 @@ function litBase(c: LitSource, flip: boolean): string {
 }
 
 /**
- * The vertex stage `lit` pairs with a given option set: LIT_VERTEX, or
+ * The vertex stage the stock lit materials pair with a given option set: LIT_VERTEX, or
  * LIT_VERTEX_COLORED when the fragment reads vColor. The shadow source
  * takes this same stage, which is what lets a surface function read the
  * same varyings in both passes.
  */
 export function litVertex(o: LitSourceOptions = {}): string {
   let c = resolveLit(o)
-  return litVertexSource(c.vertexColors, c.lightMap, c.skinned, c.instanced, c.instanceColors)
+  return litVertexSource(c.vertexColors, c.lightMap, c.skinned, c.instanced, c.instanceColors, c.morph)
 }
 
 /**
- * The `lit` fragment source for an option set - the exact program `lit`
+ * The `phong` fragment source for an option set - the exact program `phong`
  * itself builds, composed from the constants above. Pair it with
- * litVertex(o) in a shaderMaterialClass to get a lit material with your
+ * litVertex(o) in a shaderMaterialClass to get a Blinn-Phong material with your
  * own GLSL in it, and pass litShadowFragment(o) alongside when it can
  * discard.
  *
@@ -1246,7 +1508,7 @@ export function litVertex(o: LitSourceOptions = {}): string {
  * Everything else - the lights, the hemisphere, the camera position, the
  * shadow set, the fog - is written by the scene.
  */
-export function litFragment(o: LitSourceOptions = {}): string {
+export function phongFragment(o: LitSourceOptions = {}): string {
   return lightingFragment(resolveLit(o))
 }
 
@@ -1257,7 +1519,7 @@ export function litFragment(o: LitSourceOptions = {}): string {
  * metalness/roughness model (PBR) instead of Blinn-Phong, and the
  * scene's ENVIRONMENT sampled unconditionally as the split sum
  * (envRadiance times envBrdf). Pair it with litVertex(o), and with
- * litShadowFragment(o) when it can discard, exactly as litFragment.
+ * litShadowFragment(o) when it can discard, exactly as phongFragment.
  *
  * Per-entry uniforms: `uColor` (premultiplied vec4), `uMetalness`,
  * `uRoughness`, `uMetalnessMap` (blue channel) and `uRoughnessMap`
@@ -1298,10 +1560,12 @@ function lightingFragment(c: LitSource): string {
     ${c.mapTransform ? "uniform vec4 uMapTransform;" : ""}
     ${c.normalMap ? NORMAL_MAP : ""}
     ${sceneSource({ receiveShadow: c.receiveShadow, env: c.env, fog: c.fog })}
+    ${LOD_FADE}
     ${c.prelude}
     ${c.surface}
 
     void main() {
+      lodFade();
       ${litBase(c, c.cull !== "back")}
       ${c.normalMap ? "n = perturbNormal(n, vWorldPos, uv);" : ""}
       Surface s = surfaceOf(base, n);
@@ -1325,7 +1589,7 @@ function lightingFragment(c: LitSource): string {
 /**
  * The depth-pass source that makes a discarding lit material cast what it
  * actually draws: the same base, cutout and surface function as
- * litFragment(o), and nothing after them (no lighting, no fog - a shadow
+ * phongFragment(o), and nothing after them (no lighting, no fog - a shadow
  * has neither). Undefined when the option set cannot discard (no
  * alphaTest, no surface), which means the scene's default depth material
  * is already right and the material should carry no `shadow` of its own.
@@ -1383,7 +1647,7 @@ export const UNLIT_VERTEX = glsl`
 
 /**
  * The option set the unlit builders take: LitSourceOptions minus
- * everything lighting decides (no vertexColors, triplanar, receiveShadow)
+ * everything lighting decides (no triplanar, receiveShadow)
  * and minus cull (the unlit fragment has no facing-dependent code - cull
  * is pure pipeline state, passed to shaderMaterialClass directly). The
  * slots follow the lit contract; the varyings here are vUv and vWorldPos
@@ -1392,13 +1656,19 @@ export const UNLIT_VERTEX = glsl`
 export type UnlitSourceOptions = {
   /** The fragment samples a `uniform sampler2D uMap`, tinted by uColor. */
   map?: boolean
+  /** Multiply the base by the "colored" layout's per-vertex aColor (see
+   * the lit option): unlitVertex(o) forwards it as vColor, times iColor
+   * under instanceColors. */
+  vertexColors?: boolean
   /** Write the base alpha through and blend; opaque (the default) writes
    * alpha 1. */
   transparent?: boolean
   /** Declare `uniform float uAlphaTest` and discard below it. */
   alphaTest?: boolean
-  /** Compose the scene's fog over the result (default true). */
-  fog?: boolean
+  /** Compose the scene's fog over the result (default true); "additive"
+   * for a `blend: "add"` program, which fades toward black instead of the
+   * fog color (see FOG). */
+  fog?: boolean | "additive"
   /** Declare `uniform vec4 uMapTransform` ([repeatU, repeatV, offsetU,
    * offsetV]) and sample the map at `vUv * repeat + offset` (see the lit
    * option of the same name). Needs `map`. */
@@ -1406,6 +1676,9 @@ export type UnlitSourceOptions = {
   /** Skin positions by the "skinned" layout against uBones (see the lit
    * option); unlitVertex(o) reads it, the fragment is unchanged. */
   skinned?: boolean
+  /** Displace positions by the geometry's morph targets (see the lit
+   * option); unlitVertex(o) reads it, the fragment is unchanged. */
+  morph?: boolean
   /** Place each copy by its instance matrix (see the lit option);
    * unlitVertex(o) reads it, the fragment is unchanged. */
   instanced?: boolean
@@ -1423,13 +1696,15 @@ export type UnlitSourceOptions = {
 
 type UnlitSource = {
   map: boolean
+  vertexColors: boolean
   transparent: boolean
   alphaTest: boolean
-  fog: boolean
+  fog: boolean | "additive"
   mapTransform: boolean
   skinned: boolean
   instanced: boolean
   instanceColors: boolean
+  morph: boolean
   prelude: string
   surface: string
 }
@@ -1437,13 +1712,15 @@ type UnlitSource = {
 function resolveUnlit(o: UnlitSourceOptions): UnlitSource {
   return {
     map: o.map === true,
+    vertexColors: o.vertexColors === true,
     transparent: o.transparent === true,
     alphaTest: o.alphaTest === true,
-    fog: o.fog !== false,
+    fog: o.fog ?? true,
     mapTransform: o.mapTransform === true && o.map === true,
     skinned: o.skinned === true,
     instanced: o.instanced === true || o.instanceColors === true,
     instanceColors: o.instanceColors === true,
+    morph: o.morph === true,
     prelude: o.prelude ?? "",
     surface: o.surface ?? "",
   }
@@ -1451,42 +1728,48 @@ function resolveUnlit(o: UnlitSourceOptions): UnlitSource {
 
 /**
  * The vertex stage `unlit` pairs with an option set: UNLIT_VERTEX, or its
+ * colored form (aColor forwarded as vColor) when `vertexColors`, its
  * skinned form (the skin matrix applied before uModel) when `skinned`,
  * its instanced form (the instance matrix under uModel, iColor forwarded
- * as vColor under `instanceColors`) when `instanced`.
+ * as vColor under `instanceColors`) when `instanced`. vColor carries the
+ * vertex color, the instance color, or their product, as in lit.
  */
 export function unlitVertex(o: UnlitSourceOptions = {}): string {
   let c = resolveUnlit(o)
-  if (!c.skinned && !c.instanced) return UNLIT_VERTEX
+  if (!c.vertexColors && !c.skinned && !c.instanced && !c.morph) return UNLIT_VERTEX
+  let color = c.vertexColors && c.instanceColors ? "aColor * iColor" : c.vertexColors ? "aColor" : c.instanceColors ? "iColor" : ""
   return glsl`
   in vec3 aPos;
   in vec2 aUV;
+  ${c.vertexColors ? "in vec4 aColor;" : ""}
+  ${c.morph ? MORPH_DECLS : ""}
   ${c.skinned ? SKIN_DECLS : ""}
   ${c.instanced ? INSTANCE_MATRIX : ""}
   ${c.instanceColors ? "in vec4 iColor;" : ""}
   out vec2 vUv;
   out vec3 vWorldPos;
-  ${c.instanceColors ? "out vec4 vColor;" : ""}
+  ${color ? "out vec4 vColor;" : ""}
   uniform mat4 uModel;
   uniform mat4 uViewProj;
 
   void main() {
+    ${c.morph ? MORPH_APPLY_POSITION : ""}
     ${c.skinned ? SKIN_MATRIX : ""}
-    vec4 world = ${instancedPosition(c.skinned, c.instanced)};
+    vec4 world = ${instancedPosition(c.skinned, c.instanced, c.morph)};
     vWorldPos = world.xyz;
     gl_Position = uViewProj * world;
     vUv = aUV;
-    ${c.instanceColors ? "vColor = iColor;" : ""}
+    ${color ? `vColor = ${color};` : ""}
   }
 `
 }
 
 /** The unlit base sample: uColor times the (possibly transformed) map,
- * times the instance color when the material carries one. */
+ * times the vertex and instance colors when the material carries them. */
 function unlitBase(c: UnlitSource): string {
   let uv = c.mapTransform ? "vUv * uMapTransform.xy + uMapTransform.zw" : "vUv"
   let base = c.map ? `vec4 base = texture(uMap, ${uv}) * uColor;` : "vec4 base = uColor;"
-  return c.instanceColors ? base + "\n      base *= vColor;" : base
+  return c.vertexColors || c.instanceColors ? base + "\n      base *= vColor;" : base
 }
 
 /**
@@ -1509,15 +1792,17 @@ export function unlitFragment(o: UnlitSourceOptions = {}): string {
   return glsl`
     ${c.map ? "in vec2 vUv;" : ""}
     in vec3 vWorldPos;
-    ${c.instanceColors ? "in vec4 vColor;" : ""}
+    ${c.vertexColors || c.instanceColors ? "in vec4 vColor;" : ""}
     ${c.map ? "uniform sampler2D uMap;" : ""}
     uniform vec4 uColor;
     ${c.alphaTest ? "uniform float uAlphaTest;" : ""}
     ${c.mapTransform ? "uniform vec4 uMapTransform;" : ""}
     ${sceneSource({ lights: false, fog: c.fog })}
+    ${LOD_FADE}
     ${c.prelude}
     ${c.surface}
     void main() {
+      lodFade();
       ${unlitBase(c)}
       ${c.alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
       ${c.surface ? "Surface s = surfaceOf(base, vec3(0.0));\n      surface(s);\n      base = s.base;" : ""}
@@ -1537,7 +1822,7 @@ export function unlitShadowFragment(o: UnlitSourceOptions = {}): string | undefi
   if (!c.alphaTest && !c.surface) return undefined
   return glsl`
     ${c.map ? "in vec2 vUv;" : ""}
-    ${c.instanceColors ? "in vec4 vColor;" : ""}
+    ${c.vertexColors || c.instanceColors ? "in vec4 vColor;" : ""}
     uniform vec4 uColor;
     ${c.map ? "uniform sampler2D uMap;" : ""}
     ${c.alphaTest ? "uniform float uAlphaTest;" : ""}