@solidrt/3d 0.0.55 → 0.0.57

package/src/material.ts

@@ -33,6 +33,7 @@ import type {
   BlendMode,
   CullMode,
   ProgramId,
+  InstanceAttribute,
   RenderPipelineId,
   ShaderParams,
   TextureBindings,
@@ -42,7 +43,24 @@ import type {
 } from "@solidrt/core/gpu"
 import { layoutAttributes, layoutKey, layoutSlot } from "./geometry.ts"
 import type { VertexLayout } from "./geometry.ts"
-import { BLINN_SPECULAR, FOG, HEMISPHERE, LAMBERT, LIT_VERTEX, LIT_VERTEX_COLORED, MAX_LIGHTS, SHADOW, SHADOW_LOOKUP, SHADOW_SLOTS } from "./glsl.ts"
+import { linearColor } from "./color.ts"
+import {
+  INSTANCE_COLOR_ATTRIBUTES,
+  INSTANCE_MATRIX,
+  INSTANCE_MATRIX_ATTRIBUTES,
+  litFragment,
+  litShadowFragment,
+  litVertex,
+  SKIN_DECLS,
+  SKIN_MATRIX,
+  standardFragment,
+  SURFACE_DEFAULTS,
+  UNLIT_VERTEX,
+  unlitFragment,
+  unlitShadowFragment,
+  unlitVertex,
+  OUTPUT,
+} from "./glsl.ts"
 
 export type Material = {
   /** The pipeline this material draws with for geometry of `layout`
@@ -68,82 +86,62 @@ export type Material = {
    * back-to-front by mesh origin, and re-sorts them when the camera moves. */
   transparent?: boolean
   /** Per-instance attributes, when the material's pipeline declares them
-   * (shaderMaterialClass's `instanceAttributes`). Such a material draws
-   * instanced meshes only - createInstancedMesh supplies the record buffer,
-   * and createMesh meshes are rejected at add(). */
-  instanceAttributes?: VertexAttribute[]
+   * (shaderMaterialClass's `instanceAttributes`; the stock materials'
+   * `instanced`). Such a material draws populated meshes only - an
+   * instanced mesh binds slot 0 to the core-written matrix records and
+   * slot 1 to its app-written style records, a record mesh binds slot 0
+   * to its records - and createMesh meshes are rejected at add(). */
+  instanceAttributes?: InstanceAttribute[]
+  /** The style record (the slot-1 attributes' floats, in order) every
+   * fresh instance of an instanced mesh starts with; absent = zeros.
+   * White for the stock materials' `instanceColors`. */
+  instanceStyle?: ArrayLike<number>
   /** What a shadow view draws this material's meshes with instead of its
    * default depth override: the depth pass culling the side this material
    * culls (Three's shadowSide rule, Godot's shadow pass), so a `cull:
-   * "none"` caster casts from both faces, and for a cutout (lit
+   * "none"` caster casts from both faces, for a cutout (lit
    * alphaTest with a map) the same discard, so a plant casts leaves and
-   * not rectangles. Absent = the default (a back-culling material casts
-   * from its back faces). A shaderMaterial supplies its own through the
-   * instance option of the same name. */
+   * not rectangles, for a skinned material the same skinning, so a
+   * posed caster casts its pose, and for an instanced class with
+   * `shadowVertex` the same instance placement, so a fleet casts where
+   * its records stand. Absent = the default (a back-culling material
+   * casts from its back faces); an instanced material without one is
+   * SKIPPED by shadow views. A shaderMaterial supplies its own through
+   * the instance option of the same name. */
   shadow?: Material
+  /** True when the vertex stage declares `uBones` (read from the source,
+   * like normalMatrix): the program skins by the mesh's palette texture,
+   * so a shadow or override entry for a skinned mesh merges the mesh's
+   * own uBones binding even though this material is not the mesh's. */
+  skinned?: boolean
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
 
-// The unlit vertex stage: model then view-projection, plus the UV
-// varying. uModel is per-entry (the scene writes it when the mesh moves),
-// uViewProj is target-shared (one write per camera move) - the split is
-// what keeps camera motion O(1) instead of O(meshes), and the extra
-// per-vertex mat4 multiply is free on the GPU. aNormal from the shared
-// layout is deliberately not declared - inactive attributes are skipped
-// and only the stride accounts for them. vWorldPos is the fog distance
-// input; a fragment that does not read it (fog: false) leaves the out
-// unmatched, which links fine.
-const UNLIT_VERTEX = glsl`
-  in vec3 aPos;
-  in vec2 aUV;
-  out vec2 vUv;
-  out vec3 vWorldPos;
-  uniform mat4 uModel;
-  uniform mat4 uViewProj;
-
-  void main() {
-    vec4 world = uModel * vec4(aPos, 1.0);
-    vWorldPos = world.xyz;
-    gl_Position = uViewProj * world;
-    vUv = aUV;
-  }
-`
-
-// The unlit fragment (sprites share it): the color, times the map when
-// there is one, with the alphaTest discard when asked for, then the
-// scene's fog (FOG from ./glsl, mixed at the alpha about to be written)
-// unless the material opted out. An opaque
-// class writes alpha 1: the scene target is composited premultiplied, so
-// a leaked texel alpha would punch a hole through an opaque draw.
-function unlitFragment(map: boolean, alphaTest: boolean, transparent: boolean, fog: boolean): string {
-  let alpha = transparent ? "base.a" : "1.0"
-  return glsl`
-    ${map ? "in vec2 vUv;" : ""}
-    ${fog ? "in vec3 vWorldPos;" : ""}
-    ${map ? "uniform sampler2D uMap;" : ""}
-    uniform vec4 uColor;
-    ${alphaTest ? "uniform float uAlphaTest;" : ""}
-    ${fog ? "uniform vec3 uCamPos;" : ""}
-    ${fog ? FOG : ""}
-    void main() {
-      vec4 base = ${map ? "texture(uMap, vUv) * uColor" : "uColor"};
-      ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
-      ${fog ? `base.rgb = fog(base.rgb, ${alpha}, vWorldPos, uCamPos);` : ""}
-      fragColor = vec4(base.rgb, ${alpha});
-    }
-  `
-}
-
 // One shaderMaterialClass per unlit option combination (map x transparent
 // x cull x alphaTest), cached for the app's lifetime like lit's; one
 // pipeline per vertex layout inside each.
 let unlitClasses = new Map<string, ShaderMaterialClass>()
 
+// The uColor a color option compiles to: sRGB decoded to linear light,
+// then premultiplied by its alpha (the target's contract).
+function colorParam(color: readonly number[]): number[] {
+  let a = color.length === 4 ? color[3]! : 1
+  let c = linearColor(color)
+  return [c[0]! * a, c[1]! * a, c[2]! * a, a]
+}
+
 export type UnlitOptions = {
-  /** Straight [r, g, b] or [r, g, b, a], 0..1. Default white. */
+  /** Straight [r, g, b] or [r, g, b, a], 0..1, sRGB - a color picker's
+   * values. The library decodes it to linear light for shading and the
+   * output stage encodes the result back (see the color contract in
+   * AGENTS.md); an unlit surface with no tone mapping shows the value
+   * as given. Default white. */
   color?: [number, number, number] | [number, number, number, number]
-  /** A texture id to sample (tinted by `color` when both are given). */
+  /** A texture id to sample (tinted by `color` when both are given).
+   * Create a color image with `format: "rgba8-srgb"` so it decodes to
+   * linear light like `color`; a plain rgba8 map reads as linear data and
+   * shows washed out. */
   map?: TextureId
   /** Blend over what is behind (color alpha and map alpha both count).
    * Without it an alpha below 1 still draws opaque. See Material.transparent. */
@@ -166,6 +164,58 @@ export type UnlitOptions = {
    * the program - a sky sphere or a far backdrop that must keep its
    * color, an emissive marker. */
   fog?: boolean
+  /** Offset and repeat for the uv every map of this material samples:
+   * `uv * repeat + offset` (defaults `[1, 1]` / `[0, 0]`). ONE transform
+   * per MATERIAL (Godot's uv1_offset/uv1_scale, Unity's Tiling/Offset) -
+   * deliberately not Three's per-texture transform, since a TextureId is
+   * a shared value whose sampling is creation-time state. A cutout's
+   * shadow transforms the same way; lit's lightMap (aUV2) is exempt.
+   * Scrolling surfaces (water, a conveyor) drive it per frame with
+   * `setMeshParams(mesh, { uMapTransform: [ru, rv, ou, ov] })`. Needs a
+   * map; not with triplanar (whose repeat is uTriplanar). */
+  mapTransform?: { offset?: [number, number]; repeat?: [number, number] }
+  /** Skin positions (and lit normals) by the "skinned" layout's aJoints/
+   * aWeights against the `uBones` palette texture - the rigged-model
+   * variant createModel picks for skinned parts. The material then
+   * requires "skinned" geometry, and something must bind `uBones`
+   * (createModel binds each skin's palette texture to its meshes and
+   * the spatial flush writes it from the joints). The shadow variants
+   * (depth and cutout) skin the same way, so a caster casts its pose. */
+  skinned?: boolean
+  /** Draw instanced meshes (createInstancedMesh / `<InstancedMesh>`):
+   * the vertex stage places each copy by its instance matrix under the
+   * mesh's uModel, and the material declares INSTANCE_MATRIX_ATTRIBUTES,
+   * so it draws populated meshes ONLY (a createMesh mesh is rejected at
+   * add()). The shadow variants place the same way, so a fleet casts.
+   * Unity's per-material "Enable GPU Instancing"; Three's built-ins do
+   * it implicitly on an InstancedMesh. */
+  instanced?: boolean
+  /** Multiply the base by a per-instance color (implies `instanced`):
+   * the instance's style record is one premultiplied linear [r, g, b, a]
+   * (INSTANCE_COLOR_ATTRIBUTES), starting white, written with
+   * setInstanceStyle or `<Instance style>`. Three's setColorAt, Godot's
+   * MultiMesh instance color. A cutout's shadow multiplies by the same
+   * color, so alpha below `alphaTest` cuts the shadow with the pixels. */
+  instanceColors?: boolean
+}
+
+// The instance attributes a stock instanced material declares: the
+// matrix always, the color record beside it under instanceColors.
+function stockInstanceAttributes(instanced: boolean, instanceColors: boolean): InstanceAttribute[] | undefined {
+  if (!instanced) return undefined
+  return instanceColors ? [...INSTANCE_MATRIX_ATTRIBUTES, ...INSTANCE_COLOR_ATTRIBUTES] : INSTANCE_MATRIX_ATTRIBUTES
+}
+// A fresh instance's color: white, the multiplicative identity, so an
+// instance never written shows the material's own color (Godot's default;
+// Three's zero-filled instanceColor is the trap avoided here).
+const INSTANCE_COLOR_DEFAULT = [1, 1, 1, 1]
+
+/** The uMapTransform vec4 for a mapTransform option: [repeatU, repeatV,
+ * offsetU, offsetV]. */
+function mapTransformParam(t: { offset?: [number, number]; repeat?: [number, number] }): number[] {
+  let repeat = t.repeat ?? [1, 1]
+  let offset = t.offset ?? [0, 0]
+  return [repeat[0], repeat[1], offset[0], offset[1]]
 }
 
 /**
@@ -174,20 +224,26 @@ export type UnlitOptions = {
  * light list); see the scene-graph research note.
  */
 export function unlit(opts: UnlitOptions = {}): Material {
-  let color = opts.color ?? [1, 1, 1]
-  let a = color.length === 4 ? color[3] : 1
-  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let uColor = colorParam(opts.color ?? [1, 1, 1])
   let map = opts.map !== undefined
   let transparent = opts.transparent === true
   let cull = opts.cull ?? "back"
   let alphaTest = opts.alphaTest !== undefined
   let fog = opts.fog !== false
-  let key = [map, transparent, cull, alphaTest, fog].join("|")
+  let mapTransform = opts.mapTransform !== undefined
+  let skinned = opts.skinned === true
+  let instanceColors = opts.instanceColors === true
+  let instanced = opts.instanced === true || instanceColors
+  if (mapTransform && !map) throw new Error("unlit: mapTransform without a map to transform")
+  let key = [map, transparent, cull, alphaTest, fog, mapTransform, skinned, instanced, instanceColors].join("|")
   let cls = unlitClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
-      vertex: UNLIT_VERTEX,
-      fragment: unlitFragment(map, alphaTest, transparent, fog),
+      vertex: unlitVertex({ skinned, instanced, instanceColors }),
+      fragment: unlitFragment({ map, alphaTest, transparent, fog, mapTransform, instanceColors }),
+      shadowVertex: instanced ? shadowDepthVertex(skinned, true) : undefined,
+      instanceAttributes: stockInstanceAttributes(instanced, instanceColors),
+      instanceStyle: instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
       transparent,
       cull,
       label: "scene-unlit-" + key,
@@ -196,10 +252,14 @@ export function unlit(opts: UnlitOptions = {}): Material {
   }
   let params: ShaderParams = { uColor }
   if (alphaTest) params.uAlphaTest = opts.alphaTest!
+  if (mapTransform) params.uMapTransform = mapTransformParam(opts.mapTransform!)
   return cls.instance({
     params,
     textures: map ? { uMap: opts.map! } : undefined,
-    shadow: alphaTest && map ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
+    shadow:
+      alphaTest && map
+        ? unlitShadowMaterial(shadowCull(cull), skinned, instanced, instanceColors, uColor, opts.alphaTest!, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+        : undefined,
   })
 }
 
@@ -217,6 +277,58 @@ export type LitOptions = UnlitOptions & {
    * each part's size or UVs; the map must be created with
    * `wrap: "repeat"`. */
   triplanar?: number
+  /** A tangent-space normal map (OpenGL-style +Y, as glTF mandates),
+   * sampled at the same uv as `map` and bending the lit normal - track
+   * relief, kart panel lines, without triangles. The tangent frame is
+   * built per fragment from screen-space derivatives (NORMAL_MAP in
+   * `@solidrt/3d/glsl` - Three's untangented path), so ANY UV-mapped
+   * geometry works with no tangent channel; the trade is mild seams on
+   * mirrored UVs. Not with `triplanar` (which samples by world position).
+   * Wants `mipmap: true` at creation like any map seen at distance. */
+  normalMap?: TextureId
+  /** How strongly the normal map bends the surface, default 1 (0 flattens
+   * it). One float, as in Unity (_BumpScale) and Godot (normal_scale) -
+   * not Three's Vector2, whose second component exists to flip
+   * DirectX-style green channels. */
+  normalScale?: number
+  /** Light the surface emits, [r, g, b] 0..1, sRGB like `color` - added
+   * after the lighting terms, unaffected by lights and shadows, fogged
+   * like everything else. Defaults to WHITE when `emissiveMap` is given
+   * (the map is the emission - fixing Three's black-default gotcha, where
+   * an emissiveMap alone shows nothing) and to off otherwise. */
+  emissive?: [number, number, number]
+  /** Scales `emissive` in linear light, default 1: values above 1 for a
+   * glow that tone mapping can bloom (Three's emissiveIntensity, Godot's
+   * emission_energy_multiplier, glTF's KHR_materials_emissive_strength). */
+  emissiveIntensity?: number
+  /** A texture multiplying `emissive` per fragment - lamps, screens,
+   * nitro glow baked into one map. Sampled at the same uv as `map`;
+   * create it with `format: "rgba8-srgb"` like `map`. */
+  emissiveMap?: TextureId
+  /** A texture whose RED channel scales `specular` per fragment (Three's
+   * specularMap) - chrome and rubber on one mesh. With it, `specular`
+   * defaults to 1 (the map is the strength). */
+  specularMap?: TextureId
+  /** Mirror the scene's environment (scene.setEnvironment), 0..1: the
+   * face-on reflection weight, rising to 1 at grazing angles (Schlick) -
+   * 1 is chrome, ~0.05 a glossy dielectric with rim reflections. The
+   * reflection blurs with `shininess` (a wide sheen reflects a blurred
+   * sky, a mirror dot a sharp one; the environment cube needs mipmaps
+   * for the blur) and `specularMap`'s red scales it like `specular`.
+   * Three's Phong `reflectivity` with MixOperation and a fresnel weight
+   * (Three's default MultiplyOperation tints instead; not offered). Off
+   * while the scene has no environment. Undefined declares no
+   * environment sampler at all. */
+  reflectivity?: number
+  /** A baked-light texture (an offline render, an AO+GI bake), sampled by
+   * the geometry's aUV2 channel and ADDED to the light sum like the
+   * hemisphere term - a fully baked scene runs with no lights at all
+   * (Three's lightMap; Unity and Godot bake at scene level, but here the
+   * material picks the program). The geometry must carry aUV2
+   * (withAttribute) or add() throws. */
+  lightMap?: TextureId
+  /** Scales the lightMap, default 1. */
+  lightMapIntensity?: number
   /**
    * Receive the scene's directional shadows (default true, like Godot and
    * Three): each casting light's term is multiplied by its shadow-map
@@ -232,106 +344,54 @@ export type LitOptions = UnlitOptions & {
   receiveShadow?: boolean
 }
 
-// The lit fragment is composed from the same exported pieces an app
-// composes by hand, per flag: map x vertexColors x triplanar x shadow x
-// transparent x cull (a class that shows back faces lights them with the
-// normal flipped, else a double-sided leaf's back is black) x alphaTest
-// (the cutoff itself is a per-entry uniform, one class for every value)
-// x fog (the scene's fog composed last, or left out of the program).
-// An opaque class writes alpha 1 (see unlitFragment). Lights arrive
-// through the scene's shared params (light nodes); the base color, map
-// and highlight are per entry. The
-// shadow set is shared too and indexed like the lights: one atlas sampler,
+// The lit program is built by litFragment in ./glsl - the same builder an
+// app calls to get a lit material with its own GLSL in it, composed from
+// the same exported constants. What varies per flag: map x vertexColors x
+// triplanar x receiveShadow x transparent x cull (a class that shows back
+// faces lights them with the normal flipped, else a double-sided leaf's
+// back is black) x alphaTest (the cutoff itself is a per-entry uniform,
+// one class for every value) x fog (the scene's fog composed last, or
+// left out of the program) x the surface maps (normalMap, emissive /
+// emissiveMap, specularMap, lightMap) x mapTransform. The key's
+// dimensionality costs nothing by itself: classes are created lazily per
+// combination USED, so the program count is the app's distinct material
+// configurations, bounded by its material count, never by this tuple's
+// width. An opaque class writes alpha 1 (see
+// unlitFragment). Lights arrive through the scene's shared params (light
+// nodes); the base color, map and highlight are per entry. The shadow set
+// is shared too and indexed like the lights: one atlas sampler,
 // directional light i's maps (one, or its cascades) as map slots
 // uShadowFirst[i] .. + uShadowCount[i] with a tile rect and a matrix
 // each, and its biases (target-level, bound by the scene); uShadowCount
 // 0 means it does not cast; SHADOW_LOOKUP turns the index into the factor.
 // The option combination that picks a lit class: the class-cache key is
-// its values in this order, and the fragment builder reads the same
-// object, so the two cannot drift apart.
+// its values in this order, and the same object builds the program, so
+// the two cannot drift apart. `lit` fills no slot - an app that does
+// reaches for litFragment directly, and owns the class it builds.
 type LitClass = {
   map: boolean
   vertexColors: boolean
   triplanar: boolean
   transparent: boolean
-  shadow: boolean
+  receiveShadow: boolean
   cull: CullMode
   alphaTest: boolean
   fog: boolean
+  normalMap: boolean
+  emissive: boolean
+  emissiveMap: boolean
+  specularMap: boolean
+  env: boolean
+  lightMap: boolean
+  mapTransform: boolean
+  skinned: boolean
+  instanced: boolean
+  instanceColors: boolean
 }
 
 function litClassKey(c: LitClass): string {
   return Object.values(c).join("|")
 }
-
-function litFragment(c: LitClass): string {
-  let { map, vertexColors, triplanar, shadow, alphaTest, fog } = c
-  let backFaces = c.cull !== "back"
-  let alpha = c.transparent ? "base.a" : "1.0"
-  return glsl`
-    in vec3 vWorldPos;
-    in vec3 vNormal;
-    in vec2 vUv;
-    ${vertexColors ? "in vec4 vColor;" : ""}
-    uniform vec4 uColor;
-    ${map ? "uniform sampler2D uMap;" : ""}
-    uniform float uSpecular;
-    uniform float uShininess;
-    ${triplanar ? "uniform float uTriplanar;" : ""}
-    ${alphaTest ? "uniform float uAlphaTest;" : ""}
-    uniform vec3 uCamPos;
-    uniform vec3 uHemiSky;
-    uniform vec3 uHemiGround;
-    uniform int uLightCount;
-    uniform vec3 uLightDir[${MAX_LIGHTS}];
-    uniform vec3 uLightColor[${MAX_LIGHTS}];
-    ${
-      shadow
-        ? `${SHADOW_SLOTS}
-    ${SHADOW}
-    ${SHADOW_LOOKUP}`
-        : ""
-    }
-    ${HEMISPHERE}
-    ${LAMBERT}
-    ${BLINN_SPECULAR}
-    ${fog ? FOG : ""}
-
-    void main() {
-      vec3 n = normalize(vNormal);
-      ${backFaces ? "if (!gl_FrontFacing) n = -n;" : ""}
-      vec4 base = uColor;
-      ${
-        map
-          ? triplanar
-            ? `vec3 w = pow(abs(n), vec3(4.0));
-      w /= w.x + w.y + w.z;
-      vec3 p = vWorldPos * uTriplanar;
-      base *= texture(uMap, p.yz) * w.x + texture(uMap, p.xz) * w.y + texture(uMap, p.xy) * w.z;`
-            : "base *= texture(uMap, vUv);"
-          : ""
-      }
-      ${vertexColors ? "base *= vColor;" : ""}
-      ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
-      vec3 v = normalize(uCamPos - vWorldPos);
-      vec3 light = hemisphere(n, uHemiSky, uHemiGround);
-      vec3 spec = vec3(0.0);
-      for (int i = 0; i < ${MAX_LIGHTS}; i++) {
-        if (i >= uLightCount) break;
-        vec3 l = uLightDir[i];
-        ${
-          shadow ? "float s = lightShadow(i, vWorldPos, n);" : "float s = 1.0;"
-        }
-        light += uLightColor[i] * lambert(n, l) * s;
-        spec += uLightColor[i] * blinnSpecular(n, v, l, uShininess) * s;
-      }
-      vec3 rgb = base.rgb * light + spec * uSpecular * base.a;
-      ${fog ? `rgb = fog(rgb, ${alpha}, vWorldPos, uCamPos);` : ""}
-      fragColor = vec4(rgb, ${alpha});
-    }
-  `
-}
-
 let litClasses = new Map<string, ShaderMaterialClass>()
 
 /**
@@ -345,62 +405,328 @@ let litClasses = new Map<string, ShaderMaterialClass>()
  * starts at zero: set at least one of the two.
  */
 export function lit(opts: LitOptions = {}): Material {
-  let color = opts.color ?? [1, 1, 1]
-  let a = color.length === 4 ? color[3] : 1
-  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  let uColor = colorParam(opts.color ?? [1, 1, 1])
   let map = opts.map !== undefined
   let triplanar = map && opts.triplanar !== undefined
   let alphaTest = opts.alphaTest !== undefined
   let cull = opts.cull ?? "back"
+  let normalMap = opts.normalMap !== undefined
+  let emissiveMap = opts.emissiveMap !== undefined
+  let emissive = opts.emissive !== undefined || emissiveMap
+  let specularMap = opts.specularMap !== undefined
+  let env = opts.reflectivity !== undefined
+  let lightMap = opts.lightMap !== undefined
+  let mapTransform = opts.mapTransform !== undefined
+  if (env && !(Number.isFinite(opts.reflectivity) && opts.reflectivity! >= 0 && opts.reflectivity! <= 1)) {
+    throw new Error("lit: reflectivity must be a number in 0..1, got " + opts.reflectivity)
+  }
+  if (triplanar && normalMap) throw new Error("lit: normalMap cannot combine with triplanar (normal maps sample by uv)")
+  if (triplanar && mapTransform) throw new Error("lit: mapTransform cannot combine with triplanar (its repeat is the triplanar value)")
+  if (mapTransform && !map && !normalMap && !emissiveMap && !specularMap) {
+    throw new Error("lit: mapTransform without a map to transform")
+  }
   let flags: LitClass = {
     map,
     vertexColors: opts.vertexColors === true,
     triplanar,
     transparent: opts.transparent === true,
-    shadow: opts.receiveShadow !== false,
+    receiveShadow: opts.receiveShadow !== false,
     cull,
     alphaTest,
     fog: opts.fog !== false,
+    normalMap,
+    emissive,
+    emissiveMap,
+    specularMap,
+    env,
+    lightMap,
+    mapTransform,
+    skinned: opts.skinned === true,
+    instanced: opts.instanced === true || opts.instanceColors === true,
+    instanceColors: opts.instanceColors === true,
   }
   let key = litClassKey(flags)
   let cls = litClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
-      vertex: flags.vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
+      vertex: litVertex(flags),
       fragment: litFragment(flags),
+      shadowVertex: flags.instanced ? shadowDepthVertex(flags.skinned, true) : undefined,
+      instanceAttributes: stockInstanceAttributes(flags.instanced, flags.instanceColors),
+      instanceStyle: flags.instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
       transparent: flags.transparent,
       cull,
       label: "scene-lit-" + key,
     })
     litClasses.set(key, cls)
   }
-  let params: ShaderParams = { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 }
+  let params: ShaderParams = {
+    uColor,
+    uSpecular: opts.specular ?? (specularMap ? 1 : SURFACE_DEFAULTS.specular),
+    uShininess: opts.shininess ?? SURFACE_DEFAULTS.shininess,
+  }
   if (triplanar) params.uTriplanar = opts.triplanar!
   if (alphaTest) params.uAlphaTest = opts.alphaTest!
-  // A UV-mapped cutout casts its cutout; a color-only or triplanar
-  // alphaTest keeps the plain (cull-only) variant.
-  let cutout = alphaTest && map && !triplanar
+  if (normalMap) params.uNormalScale = opts.normalScale ?? 1
+  if (env) params.uReflectivity = opts.reflectivity!
+  if (emissive) {
+    let k = opts.emissiveIntensity ?? 1
+    params.uEmissive = linearColor(opts.emissive ?? [1, 1, 1]).map(c => c * k)
+  }
+  if (lightMap) params.uLightMapIntensity = opts.lightMapIntensity ?? 1
+  if (mapTransform) params.uMapTransform = mapTransformParam(opts.mapTransform!)
+  let textures: TextureBindings | undefined
+  if (map || normalMap || emissiveMap || specularMap || lightMap) {
+    textures = {}
+    if (map) textures.uMap = opts.map!
+    if (normalMap) textures.uNormalMap = opts.normalMap!
+    if (emissiveMap) textures.uEmissiveMap = opts.emissiveMap!
+    if (specularMap) textures.uSpecularMap = opts.specularMap!
+    if (lightMap) textures.uLightMap = opts.lightMap!
+  }
+  // A mapped cutout casts its cutout, triplanar included (the shadow
+  // source resolves the base exactly as the main one does). A color-only
+  // alphaTest is a constant over the mesh - all or nothing, and nothing
+  // needs no program - so it keeps the plain cull-only variant.
   let material = cls.instance({
     params,
-    textures: map ? { uMap: opts.map! } : undefined,
-    shadow: cutout ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
+    textures,
+    shadow:
+      alphaTest && map
+        ? litShadowMaterial(flags, uColor, opts.alphaTest!, opts.triplanar, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+        : undefined,
   })
   return material
 }
 
+export type StandardOptions = Omit<LitOptions, "specular" | "shininess" | "specularMap" | "reflectivity"> & {
+  /** How metallic the surface is, 0..1 (default 0; 1 when `metalnessMap`
+   * is given - the map is the value): a metal has no diffuse and
+   * reflects tinted by `color`, a dielectric reflects 4% face-on.
+   * Three's metalness; metallic in Godot, Unity and glTF. */
+  metalness?: number
+  /** Perceptual roughness, 0..1 (default 1): 0 a mirror, 1 fully matte;
+   * it widens the highlight and blurs the environment reflection alike.
+   * Unity's smoothness is 1 - roughness. */
+  roughness?: number
+  /** A texture whose BLUE channel scales `metalness` per fragment, and
+   * `roughnessMap` one whose GREEN channel scales `roughness`: Three's
+   * two options over glTF's ONE packed metallicRoughnessTexture, so
+   * pass the same texture to both (createModel's `maps` does). Data
+   * maps, created as plain rgba8; sampled at the same uv as `map`. */
+  metalnessMap?: TextureId
+  roughnessMap?: TextureId
+}
+
+// The `standard` class key: lit's minus the Blinn-Phong slots (env is
+// always on, the environment being intrinsic to the model) plus the two
+// packed maps. Its cutout shadow is lit's own, keyed on the shared subset
+// in lit's order, so the two materials share shadow programs.
+type StandardClass = Omit<LitClass, "specularMap" | "env"> & { metalnessMap: boolean; roughnessMap: boolean }
+
+function standardClassKey(c: StandardClass): string {
+  return Object.values(c).join("|")
+}
+let standardClasses = new Map<string, ShaderMaterialClass>()
+
+function standardShadowFlags(c: StandardClass): LitClass {
+  return {
+    map: c.map,
+    vertexColors: c.vertexColors,
+    triplanar: c.triplanar,
+    transparent: c.transparent,
+    receiveShadow: c.receiveShadow,
+    cull: c.cull,
+    alphaTest: c.alphaTest,
+    fog: c.fog,
+    normalMap: c.normalMap,
+    emissive: c.emissive,
+    emissiveMap: c.emissiveMap,
+    specularMap: false,
+    env: false,
+    lightMap: c.lightMap,
+    mapTransform: c.mapTransform,
+    skinned: c.skinned,
+    instanced: c.instanced,
+    instanceColors: c.instanceColors,
+  }
+}
+
+/**
+ * The metalness/roughness material, the look authored assets expect
+ * (Three's MeshStandardMaterial, Godot's StandardMaterial3D, Unity's
+ * Standard): the same base, maps, cutout, shadows, emissive, fog and
+ * lights as `lit`, shaded with GGX specular (PBR in `@solidrt/3d/glsl`)
+ * and the scene's environment sampled ALWAYS as the split sum over its
+ * mip chain - no `reflectivity` switch, the environment is intrinsic to
+ * the model. Light intensities read as lit's (1 lights a white matte
+ * surface to 1). Without an environment set a metal shows only its
+ * highlights - its diffuse is zero and there is nothing to reflect, as
+ * in Three and Godot - so give the scene one. One program per option
+ * combination, shared by every instance, like lit.
+ */
+export function standard(opts: StandardOptions = {}): Material {
+  let uColor = colorParam(opts.color ?? [1, 1, 1])
+  let map = opts.map !== undefined
+  let triplanar = map && opts.triplanar !== undefined
+  let alphaTest = opts.alphaTest !== undefined
+  let cull = opts.cull ?? "back"
+  let normalMap = opts.normalMap !== undefined
+  let emissiveMap = opts.emissiveMap !== undefined
+  let emissive = opts.emissive !== undefined || emissiveMap
+  let metalnessMap = opts.metalnessMap !== undefined
+  let roughnessMap = opts.roughnessMap !== undefined
+  let lightMap = opts.lightMap !== undefined
+  let mapTransform = opts.mapTransform !== undefined
+  let metalness = opts.metalness ?? (metalnessMap ? 1 : SURFACE_DEFAULTS.metalness)
+  let roughness = opts.roughness ?? SURFACE_DEFAULTS.roughness
+  if (!(Number.isFinite(metalness) && metalness >= 0 && metalness <= 1)) {
+    throw new Error("standard: metalness must be a number in 0..1, got " + opts.metalness)
+  }
+  if (!(Number.isFinite(roughness) && roughness >= 0 && roughness <= 1)) {
+    throw new Error("standard: roughness must be a number in 0..1, got " + opts.roughness)
+  }
+  if (triplanar && normalMap) throw new Error("standard: normalMap cannot combine with triplanar (normal maps sample by uv)")
+  if (triplanar && (metalnessMap || roughnessMap)) {
+    throw new Error("standard: metalnessMap and roughnessMap cannot combine with triplanar (they sample by uv)")
+  }
+  if (triplanar && mapTransform) throw new Error("standard: mapTransform cannot combine with triplanar (its repeat is the triplanar value)")
+  if (mapTransform && !map && !normalMap && !emissiveMap && !metalnessMap && !roughnessMap) {
+    throw new Error("standard: mapTransform without a map to transform")
+  }
+  let flags: StandardClass = {
+    map,
+    vertexColors: opts.vertexColors === true,
+    triplanar,
+    transparent: opts.transparent === true,
+    receiveShadow: opts.receiveShadow !== false,
+    cull,
+    alphaTest,
+    fog: opts.fog !== false,
+    normalMap,
+    emissive,
+    emissiveMap,
+    lightMap,
+    mapTransform,
+    skinned: opts.skinned === true,
+    instanced: opts.instanced === true || opts.instanceColors === true,
+    instanceColors: opts.instanceColors === true,
+    metalnessMap,
+    roughnessMap,
+  }
+  let key = standardClassKey(flags)
+  let cls = standardClasses.get(key)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: litVertex(flags),
+      fragment: standardFragment(flags),
+      shadowVertex: flags.instanced ? shadowDepthVertex(flags.skinned, true) : undefined,
+      instanceAttributes: stockInstanceAttributes(flags.instanced, flags.instanceColors),
+      instanceStyle: flags.instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
+      transparent: flags.transparent,
+      cull,
+      label: "scene-standard-" + key,
+    })
+    standardClasses.set(key, cls)
+  }
+  let params: ShaderParams = { uColor, uMetalness: metalness, uRoughness: roughness }
+  if (triplanar) params.uTriplanar = opts.triplanar!
+  if (alphaTest) params.uAlphaTest = opts.alphaTest!
+  if (normalMap) params.uNormalScale = opts.normalScale ?? 1
+  if (emissive) {
+    let k = opts.emissiveIntensity ?? 1
+    params.uEmissive = linearColor(opts.emissive ?? [1, 1, 1]).map(c => c * k)
+  }
+  if (lightMap) params.uLightMapIntensity = opts.lightMapIntensity ?? 1
+  if (mapTransform) params.uMapTransform = mapTransformParam(opts.mapTransform!)
+  let textures: TextureBindings | undefined
+  if (map || normalMap || emissiveMap || metalnessMap || roughnessMap || lightMap) {
+    textures = {}
+    if (map) textures.uMap = opts.map!
+    if (normalMap) textures.uNormalMap = opts.normalMap!
+    if (emissiveMap) textures.uEmissiveMap = opts.emissiveMap!
+    if (metalnessMap) textures.uMetalnessMap = opts.metalnessMap!
+    if (roughnessMap) textures.uRoughnessMap = opts.roughnessMap!
+    if (lightMap) textures.uLightMap = opts.lightMap!
+  }
+  return cls.instance({
+    params,
+    textures,
+    shadow:
+      alphaTest && map
+        ? litShadowMaterial(standardShadowFlags(flags), uColor, opts.alphaTest!, opts.triplanar, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+        : undefined,
+  })
+}
+
+let litShadowClasses = new Map<string, ShaderMaterialClass>()
+
+/** The shadow variant of a discarding lit material: litShadowFragment on
+ * the same vertex stage, culling the side the material's own pipeline
+ * keeps (Three's shadowSide rule), instanced with the same values so the
+ * cutout it casts is the one it draws. Its params carry only the uniforms
+ * its program declares - per-entry params reject unknown names. One class
+ * per lit class, an instance per material. */
+function litShadowMaterial(
+  flags: LitClass,
+  uColor: number[],
+  uAlphaTest: number,
+  triplanar: number | undefined,
+  uMap: TextureId,
+  uMapTransform?: number[],
+): Material {
+  // A skinned cutout keeps its skinning (flags.skinned rides into the
+  // key and the vertex stage), so the shadow it casts is posed: the
+  // shadow entry merges the mesh's uBones binding (Material.skinned).
+  let key = litClassKey(flags)
+  let cls = litShadowClasses.get(key)
+  if (cls === undefined) {
+    let fragment = litShadowFragment(flags)
+    if (fragment === undefined) throw new Error("litShadowMaterial: " + key + " cannot discard")
+    cls = shaderMaterialClass({
+      vertex: litVertex(flags),
+      fragment,
+      cull: shadowCull(flags.cull),
+      instanceAttributes: stockInstanceAttributes(flags.instanced, flags.instanceColors),
+      label: "scene-lit-shadow-" + key,
+    })
+    litShadowClasses.set(key, cls)
+  }
+  let params: ShaderParams = { uColor, uAlphaTest }
+  if (flags.triplanar) params.uTriplanar = triplanar!
+  if (uMapTransform !== undefined) params.uMapTransform = uMapTransform
+  let material = cls.instance({ params, textures: { uMap } })
+  // Only triplanar sampling reads the normal here: everywhere else the
+  // linker drops vNormal and uNormal reflects inactive, so writing it per
+  // move would warn every time. The value cannot matter, skip the write.
+  if (!flags.triplanar) material.normalMatrix = false
+  return material
+}
+
 // The shadow depth pass: position only, no color of interest (the target's
 // depth texture is the output; the color write is the pipeline's minimum).
 // Front faces culled, Three's shadowSide default: the map holds each
 // caster's BACK surface, so a receiving front face at the same depth
 // compares lit without a bias and acne needs no fighting on closed meshes.
-const SHADOW_DEPTH_VERTEX = glsl`
+// The skinned form applies the skin matrix first, so a posed caster's
+// depth is its pose (the entry's uBones binding comes from the mesh, see
+// Material.skinned); the instanced form places each copy by its instance
+// matrix, so a fleet casts where its records stand - the stock instanced
+// materials pass it as their class's shadowVertex.
+function shadowDepthVertex(skinned: boolean, instanced: boolean): string {
+  let local = skinned ? "(skin * vec4(aPos, 1.0))" : "vec4(aPos, 1.0)"
+  return glsl`
   in vec3 aPos;
+  ${skinned ? SKIN_DECLS : ""}
+  ${instanced ? INSTANCE_MATRIX : ""}
   uniform mat4 uModel;
   uniform mat4 uViewProj;
   void main() {
-    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
+    ${skinned ? SKIN_MATRIX : ""}
+    gl_Position = uViewProj * uModel * ${instanced ? `(instanceMatrix() * ${local})` : local};
   }
 `
+}
 
 const SHADOW_DEPTH_FRAGMENT = glsl`
   void main() {
@@ -408,22 +734,23 @@ const SHADOW_DEPTH_FRAGMENT = glsl`
   }
 `
 
-let shadowDepth = new Map<CullMode, Material>()
+let shadowDepth = new Map<string, Material>()
 
 /** The override material of a scene's shadow view (internal): one class
- * per cull mode for the app, built on first use. The default, "front",
- * is the caster's back surface (see above); a material culling
- * otherwise carries its own variant as Material.shadow. */
-export function shadowDepthMaterial(cull: CullMode = "front"): Material {
-  let material = shadowDepth.get(cull)
+ * per cull mode x skinned for the app, built on first use. The default,
+ * "front", is the caster's back surface (see above); a material culling
+ * or skinning otherwise carries its own variant as Material.shadow. */
+export function shadowDepthMaterial(cull: CullMode = "front", skinned = false): Material {
+  let key = cull + (skinned ? "|skinned" : "")
+  let material = shadowDepth.get(key)
   if (material === undefined) {
     material = shaderMaterialClass({
-      vertex: SHADOW_DEPTH_VERTEX,
+      vertex: shadowDepthVertex(skinned, false),
       fragment: SHADOW_DEPTH_FRAGMENT,
       cull,
-      label: "scene-shadow-depth-" + cull,
+      label: "scene-shadow-depth-" + key,
     }).instance()
-    shadowDepth.set(cull, material)
+    shadowDepth.set(key, material)
   }
   return material
 }
@@ -434,56 +761,56 @@ function shadowCull(cull: CullMode): CullMode {
   return cull === "none" ? "none" : cull === "back" ? "front" : "back"
 }
 
-/** "back" maps to the default depth material, so its variant is
- * undefined. */
-function shadowVariant(cull: CullMode): Material | undefined {
-  return cull === "back" ? undefined : shadowDepthMaterial(shadowCull(cull))
+/** "back" unskinned maps to the default depth material, so its variant
+ * is undefined; a skinned class always needs its own (the default does
+ * not skin). */
+function shadowVariant(cull: CullMode, skinned: boolean): Material | undefined {
+  if (cull === "back" && !skinned) return undefined
+  return shadowDepthMaterial(shadowCull(cull), skinned)
 }
 
-// The cutout depth pass: the caster's map alpha (times its color alpha)
-// against its alphaTest, the lit fragment's test minus everything else.
-const SHADOW_CUTOUT_VERTEX = glsl`
-  in vec3 aPos;
-  in vec2 aUV;
-  out vec2 vUv;
-  uniform mat4 uModel;
-  uniform mat4 uViewProj;
-  void main() {
-    gl_Position = uViewProj * uModel * vec4(aPos, 1.0);
-    vUv = aUV;
-  }
-`
-
-const SHADOW_CUTOUT_FRAGMENT = glsl`
-  in vec2 vUv;
-  uniform sampler2D uMap;
-  uniform vec4 uColor;
-  uniform float uAlphaTest;
-  void main() {
-    if (texture(uMap, vUv).a * uColor.a < uAlphaTest) discard;
-    fragColor = vec4(1.0);
-  }
-`
+let unlitShadowClasses = new Map<string, ShaderMaterialClass>()
 
-let shadowCutout = new Map<CullMode, ShaderMaterialClass>()
-
-/** The shadow variant of a UV-mapped cutout material: one class per
- * shadow cull mode, an instance per material (its map, color, cutoff). */
-function shadowCutoutMaterial(cull: CullMode, uColor: number[], uAlphaTest: number, uMap: TextureId): Material {
-  let cls = shadowCutout.get(cull)
+/** 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,
+  skinned: boolean,
+  instanced: boolean,
+  instanceColors: boolean,
+  uColor: number[],
+  uAlphaTest: number,
+  uMap: TextureId,
+  uMapTransform?: number[],
+): Material {
+  let key = [cull, uMapTransform !== undefined, skinned, instanced, instanceColors].join("|")
+  let cls = unlitShadowClasses.get(key)
   if (cls === undefined) {
+    let fragment = unlitShadowFragment({ map: true, alphaTest: true, mapTransform: uMapTransform !== undefined, instanceColors })
+    if (fragment === undefined) throw new Error("unlitShadowMaterial: the cutout options cannot discard")
     cls = shaderMaterialClass({
-      vertex: SHADOW_CUTOUT_VERTEX,
-      fragment: SHADOW_CUTOUT_FRAGMENT,
+      vertex: unlitVertex({ skinned, instanced, instanceColors }),
+      fragment,
       cull,
-      label: "scene-shadow-cutout-" + cull,
+      instanceAttributes: stockInstanceAttributes(instanced, instanceColors),
+      label: "scene-unlit-shadow-" + key,
     })
-    shadowCutout.set(cull, cls)
+    unlitShadowClasses.set(key, cls)
   }
-  return cls.instance({ params: { uColor, uAlphaTest }, textures: { uMap } })
+  let params: ShaderParams = { uColor, uAlphaTest }
+  if (uMapTransform !== undefined) params.uMapTransform = uMapTransform
+  return cls.instance({ params, textures: { uMap } })
 }
 
-export type SpriteOptions = UnlitOptions & {
+/** A sprite's options: unlit's, minus instancing (the billboard stage
+ * places one quad per mesh; an instanced billboard field is a custom
+ * class's vertex stage). */
+export type SpriteOptions = Omit<UnlitOptions, "instanced" | "instanceColors"> & {
   /** Which way the quad turns to face the camera. `"full"` (default,
    * Three's Sprite): both axes follow the view, the quad is always flat
    * to the screen. `"fixed-y"` (Godot's BILLBOARD_FIXED_Y): only the yaw
@@ -555,9 +882,12 @@ let spriteClasses = new Map<string, ShaderMaterialClass>()
  * for an opaque one. Culling is off: a camera-facing quad has no back.
  */
 export function sprite(opts: SpriteOptions = {}): Material {
-  let color = opts.color ?? [1, 1, 1]
-  let a = color.length === 4 ? color[3] : 1
-  let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
+  // Excluded by the type and checked for a JS caller: the billboard stage
+  // has no instance placement, so the flags would otherwise be ignored.
+  if ((opts as UnlitOptions).instanced || (opts as UnlitOptions).instanceColors) {
+    throw new Error("sprite: instanced and instanceColors are not sprite options (one billboard per mesh)")
+  }
+  let uColor = colorParam(opts.color ?? [1, 1, 1])
   let map = opts.map !== undefined
   let transparent = opts.transparent !== false
   let fixedY = opts.billboard === "fixed-y"
@@ -567,7 +897,7 @@ export function sprite(opts: SpriteOptions = {}): Material {
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: unlitFragment(map, false, transparent, fog),
+      fragment: unlitFragment({ map, transparent, fog }),
       transparent,
       cull: "none",
       label: "scene-sprite-" + key,
@@ -598,21 +928,51 @@ function needsHeader(source: string): boolean {
 // engine's own attributeless fullscreen triangle (gl_VertexID, no vertex
 // buffer), emitting the SAME vUV the shader-target contract provides: 0..1
 // with origin at the displayed top-left - so a backdrop fragment written
-// for createShaderTexture ports verbatim.
+// for createShaderTexture ports verbatim - plus vRay, the world-space
+// view ray through the pixel: the vertex's own clip position carried back
+// to world at the near and far planes through the camera's shared
+// uInvViewProj, far minus near. Linear interpolation is exact for it
+// (at a fixed clip depth the unprojected point is affine in clip x, y
+// under either projection), and under an orthographic camera every ray is
+// the camera's forward. Unnormalized: a sky fragment normalizes it.
 const BACKGROUND_VERTEX = glsl`
+  uniform mat4 uInvViewProj;
   out vec2 vUV;
+  out vec3 vRay;
   void main() {
     vec2 p = vec2(float((gl_VertexID << 1) & 2), float(gl_VertexID & 2));
     vUV = p;
-    gl_Position = vec4(p * 2.0 - 1.0, 0.0, 1.0);
+    vec2 ndc = p * 2.0 - 1.0;
+    vec4 near = uInvViewProj * vec4(ndc, -1.0, 1.0);
+    vec4 far = uInvViewProj * vec4(ndc, 1.0, 1.0);
+    vRay = far.xyz / far.w - near.xyz / near.w;
+    gl_Position = vec4(ndc, 0.0, 1.0);
   }
 `
 
 // Pipeline fragments get no vUV from the engine preamble (a pipeline's
 // varyings are its own), so the background slot injects the full
-// shader-target fragment contract itself: vUV, fragColor, iResolution.
+// shader-target fragment contract itself: vUV, fragColor, iResolution,
+// its own vRay, and the OUTPUT set, so a sky can end with outputColor
+// and take the scene's exposure and tone mapping.
 const BACKGROUND_FRAGMENT_PREAMBLE =
-  "#version 300 es\nprecision highp float;\nin vec2 vUV;\nout vec4 fragColor;\nuniform vec2 iResolution;\n"
+  "#version 300 es\nprecision highp float;\nin vec2 vUV;\nin vec3 vRay;\nout vec4 fragColor;\nuniform vec2 iResolution;\n" + OUTPUT + "\n"
+
+// The skybox fragment behind setBackground({ cube }): the view ray through
+// the sky's rotation (the INVERSE turn, written by skyboxParams, so the
+// sky itself turns by +rotation like a node would), then the cube lookup
+// times the intensity, through the output
+// stage (the preamble declares it) like every lit pixel. Opaque: the
+// skybox replaces the clearColor exactly as a GLSL background does.
+export const SKYBOX_FRAGMENT = glsl`
+  uniform samplerCube uSky;
+  uniform float uSkyIntensity;
+  uniform mat4 uSkyRotation;
+  void main() {
+    vec3 dir = mat3(uSkyRotation) * normalize(vRay);
+    fragColor = outputColor(texture(uSky, dir).rgb * uSkyIntensity, 1.0);
+  }
+`
 
 /** The scene's background pipeline (internal - reached via
  * scene.setBackground): depth-free, attributeless, drawn as entry zero of
@@ -664,12 +1024,40 @@ export type ShaderMaterialClassOptions = {
    * beside the layout's own, and each drawn instance gets one record from
    * the mesh's instance buffer (interleaved floats in this order). A class
    * with instance attributes makes INSTANCED materials: attach their meshes
-   * with createInstancedMesh, which carries the records - a createMesh mesh
-   * is rejected at add(). A per-instance transform is data, not a matrix:
-   * a position/yaw/scale record beats four vec4 columns for most fleets,
-   * and the composed uModel still places the whole population.
+   * with createInstancedMesh or createRecordMesh, which carry the records
+   * - a createMesh mesh is rejected at add(). Each attribute's `slot`
+   * (default 0) picks the buffer: an instanced mesh binds the core's
+   * matrix records (INSTANCE_MATRIX_ATTRIBUTES, exactly) to slot 0 and
+   * the app's style records - any layout, written per instance with
+   * setInstanceStyle - to slot 1; a record mesh is slot 0 only, its
+   * records whatever the stage reads (a position/yaw/scale record beats
+   * four vec4 columns for a JS-stepped fleet, and the composed uModel
+   * still places the whole population).
+   */
+  instanceAttributes?: InstanceAttribute[]
+  /** The style record a fresh instance starts with (the slot-1
+   * attributes' floats, in order); default zeros. The identity of
+   * whatever the stage does with the record - white for a multiplied
+   * tint. */
+  instanceStyle?: ArrayLike<number>
+  /**
+   * The class's vertex stage reduced to POSITION - the instance
+   * placement, a displacement, whatever moves vertices, minus every
+   * color/normal/uv output - for the shadow pass. With it the class's
+   * instances cast: a shadow view draws their meshes with a depth
+   * pipeline built from this stage and the shared depth fragment
+   * (culling the side the class culls, binding the instance slots this
+   * stage reads - the records always, a style slot only when it names
+   * one of its attributes), so
+   * an instanced fleet's shadows land where its records put the
+   * vertices. Same standard-uniform contract as `vertex` (uModel and
+   * uViewProj required); one extra program per class, built at first
+   * cast. Without it, instanced meshes are SKIPPED by shadow views
+   * (`castShadow` does nothing for them) - a non-instanced class needs
+   * it only when its vertex stage moves vertices. Depth-only: a cutout's
+   * discard still goes through the `shadow` instance option.
    */
-  instanceAttributes?: VertexAttribute[]
+  shadowVertex?: string
   /** Blend over what is behind, with the scene sorting this material's
    * meshes back-to-front after the opaque ones (see Material.transparent).
    * Sets the pipeline defaults blend "alpha" and depthWrite false; the
@@ -696,8 +1084,11 @@ export type ShaderMaterialInstanceOptions = {
   params?: ShaderParams
   textures?: TextureBindings
   /** The depth variant a shadow view draws this instance with (see
-   * Material.shadow): a cutout's discard, an instanced class's vertex
-   * placement. Default: the depth pass with this class's cull side. */
+   * Material.shadow): a cutout's discard, a placement the class-level
+   * `shadowVertex` cannot express. Default: the class's shadowVertex
+   * depth material when one is declared, else the depth pass with this
+   * class's cull side, skinned like the class when its vertex skins by
+   * uBones. */
   shadow?: Material
 }
 
@@ -732,10 +1123,12 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   // shared params skipping undeclared names the omission would otherwise
   // surface as a silently untransformed render, not an error.
   for (let name of ["uModel", "uViewProj"]) {
-    if (!new RegExp("\\b" + name + "\\b").test(opts.vertex)) {
-      throw new Error(
-        "shaderMaterial vertex stage must declare and use '" + name + "' (see the standard uniform set in AGENTS.md)",
-      )
+    for (let source of opts.shadowVertex === undefined ? [opts.vertex] : [opts.vertex, opts.shadowVertex]) {
+      if (!new RegExp("\\b" + name + "\\b").test(source)) {
+        throw new Error(
+          "shaderMaterial vertex stage must declare and use '" + name + "' (see the standard uniform set in AGENTS.md)",
+        )
+      }
     }
   }
   let program: ProgramId | undefined
@@ -743,12 +1136,47 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   // Attributes live in the vertex stage only, so unlike the uNormal scan
   // there is nothing to look for in the fragment source.
   let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
+  // Skinning is a vertex-stage affair like the attributes; a source that
+  // mentions uBones skins by the mesh's palette texture (Material.skinned).
+  let skinned = /\buBones\b/.test(opts.vertex)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
   let depth = opts.depth ?? true
   let cull = opts.cull ?? "back"
   // An empty list declares nothing - same as absent (the engine requires an
   // instance buffer exactly when attributes are declared).
   let instanceAttributes = opts.instanceAttributes?.length ? opts.instanceAttributes.map(a => ({ ...a })) : undefined
+  // The shadowVertex depth pass binds the instance slots its stage reads
+  // from - the record slot always (a stage reading none of it cannot
+  // place the instances, an error here), a style slot only when the
+  // stage names one of its attributes - and declares each bound slot's
+  // whole layout, since a slot's stride is the record's (an unread
+  // attribute in a bound slot is inactive, like an extra geometry channel).
+  let shadowAttributes: InstanceAttribute[] | undefined
+  if (opts.shadowVertex !== undefined && instanceAttributes !== undefined) {
+    let source = opts.shadowVertex
+    let named = (a: InstanceAttribute) => new RegExp("\\b" + a.name + "\\b").test(source)
+    let slots = new Set(instanceAttributes.filter(named).map(a => a.slot ?? 0))
+    if (!slots.has(0)) throw new Error("shaderMaterial shadowVertex must read the slot-0 instance attributes it places instances by")
+    shadowAttributes = instanceAttributes.filter(a => slots.has(a.slot ?? 0))
+  }
+  // The shadowVertex depth material: one class and one shared instance,
+  // built the first time a caster of this class meets a shadow view.
+  let shadowClass: ShaderMaterialClass | undefined
+  let classShadow: Material | undefined
+  let shadowFor = (): Material | undefined => {
+    if (opts.shadowVertex === undefined) return undefined
+    if (classShadow === undefined) {
+      shadowClass = shaderMaterialClass({
+        vertex: opts.shadowVertex,
+        fragment: SHADOW_DEPTH_FRAGMENT,
+        cull: shadowCull(cull),
+        instanceAttributes: shadowAttributes,
+        label: (opts.label ?? "shader-material") + "-shadow",
+      })
+      classShadow = shadowClass.instance()
+    }
+    return classShadow
+  }
   let programFor = (): ProgramId => {
     if (program === undefined) {
       let vs = compileShader("vertex", opts.vertex, { header: needsHeader(opts.vertex) })
@@ -788,16 +1216,18 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
     instance(inst = {}) {
       return {
         normalMatrix,
+        skinned,
         attributes,
         transparent,
         instanceAttributes,
+        instanceStyle: opts.instanceStyle,
         pipeline: pipelineFor,
         params: inst.params ?? {},
         textures: inst.textures,
         // Lazy: the depth materials are shaderMaterialClass instances
         // themselves, so an eager variant would recurse into its own cache.
         get shadow() {
-          return inst.shadow ?? shadowVariant(cull)
+          return inst.shadow ?? shadowFor() ?? shadowVariant(cull, skinned)
         },
       }
     },
@@ -808,6 +1238,11 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         destroyProgram(program)
         program = undefined
       }
+      if (shadowClass !== undefined) {
+        shadowClass.dispose()
+        shadowClass = undefined
+        classShadow = undefined
+      }
     },
   }
 }