@solidrt/3d 0.0.70 → 0.0.72

package/src/geometry.ts

@@ -40,7 +40,8 @@
 // array math (tests/geometry.test.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
-import type { Topology, VertexAttribute, VertexFormat } from "@solidrt/core/gpu"
+import { attributeAccess as coreAccess, checkLayout as coreCheck, isFloatFormat, isFloatLayout as coreIsFloat, layoutBytes, layoutKey as coreKey, layoutSlot as coreSlot, layoutStride as coreStride, layoutView, VERTEX_FORMATS } from "@solidrt/core/gpu"
+import type { AttributeAccess, Topology, VertexAttribute, VertexFormat } from "@solidrt/core/gpu"
 import { premultipliedColor } from "./color.ts"
 import { add, compose, cross, mat4, normalize, normalMatrix, sub, updateRotation, updateScale } from "./math.ts"
 import type { Quat, TransformUpdate, Vec2, Vec3 } from "./math.ts"
@@ -78,144 +79,15 @@ export const VERTEX_LAYOUTS: Record<"base" | "colored" | "skinned", VertexAttrib
  * format before packing). */
 export const BASE_FLOATS = 8
 
-/** The shader `in` family a vertex format feeds (WebGPU's rule: the
- * format decides): "float" for the float and normalized formats (`in
- * vec*`), "uint" for uint* (`in uvec*`), "sint" for sint* (`in ivec*`). */
-export type FormatKind = "float" | "uint" | "sint"
-
-/** One vertex format's codec: its size, its component count, its kind,
- * and the read and write of component `k` of an attribute at byte `at`
- * of a DataView, in the value the shader sees (a normalized integer
- * decodes to 0..1 / -1..1, an unnormalized one to its exact value).
- * Every format is a multiple of 4 bytes (WebGPU's alignment rule), which
- * is what keeps every offset and stride 4-aligned with no padding
- * arithmetic anywhere. */
-export type FormatCodec = {
-  bytes: number
-  components: number
-  kind: FormatKind
-  get(dv: DataView, at: number, k: number): number
-  set(dv: DataView, at: number, k: number, v: number): void
-}
-
-// The integer component kinds behind the packed formats: width, the
-// value that maps to 1 (GL ES 3.0's normalization rule, -max mapping to
-// -1 and the one value below it clamped there), and the raw accessors.
-type IntKind = { bytes: number; max: number; get(dv: DataView, at: number): number; set(dv: DataView, at: number, v: number): void }
-const U8: IntKind = { bytes: 1, max: 255, get: (dv, at) => dv.getUint8(at), set: (dv, at, v) => dv.setUint8(at, v) }
-const S8: IntKind = { bytes: 1, max: 127, get: (dv, at) => dv.getInt8(at), set: (dv, at, v) => dv.setInt8(at, v) }
-const U16: IntKind = { bytes: 2, max: 65535, get: (dv, at) => dv.getUint16(at, true), set: (dv, at, v) => dv.setUint16(at, v, true) }
-const S16: IntKind = { bytes: 2, max: 32767, get: (dv, at) => dv.getInt16(at, true), set: (dv, at, v) => dv.setInt16(at, v, true) }
-const U32: IntKind = { bytes: 4, max: 4294967295, get: (dv, at) => dv.getUint32(at, true), set: (dv, at, v) => dv.setUint32(at, v, true) }
-const S32: IntKind = { bytes: 4, max: 2147483647, get: (dv, at) => dv.getInt32(at, true), set: (dv, at, v) => dv.setInt32(at, v, true) }
-
-function clamp(v: number, lo: number, hi: number): number {
-  return v < lo ? lo : v > hi ? hi : v
-}
-
-function floatCodec(components: number, bytes: number, get: (dv: DataView, at: number) => number, set: (dv: DataView, at: number, v: number) => void): FormatCodec {
-  return {
-    bytes: components * bytes,
-    components,
-    kind: "float",
-    get: (dv, at, k) => get(dv, at + k * bytes),
-    set: (dv, at, k, v) => set(dv, at + k * bytes, v),
-  }
-}
-
-function unormCodec(components: number, int: IntKind): FormatCodec {
-  return {
-    bytes: components * int.bytes,
-    components,
-    kind: "float",
-    get: (dv, at, k) => int.get(dv, at + k * int.bytes) / int.max,
-    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, 0, 1) * int.max)),
-  }
-}
-
-function snormCodec(components: number, int: IntKind): FormatCodec {
-  return {
-    bytes: components * int.bytes,
-    components,
-    kind: "float",
-    get: (dv, at, k) => Math.max(int.get(dv, at + k * int.bytes) / int.max, -1),
-    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, -1, 1) * int.max)),
-  }
-}
-
-function uintCodec(components: number, int: IntKind): FormatCodec {
-  return {
-    bytes: components * int.bytes,
-    components,
-    kind: "uint",
-    get: (dv, at, k) => int.get(dv, at + k * int.bytes),
-    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, 0, int.max))),
-  }
-}
-
-function sintCodec(components: number, int: IntKind): FormatCodec {
-  return {
-    bytes: components * int.bytes,
-    components,
-    kind: "sint",
-    get: (dv, at, k) => int.get(dv, at + k * int.bytes),
-    set: (dv, at, k, v) => int.set(dv, at + k * int.bytes, Math.round(clamp(v, -int.max - 1, int.max))),
-  }
-}
-
-let getF32 = (dv: DataView, at: number) => dv.getFloat32(at, true)
-let setF32 = (dv: DataView, at: number, v: number) => dv.setFloat32(at, v, true)
-let getF16 = (dv: DataView, at: number) => dv.getFloat16(at, true)
-let setF16 = (dv: DataView, at: number, v: number) => dv.setFloat16(at, v, true)
-
-/** The vertex vocabulary: one codec per format (the engine's table in
- * the same spelling), so it is also the list a declared format must be
- * one of. A format feeds the shader `in` of its kind and component
- * count (`formatFeeds`). */
-export const VERTEX_FORMATS: Record<VertexFormat, FormatCodec> = {
-  float32: floatCodec(1, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
-  float32x2: floatCodec(2, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
-  float32x3: floatCodec(3, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
-  float32x4: floatCodec(4, Float32Array.BYTES_PER_ELEMENT, getF32, setF32),
-  float16x2: floatCodec(2, Float16Array.BYTES_PER_ELEMENT, getF16, setF16),
-  float16x4: floatCodec(4, Float16Array.BYTES_PER_ELEMENT, getF16, setF16),
-  unorm8x4: unormCodec(4, U8),
-  snorm8x4: snormCodec(4, S8),
-  unorm16x2: unormCodec(2, U16),
-  unorm16x4: unormCodec(4, U16),
-  snorm16x2: snormCodec(2, S16),
-  snorm16x4: snormCodec(4, S16),
-  uint8x4: uintCodec(4, U8),
-  uint16x2: uintCodec(2, U16),
-  uint16x4: uintCodec(4, U16),
-  uint32: uintCodec(1, U32),
-  uint32x2: uintCodec(2, U32),
-  uint32x3: uintCodec(3, U32),
-  uint32x4: uintCodec(4, U32),
-  sint8x4: sintCodec(4, S8),
-  sint16x2: sintCodec(2, S16),
-  sint16x4: sintCodec(4, S16),
-  sint32: sintCodec(1, S32),
-  sint32x2: sintCodec(2, S32),
-  sint32x3: sintCodec(3, S32),
-  sint32x4: sintCodec(4, S32),
-}
-
-/** Whether a layout declaring `declared` may feed a program input the
- * engine reflects as `reflected` (float32xN for `vec*`, uint32xN for
- * `uvec*`, sint32xN for `ivec*`): same component count and same kind,
- * the engine's own pipeline rule. */
-export function formatFeeds(declared: VertexFormat, reflected: VertexFormat): boolean {
-  let d = VERTEX_FORMATS[declared]
-  let r = VERTEX_FORMATS[reflected]
-  return d.components === r.components && d.kind === r.kind
-}
-
-/** Whether a format is one of the float32 family: what a Float32Array
- * holds directly, and what the generators write. */
-export function isFloatFormat(format: VertexFormat): boolean {
-  return format.startsWith("float32")
-}
+// The vertex vocabulary - the format codecs, the stride and key of an
+// attribute list, the record accessors - is core's (`@solidrt/core/gpu`,
+// vertex.ts), shared with the 2d package's material style streams;
+// re-exported here so the package's own modules and callers keep one
+// import for layouts. What stays here is the PRESET side: the named
+// layouts and the functions taking a VertexLayout (a preset name or a
+// list).
+export { formatFeeds, isFloatFormat, VERTEX_FORMATS } from "@solidrt/core/gpu"
+export type { AttributeAccess, FormatCodec, FormatKind } from "@solidrt/core/gpu"
 
 /** The attribute list of a layout (a preset name resolves to its list). */
 export function layoutAttributes(layout?: VertexLayout): VertexAttribute[] {
@@ -227,64 +99,48 @@ export function layoutAttributes(layout?: VertexLayout): VertexAttribute[] {
 
 /** Bytes per vertex of a layout - its interleave stride. */
 export function layoutStride(layout?: VertexLayout): number {
-  let stride = 0
-  for (let attr of layoutAttributes(layout)) stride += VERTEX_FORMATS[attr.format].bytes
-  return stride
+  return coreStride(layoutAttributes(layout))
 }
 
 /** A layout's identity as a string (name:format per attribute, in order):
  * two layouts with equal keys interleave identically. */
 export function layoutKey(layout?: VertexLayout): string {
-  return layoutAttributes(layout)
-    .map(a => a.name + ":" + a.format)
-    .join(",")
+  return coreKey(layoutAttributes(layout))
 }
 
 /** Where an attribute sits in the interleave: its byte offset, format
  * and component count. Null when the layout does not carry that name. */
 export function layoutSlot(layout: VertexLayout | undefined, name: string): { offset: number; format: VertexFormat; components: number } | null {
-  let offset = 0
-  for (let attr of layoutAttributes(layout)) {
-    let codec = VERTEX_FORMATS[attr.format]
-    if (attr.name === name) return { offset, format: attr.format, components: codec.components }
-    offset += codec.bytes
-  }
-  return null
+  return coreSlot(layoutAttributes(layout), name)
 }
 
 /** Whether every attribute of a layout is float32-family: such a buffer
  * is a Float32Array of `layoutStride / 4` floats per vertex, the
  * generators' write form. */
 export function isFloatLayout(layout?: VertexLayout): boolean {
-  return layoutAttributes(layout).every(a => isFloatFormat(a.format))
+  return coreIsFloat(layoutAttributes(layout))
 }
 
-/** The check every layout must pass: aPos float32x3 first and no
- * duplicate names. */
+/** The check every layout must pass: aPos float32x3 first, known
+ * formats and no duplicate names. */
 function checkLayout(layout: VertexAttribute[], where: string): void {
   let first = layout[0]
   if (first === undefined || first.name !== "aPos" || first.format !== "float32x3") {
     throw new Error(where + ": a layout must start with aPos float32x3")
   }
-  let seen = new Set<string>()
-  for (let attr of layout) {
-    if (seen.has(attr.name)) throw new Error(where + ": duplicate attribute '" + attr.name + "'")
-    seen.add(attr.name)
-  }
+  coreCheck(layout, where)
 }
 
 /** The bytes of a vertex buffer, whatever view holds them. */
 export function vertexBytes(vertices: ArrayBufferView): Uint8Array {
-  return new Uint8Array(vertices.buffer, vertices.byteOffset, vertices.byteLength)
+  return layoutBytes(vertices)
 }
 
 /** The view a vertex buffer of `layout` is handed out as: a Float32Array
  * over an all-float layout (the generators' form, indexable as floats),
  * a Uint8Array over a layout with a packed channel. */
 export function vertexView(layout: VertexLayout | undefined, buffer: ArrayBuffer, byteOffset = 0, byteLength = buffer.byteLength - byteOffset): ArrayBufferView {
-  return isFloatLayout(layout)
-    ? new Float32Array(buffer, byteOffset, byteLength / Float32Array.BYTES_PER_ELEMENT)
-    : new Uint8Array(buffer, byteOffset, byteLength)
+  return layoutView(layoutAttributes(layout), buffer, byteOffset, byteLength)
 }
 
 /** Vertices in a buffer of `layout`. Throws naming `where` when the byte
@@ -302,32 +158,11 @@ export function vertexCount(vertices: ArrayBufferView, layout: VertexLayout | un
   return vertices.byteLength / stride
 }
 
-/** A view on one attribute of a vertex buffer: component `k` of vertex
- * `i`, read and written as the float the shader sees, through the
- * format's codec. The one way anything touches vertex data, so no
- * caller knows an offset, a stride or a format. */
-export type AttributeAccess = {
-  format: VertexFormat
-  components: number
-  get(i: number, k: number): number
-  set(i: number, k: number, v: number): void
-}
-
 /** The accessor for `name` over a bare vertex buffer of `layout`; null
- * when the layout lacks the name. */
+ * when the layout lacks the name (core's attributeAccess over the
+ * resolved list). */
 export function attributeAccess(vertices: ArrayBufferView, layout: VertexLayout | undefined, name: string): AttributeAccess | null {
-  let slot = layoutSlot(layout, name)
-  if (slot === null) return null
-  let stride = layoutStride(layout)
-  let codec = VERTEX_FORMATS[slot.format]
-  let offset = slot.offset
-  let dv = new DataView(vertices.buffer, vertices.byteOffset, vertices.byteLength)
-  return {
-    format: slot.format,
-    components: codec.components,
-    get: (i, k) => codec.get(dv, i * stride + offset, k),
-    set: (i, k, v) => codec.set(dv, i * stride + offset, k, v),
-  }
+  return coreAccess(vertices, layoutAttributes(layout), name)
 }
 
 /** One extra vertex buffer of a geometry (see `Geometry.streams`): its

package/src/glsl.ts

@@ -1739,6 +1739,12 @@ export type UnlitSourceOptions = {
   /** Multiply the base by the per-instance `iColor` (implies `instanced`;
    * see the lit option): the one per-copy value an unlit fleet wants. */
   instanceColors?: boolean
+  /** The sprite material's radial shape: declare `uniform float
+   * uFalloff` and multiply the base (color and alpha, the premultiplied
+   * rule) by `(1 - 2 * |vUv - 0.5|)^uFalloff` clamped over the quad's
+   * inscribed disc, after the cutout and before the surface slot. Reads
+   * vUv, so the fragment declares it with or without a map. */
+  radial?: boolean
   /** GLSL spliced at file scope, before main. */
   prelude?: string
   /** GLSL declaring `void surface(inout Surface s)`, called with the base
@@ -1759,6 +1765,7 @@ type UnlitSource = {
   instanced: boolean
   instanceColors: boolean
   morph: boolean
+  radial: boolean
   prelude: string
   surface: string
 }
@@ -1775,6 +1782,7 @@ function resolveUnlit(o: UnlitSourceOptions): UnlitSource {
     instanced: o.instanced === true || o.instanceColors === true,
     instanceColors: o.instanceColors === true,
     morph: o.morph === true,
+    radial: o.radial === true,
     prelude: o.prelude ?? "",
     surface: o.surface ?? "",
   }
@@ -1837,20 +1845,21 @@ function unlitBase(c: UnlitSource): string {
  * does - vWorldPos is read whether or not the program fogs).
  *
  * Per-entry uniforms on instance(): `uColor` (linear light, premultiplied
- * vec4), plus `uMap`/`uAlphaTest` for the options that declare them, plus
- * whatever `prelude` declares.
+ * vec4), plus `uMap`/`uAlphaTest`/`uFalloff` for the options that declare
+ * them, plus whatever `prelude` declares.
  */
 export function unlitFragment(o: UnlitSourceOptions = {}): string {
   let c = resolveUnlit(o)
   let alpha = c.transparent ? "base.a" : "1.0"
   return glsl`
-    ${c.map ? "in vec2 vUv;" : ""}
+    ${c.map || c.radial ? "in vec2 vUv;" : ""}
     in vec3 vWorldPos;
     ${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;" : ""}
+    ${c.radial ? "uniform float uFalloff;" : ""}
     ${sceneSource({ lights: false, fog: c.fog })}
     ${LOD_FADE}
     ${c.prelude}
@@ -1859,6 +1868,7 @@ export function unlitFragment(o: UnlitSourceOptions = {}): string {
       lodFade();
       ${unlitBase(c)}
       ${c.alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
+      ${c.radial ? "base *= pow(clamp(1.0 - 2.0 * length(vUv - 0.5), 0.0, 1.0), uFalloff);" : ""}
       ${c.surface ? "Surface s = surfaceOf(base, vec3(0.0));\n      surface(s);\n      base = s.base;" : ""}
       fragColor = sceneOutput(base.rgb, ${alpha}, vWorldPos);
     }

package/src/index.ts

@@ -5,7 +5,7 @@
 // without Solid components) and the component face (Scene/Mesh/Group/
 // PerspectiveCamera) on top. See AGENTS.md for the model and the traps.
 
-export { add, createGroup, destroy, getMorphNames, getMorphWeights, getRotation, getTransform, lookAt, remove, setMorphWeights, setTransform, setTransition, setVisible, worldPosition } from "./node.ts"
+export { add, createGroup, destroy, getMorphNames, getMorphWeights, getRotation, getTransform, lookAt, remove, setMorphWeights, setTimeScale, setTransform, setTransition, setVisible, timeRate, worldPosition } from "./node.ts"
 export type { HoverHandlers, LodConfig, MorphWeights, NodePointerEvent, NodeTapEvent, NodeWheelEvent, SceneEventBase, SceneNode, ScenePointerEvent, ScenePointerListener, SceneTapEvent, SceneWheelEvent, TransformUpdate, TransitionEndEvent } from "./node.ts"
 export { addInstance, createInstancedMesh, createMesh, createRecordMesh, createSprite, disposeInstances, setCastShadow, setCulling, setDrawRange, setEnvironment, setGeometry, setInstanceStyle, setLayers, setMaterial, setMeshParams, setRecordCount, setRecords, setRenderOrder, instanceAttribute, records, updateRecords, INSTANCE_FLOATS } from "./mesh.ts"
 export type { InstancedMesh as InstancedMeshNode, InstancedMeshOptions, InstanceNode, InstanceOrderOptions, InstanceSlots, InstanceStream, Mesh as MeshNode, MeshInstances, RecordMesh as RecordMeshNode, RecordMeshOptions, UpdateRecordsOptions } from "./mesh.ts"

package/src/material.ts

@@ -257,6 +257,19 @@ export type UnlitOptions = {
    * MultiMesh instance color. A cutout's shadow multiplies by the same
    * color, so alpha below `alphaTest` cuts the shadow with the pixels. */
   instanceColors?: boolean
+  /** GLSL at file scope for `surface`: uniforms (each an ordinary
+   * per-entry param, `params` on the mesh or setMeshParams) and helper
+   * functions. See the tier-2 look in AGENTS.md "Custom looks". */
+  prelude?: string
+  /** GLSL declaring `void surface(inout Surface s)`, called once the
+   * program has resolved the base (the color, the map, the vertex and
+   * instance colors, the cutout) and before the scene tail: rewrite
+   * `s.base` or `discard`. The unlit program shades nothing, so `base`
+   * is the only field read back and `s.normal` is zero. Runs in the
+   * shadow twin too (attached whenever a surface is given), so what it
+   * discards casts no shadow, the twin seeing a `prelude` uniform at its
+   * zero value. One program per distinct source, like every option. */
+  surface?: string
 }
 
 // The fog an unlit program composes: none when opted out, the additive
@@ -306,13 +319,15 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let instanceColors = opts.instanceColors === true
   let instanced = opts.instanced === true || instanceColors
   let vertexColors = opts.vertexColors === true
+  let prelude = opts.prelude ?? ""
+  let surface = opts.surface ?? ""
   if (mapTransform && !map) throw new Error("unlit: mapTransform without a map to transform")
-  let key = [map, vertexColors, transparent, blend, cull, alphaTest, fog, mapTransform, skinned, instanced, instanceColors, morph].join("|")
+  let key = [map, vertexColors, transparent, blend, cull, alphaTest, fog, mapTransform, skinned, instanced, instanceColors, morph, prelude, surface].join("|")
   let cls = unlitClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: unlitVertex({ vertexColors, skinned, instanced, instanceColors, morph }),
-      fragment: unlitFragment({ map, vertexColors, alphaTest, transparent, fog, mapTransform, instanceColors }),
+      fragment: unlitFragment({ map, vertexColors, alphaTest, transparent, fog, mapTransform, instanceColors, prelude, surface }),
       shadowVertex: instanced ? shadowDepthVertex(skinned, true, morph) : undefined,
       instanceBuffers: stockInstanceBuffers(instanced, instanceColors),
       instanceStyle: instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
@@ -327,12 +342,21 @@ export function unlit(opts: UnlitOptions = {}): Material {
   let params: ShaderParams = { uColor }
   if (alphaTest) params.uAlphaTest = opts.alphaTest!
   if (mapTransform) params.uMapTransform = mapTransformParam(opts.mapTransform!)
+  // A mapped cutout casts its cutout and a surface function casts its
+  // discards (lit's rule); a color-only alphaTest is all or nothing and
+  // keeps the plain depth variant.
   return cls.instance({
     params,
     textures: map ? { uMap: opts.map! } : undefined,
     shadow:
-      alphaTest && map
-        ? unlitShadowMaterial(shadowCull(cull), vertexColors, skinned, instanced, instanceColors, morph, uColor, opts.alphaTest!, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+      (alphaTest && map) || surface !== ""
+        ? unlitShadowMaterial(
+            { cull: shadowCull(cull), map, vertexColors, alphaTest: alphaTest && map, skinned, instanced, instanceColors, morph, mapTransform, prelude, surface },
+            uColor,
+            opts.alphaTest,
+            opts.map,
+            mapTransform ? (params.uMapTransform as number[]) : undefined,
+          )
         : undefined,
   })
 }
@@ -892,42 +916,59 @@ function shadowVariant(cull: CullMode, skinned: boolean, morphed: boolean): Mate
 
 let unlitShadowClasses = new Map<string, ShaderMaterialClass>()
 
+/** The flags an unlit shadow twin is keyed and built on: the shadow
+ * cull, the source options the discard depends on, and the vertex
+ * stage's own (skinning, instancing, morphing, so the cutout casts its
+ * pose and placement). */
+type UnlitShadowFlags = {
+  cull: CullMode
+  map: boolean
+  vertexColors: boolean
+  alphaTest: boolean
+  skinned: boolean
+  instanced: boolean
+  instanceColors: boolean
+  morph: boolean
+  mapTransform: boolean
+  prelude: string
+  surface: string
+}
+
 /** The shadow variant of a discarding unlit material: unlitShadowFragment
  * on the same vertex stage (skinned when the material skins, so the
- * cutout casts its pose), litShadowMaterial's unlit twin. unlit()'s
- * only discard is the mapped cutout, so what varies is the shadow cull,
- * skinning and whether the cutout's uv is transformed - one class per
- * combination. An instance per material (its map, color, cutoff,
- * transform). */
-function unlitShadowMaterial(
-  cull: CullMode,
-  vertexColors: boolean,
-  skinned: boolean,
-  instanced: boolean,
-  instanceColors: boolean,
-  morph: boolean,
-  uColor: number[],
-  uAlphaTest: number,
-  uMap: TextureId,
-  uMapTransform?: number[],
-): Material {
-  let key = [cull, uMapTransform !== undefined, vertexColors, skinned, instanced, instanceColors, morph].join("|")
+ * cutout casts its pose), litShadowMaterial's unlit twin. unlit()
+ * discards through the mapped cutout and through a surface function,
+ * so what varies is the shadow cull, the source flags and the sources
+ * themselves - one class per combination. An instance per material (its
+ * map, color, cutoff, transform); a prelude uniform reaches the twin at
+ * its zero value, mesh params going to the main entry only. */
+function unlitShadowMaterial(flags: UnlitShadowFlags, uColor: number[], uAlphaTest: number | undefined, uMap: TextureId | undefined, uMapTransform?: number[]): Material {
+  let key = [flags.cull, flags.map, flags.vertexColors, flags.alphaTest, flags.skinned, flags.instanced, flags.instanceColors, flags.morph, flags.mapTransform, flags.prelude, flags.surface].join("|")
   let cls = unlitShadowClasses.get(key)
   if (cls === undefined) {
-    let fragment = unlitShadowFragment({ map: true, vertexColors, alphaTest: true, mapTransform: uMapTransform !== undefined, instanceColors })
-    if (fragment === undefined) throw new Error("unlitShadowMaterial: the cutout options cannot discard")
+    let fragment = unlitShadowFragment({
+      map: flags.map,
+      vertexColors: flags.vertexColors,
+      alphaTest: flags.alphaTest,
+      mapTransform: flags.mapTransform,
+      instanceColors: flags.instanceColors,
+      prelude: flags.prelude,
+      surface: flags.surface,
+    })
+    if (fragment === undefined) throw new Error("unlitShadowMaterial: the options cannot discard")
     cls = shaderMaterialClass({
-      vertex: unlitVertex({ vertexColors, skinned, instanced, instanceColors, morph }),
+      vertex: unlitVertex({ vertexColors: flags.vertexColors, skinned: flags.skinned, instanced: flags.instanced, instanceColors: flags.instanceColors, morph: flags.morph }),
       fragment,
-      cull,
-      instanceBuffers: stockInstanceBuffers(instanced, instanceColors),
+      cull: flags.cull,
+      instanceBuffers: stockInstanceBuffers(flags.instanced, flags.instanceColors),
       label: "scene-unlit-shadow-" + key,
     })
     unlitShadowClasses.set(key, cls)
   }
-  let params: ShaderParams = { uColor, uAlphaTest }
+  let params: ShaderParams = { uColor }
+  if (flags.alphaTest) params.uAlphaTest = uAlphaTest!
   if (uMapTransform !== undefined) params.uMapTransform = uMapTransform
-  return cls.instance({ params, textures: { uMap } })
+  return cls.instance({ params, textures: flags.map ? { uMap: uMap! } : undefined })
 }
 
 /** A sprite's options: unlit's, minus instancing (the billboard stage
@@ -974,19 +1015,6 @@ export type SpriteOptions = Omit<UnlitOptions, "instanced" | "instanceColors" |
   maxScreenPx?: number
 }
 
-// The radial shape as a tier-2 surface on the unlit fragment: the
-// vertex stages always write vUv, which the fragment declares only with
-// a map, so the mapless prelude declares it itself.
-const RADIAL_PRELUDE = glsl`
-  uniform float uFalloff;
-`
-const RADIAL_SURFACE = glsl`
-  void surface(inout Surface s) {
-    float disc = clamp(1.0 - 2.0 * length(vUv - 0.5), 0.0, 1.0);
-    s.base *= pow(disc, uFalloff);
-  }
-`
-
 // The billboard vertex stages: the unit quad's corners placed along the
 // camera axes at the mesh's world position, with the quad's size read
 // off uModel's column lengths so `scale` sizes the sprite like any mesh,
@@ -1103,18 +1131,14 @@ export function sprite(opts: SpriteOptions = {}): Material {
   let minScreenPx = opts.minScreenPx ?? 0
   let maxScreenPx = opts.maxScreenPx ?? 0
   checkScreenSize("sprite", minScreenPx, maxScreenPx)
-  let key = [map, transparent, blend, fixedY, fog, radial].join("|")
+  let prelude = opts.prelude ?? ""
+  let surface = opts.surface ?? ""
+  let key = [map, transparent, blend, fixedY, fog, radial, prelude, surface].join("|")
   let cls = spriteClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: unlitFragment({
-        map,
-        transparent,
-        fog,
-        prelude: radial ? (map ? "" : "in vec2 vUv;\n") + RADIAL_PRELUDE : undefined,
-        surface: radial ? RADIAL_SURFACE : undefined,
-      }),
+      fragment: unlitFragment({ map, transparent, fog, radial, prelude, surface }),
       transparent,
       blend,
       cull: "none",