@solidrt/3d 0.0.53 → 0.0.54

package/AGENTS.md

@@ -131,9 +131,12 @@ blendMode and pointer events like any element.
   the upload), so swapping `<Mesh geometry>` reactively never accumulates
   old generations. `disposeGeometry` is the immediate explicit free.
 - Materials dedupe hard: one program + one pipeline per material CLASS
-  (unlit color, unlit map, each opaque or transparent), `depth: true` +
-  `cull: "back"`; an instance is
-  just per-entry uniforms (`uColor`) and bindings (`uMap`).
+  (a `shaderMaterialClass` per option combination for unlit, lit and
+  sprite alike: map x transparent x cull x alphaTest, lit's extras on
+  top), `depth: true` + `cull: "back"` unless the material says otherwise
+  (`cull: "none"` for double-sided geometry; lit flips the normal on back
+  faces); an instance is just per-entry uniforms (`uColor`) and bindings
+  (`uMap`).
 - The pure pieces (`math.ts`, `order.ts`, `geometry.ts`,
   `profile.ts`, `sweep.ts`, `gltf.ts`, `model-file.ts`) are Solid-free and
   GPU-free BY DESIGN so they can be checked headless (and, for the two
@@ -168,6 +171,31 @@ elsewhere. Called once, untracked, inside the scene context. Scene
 layout, so render and display size separate - render at 2x and display
 smaller for supersampling.
 
+Filling the window: `width`/`height` are DEVICE pixels, the leaf's layout
+is LOGICAL. A `designSize` view fits the leaf to the window but never
+changes the target, so on a HiDPI display a 720-pixel scene is stretched
+across ~1100 device pixels and looks soft, and nothing warns (the
+examples' `SIZE = 720` is a verification convenience, not a sizing
+model). Render at the window's device size and lay the leaf out at its
+logical size:
+
+```tsx
+let target = createMemo(() => {
+  let { width, height } = windowSize()
+  let scale = displayScale()
+  return { w: Math.round(width * scale), h: Math.round(height * scale) }
+})
+<Scene width={target().w} height={target().h}
+       output={t => <texture src={t} width={windowSize().width}
+                             height={windowSize().height}
+                             {...useScene().scene.handlersFor(windowSize)} />}>
+```
+
+`windowSize` and `displayScale` come from `@solidrt/core`. The leaf's
+layout differs from the target, so it takes `handlersFor` (below), not
+`handlers`; `useScene()` works inside `output` because it runs in the
+scene context.
+
 Camera control: `createOrbitCamera(scene, { target?, azimuth?, elevation?,
 distance?, min/maxDistance?, min/maxElevation?, orbitSpeed?, rotateSpeed?,
 zoomSpeed?, zoomAnchor?, rotateAnchor?, panSpeed?, viewport?, clampTarget? })`
@@ -321,8 +349,9 @@ uint16/uint32 indices by vertex count automatically.
 
 Materials:
 
-- `unlit({ color?, map? })` - straight `[r, g, b, a?]` 0..1, premultiplied
-  internally.
+- `unlit({ color?, map?, transparent?, cull?, alphaTest? })` - straight
+  `[r, g, b, a?]` 0..1, premultiplied internally; `cull` and `alphaTest`
+  as on lit (a mapped cutout casts its cutout).
 - `sprite({ color?, map?, transparent?, billboard? })` - unlit on a quad
   that turns to face the camera IN THE VERTEX STAGE (off the shared
   uCamRight/uCamUp, or uCamPos for `billboard: "fixed-y"`, which yaws
@@ -472,17 +501,22 @@ the directional list, Lambert diffuse, Blinn-Phong highlight when
 `specular` (0..1 strength) is set with `shininess` (default 30), the
 same `color`/`map`/`transparent` as unlit, `vertexColors: true` to
 multiply by the colored layout's aColor (so the geometry must carry it),
-and `triplanar: n` to sample `map` by world position at `n` repeats per
-world unit, blended across the three axis planes by the normal. Triplanar
+`triplanar: n` to sample `map` by world position at `n` repeats per
+world unit, blended across the three axis planes by the normal, and
+`alphaTest: t` for a cutout (a fragment whose final alpha is below `t`
+is discarded; Three's alphaTest, glTF MASK): opaque, depth-written, no
+sorting, usually with `cull: "none"` for cards. Triplanar
 is an OPTION, not the default: generators emit 0..1 UVs per face, so a
 map on a plane is a decal (UV) while a map on generated scenery wants one
 density across parts of any size (triplanar); the map must be created
 with `wrap: "repeat"`. Internally one `shaderMaterialClass` per option
-combination (map x vertexColors x triplanar x transparent), cached for
-the app's lifetime, one pipeline per vertex layout - a thousand lit
-meshes share one program. The view vector comes from the shared uCamPos;
-`uTriplanar` is declared only by the triplanar classes so the other
-classes do not warn about an inactive uniform.
+combination (map x vertexColors x triplanar x transparent x cull x
+alphaTest), cached for the app's lifetime, one pipeline per vertex layout
+- a thousand lit meshes share one program. The view vector comes from the
+shared uCamPos; `uTriplanar` and `uAlphaTest` are declared only by the
+classes that use them (the cutoff is a per-entry value, so every
+alphaTest material shares one class) so the other classes do not warn
+about an inactive uniform.
 
 ## Models
 
@@ -494,7 +528,8 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   bun and on flux): `ModelData` = `parts` (one per mesh node, its NAME
   kept, vertices in the standard layout with the node's WORLD transform
   baked in), `materials` (base color factor, `map` = index into `images`,
-  `doubleSided`, `transparent` = alphaMode BLEND), `images` (the encoded
+  `doubleSided`, `transparent` = alphaMode BLEND, `alphaMode` as written
+  and `alphaCutoff`, spec default 0.5), `images` (the encoded
   PNG/JPEG bytes, undecoded) and `bounds`. A .gltf's external files come
   through `resolve(uri)` (uri as written, still percent-encoded;
   `gltfExternalUris(bytes)` lists them so an async caller can read them
@@ -526,10 +561,10 @@ next to it, or single-file .glb) and become a Group of meshes, Three's
   "binary" }` then `createModel(parseGltf(bytes))`, see
   `examples/model.tsx`); bake anything big.
 
-Not in the subset, reported or dropped: `doubleSided` is reported and NOT
-applied (the standard materials cull back faces); vertex colors, tangents
-and further UV sets are dropped; samplers are ignored (every texture
-repeats); alphaMode MASK draws opaque; emissive/additive parts of a model
+Applied: `doubleSided` (the default material draws it with `cull:
+"none"`) and alphaMode MASK (`alphaTest: alphaCutoff`). Not in the
+subset, dropped: vertex colors, tangents and further UV sets; samplers
+are ignored (every texture repeats); emissive/additive parts of a model
 draw as their base color (a model's "glow" cards come out as dark wedges).
 The follow-ups are filed in okf/backlog/3d-model-loader.md.
 
@@ -568,7 +603,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   are opaque to the library, so any inferred box would be a guess. Supply
   `bounds` for anything pickable or transparent.
 - Transparency is an EXPLICIT material flag, Three's rule: `unlit({ color:
-  [r, g, b, 0.5] })` still draws opaque; `unlit({ ..., transparent: true })`
+  [r, g, b, 0.5] })` still draws opaque, and opaque means it: the standard
+  classes write alpha 1 when not `transparent` (the scene target is
+  composited premultiplied, so a leaked texel or color alpha would punch
+  a see-through hole in an opaque draw - the source of "white cutouts"
+  on an alpha-mapped model drawn without alphaTest). A `shaderMaterial`
+  writes its own fragColor: give an opaque look alpha 1 too.
+  `unlit({ ..., transparent: true })`
   (or `shaderMaterial({ transparent: true })`) builds the pipeline with
   `blend: "alpha"` and `depthWrite: false` (depth test stays on, so it hides
   behind opaques without occluding other translucents). The one inference:
@@ -675,7 +716,14 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   `shadow.normalBias` (world units along the receiver normal, the one to
   reach for first, ~0.02); the depth pass culls FRONT faces (Three's
   shadowSide default), so closed casters need little bias but a
-  single-sided plane casts nothing. Opting out of receiving is on the
+  back-culling plane casts only from its back. The shadow side follows
+  the material's `cull` (Three's shadowSide rule, Godot's shadow pass):
+  a `cull: "none"` foliage card or pane casts from both faces, and a
+  UV-mapped `alphaTest` material casts its cutout (leaves, not
+  rectangles), through the `Material.shadow` variant the standard
+  classes carry (a `shaderMaterial` gets the cull side from its `cull`
+  and supplies its own cutout variant as the `shadow` instance option).
+  Opting out of receiving is on the
   MATERIAL here (`receiveShadow: false`), not the object (Three's
   `mesh.receiveShadow`) - Godot's split, and URP's - and instanced
   meshes never cast (the depth override cannot know their records) - the
@@ -752,12 +800,13 @@ The follow-ups are filed in okf/backlog/3d-model-loader.md.
   vertex source - a comment counts - selects the "colored" layout, and
   the material then rejects standard geometry at add(). Do not mention
   aColor you do not read.
-- Picking is the VOLUME tier: a hit means the ray crossed the mesh's
-  transformed bounding box, not its surface. Never present `point` as a
-  surface point (it is the box-entry point), and never add a
-  triangle-accurate path in JS - per-triangle rays at mesh scale are
-  interpreter-hostile; that tier is core work (BVH descent per the
-  differentiators ladder).
+- Picking is triangle-accurate for ordinary meshes (`point` is a surface
+  point, hits carry `face`/`uv`/`normal`) but box-only for instanced
+  meshes: there `point` is the entry point of the population `bounds`
+  box, and `face`/`uv`/`normal` are absent. Never present an instanced
+  hit as a surface hit. Both tiers run in the spatial core (Rust); never
+  add a per-triangle path in JS - rays at mesh scale are
+  interpreter-hostile, and the core already does it.
 - `scene.handlers` vs `handlersFor`: localX/localY arrive in the leaf's
   LAYOUT frame (every ancestor transform and design-size fit is already
   undone by the element hit test). `handlers` therefore assumes leaf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.53",
+  "version": "0.0.54",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -19,6 +19,6 @@
   ],
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.3",
-    "@solidrt/core": "0.0.53"
+    "@solidrt/core": "0.0.54"
   }
 }

package/src/gltf.ts

@@ -30,11 +30,16 @@ export type ModelMaterial = {
   color: [number, number, number, number]
   /** Index into ModelData.images (the base color texture), or null. */
   map: number | null
-  /** glTF doubleSided. Reported, not applied: the standard materials cull
-   * back faces. */
+  /** glTF doubleSided; createModel's default material draws it with
+   * `cull: "none"`. */
   doubleSided: boolean
-  /** alphaMode BLEND. MASK draws opaque (no alpha test). */
+  /** alphaMode BLEND; createModel's default material blends it. */
   transparent: boolean
+  /** glTF alphaMode as written (default OPAQUE). MASK is a cutout:
+   * createModel's default material draws it with `alphaTest: alphaCutoff`. */
+  alphaMode: "OPAQUE" | "MASK" | "BLEND"
+  /** glTF alphaCutoff (default 0.5); meaningful for MASK only. */
+  alphaCutoff: number
 }
 
 /** One drawable: a mesh node's primitive, vertices in WORLD space. */
@@ -67,10 +72,21 @@ const CHUNK_JSON = 0x4e4f534a
 const CHUNK_BIN = 0x004e4942
 const MODE_TRIANGLES = 4
 
+// The spec's alphaCutoff when a MASK material leaves it out.
+const GLTF_ALPHA_CUTOFF = 0.5
+
 const COMPONENT_BYTES: Record<number, number> = { 5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4 }
 const TYPE_ELEMENTS: Record<string, number> = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 }
 
-const DEFAULT_MATERIAL: ModelMaterial = { name: "default", color: [1, 1, 1, 1], map: null, doubleSided: false, transparent: false }
+const DEFAULT_MATERIAL: ModelMaterial = {
+  name: "default",
+  color: [1, 1, 1, 1],
+  map: null,
+  doubleSided: false,
+  transparent: false,
+  alphaMode: "OPAQUE",
+  alphaCutoff: GLTF_ALPHA_CUTOFF,
+}
 
 /** True when the bytes are a .glb container (the "glTF" magic). */
 export function isGlb(bytes: Uint8Array): boolean {
@@ -171,6 +187,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       map,
       doubleSided: m.doubleSided === true,
       transparent: m.alphaMode === "BLEND",
+      alphaMode: m.alphaMode === "MASK" || m.alphaMode === "BLEND" ? m.alphaMode : "OPAQUE",
+      alphaCutoff: typeof m.alphaCutoff === "number" ? m.alphaCutoff : GLTF_ALPHA_CUTOFF,
     }
   })
   // Primitives without a material draw the spec's default; it is appended

package/src/material.ts

@@ -35,7 +35,6 @@ import type {
   ProgramId,
   RenderPipelineId,
   ShaderParams,
-  ShaderStageId,
   TextureBindings,
   TextureId,
   Topology,
@@ -73,18 +72,27 @@ export type Material = {
    * instanced meshes only - createInstancedMesh supplies the record buffer,
    * and createMesh meshes are rejected at add(). */
   instanceAttributes?: VertexAttribute[]
+  /** 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
+   * 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. */
+  shadow?: Material
   /** Present on materials that own their pipeline (shaderMaterial). */
   dispose?(): void
 }
 
-// One vertex stage serves every unlit class: 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.
-const VERTEX_SRC = glsl`
+// 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.
+const UNLIT_VERTEX = glsl`
   in vec3 aPos;
   in vec2 aUV;
   out vec2 vUv;
@@ -97,61 +105,28 @@ const VERTEX_SRC = glsl`
   }
 `
 
-const FRAGMENT_COLOR_SRC = glsl`
-  uniform vec4 uColor;
-  void main() {
-    fragColor = uColor;
-  }
-`
-
-const FRAGMENT_MAP_SRC = glsl`
-  in vec2 vUv;
-  uniform sampler2D uMap;
-  uniform vec4 uColor;
-  void main() {
-    fragColor = texture(uMap, vUv) * uColor;
-  }
-`
-
-let sharedVertex: ShaderStageId | undefined
-let programs: Partial<Record<UnlitClass, ProgramId>> = {}
-let pipelines = new Map<string, RenderPipelineId>()
-
-// One program per unlit CLASS: fragment kind x transparency. Blend state is
-// pipeline state and so is the attribute list, so the pipeline is keyed by
-// class and vertex layout.
-type UnlitClass = "color" | "map" | "color-transparent" | "map-transparent"
-
-function programFor(cls: UnlitClass): ProgramId {
-  let program = programs[cls]
-  if (program === undefined) {
-    if (sharedVertex === undefined) sharedVertex = compileShader("vertex", VERTEX_SRC, { header: true })
-    let fragment = compileShader("fragment", cls.startsWith("color") ? FRAGMENT_COLOR_SRC : FRAGMENT_MAP_SRC, {
-      header: true,
-    })
-    program = linkProgram(sharedVertex, fragment, { label: "scene-unlit-" + cls })
-    programs[cls] = program
-  }
-  return program
+// The unlit fragment (sprites share it): the color, times the map when
+// there is one, with the alphaTest discard when asked for. 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): string {
+  return glsl`
+    ${map ? "in vec2 vUv;" : ""}
+    ${map ? "uniform sampler2D uMap;" : ""}
+    uniform vec4 uColor;
+    ${alphaTest ? "uniform float uAlphaTest;" : ""}
+    void main() {
+      vec4 base = ${map ? "texture(uMap, vUv) * uColor" : "uColor"};
+      ${alphaTest ? "if (base.a < uAlphaTest) discard;" : ""}
+      fragColor = ${transparent ? "base" : "vec4(base.rgb, 1.0)"};
+    }
+  `
 }
 
-function pipelineFor(cls: UnlitClass, layout: VertexLayout | undefined): RenderPipelineId {
-  let key = cls + "|" + layoutKey(layout)
-  let existing = pipelines.get(key)
-  if (existing !== undefined) return existing
-  let program = programFor(cls)
-  let transparent = cls.endsWith("-transparent")
-  let pipeline = createRenderPipeline(program, {
-    attributes: layoutAttributes(layout),
-    depth: true,
-    depthWrite: transparent ? false : undefined,
-    blend: transparent ? "alpha" : undefined,
-    cull: "back",
-    label: "scene-unlit-" + cls,
-  })
-  pipelines.set(key, pipeline)
-  return pipeline
-}
+// 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>()
 
 export type UnlitOptions = {
   /** Straight [r, g, b] or [r, g, b, a], 0..1. Default white. */
@@ -161,6 +136,18 @@ export type UnlitOptions = {
   /** Blend over what is behind (color alpha and map alpha both count).
    * Without it an alpha below 1 still draws opaque. See Material.transparent. */
   transparent?: boolean
+  /** Which faces to drop; default "back". "none" draws both sides of
+   * single-layer geometry (foliage cards, glass, a mirrored part), and
+   * lit materials then light a back face with its normal flipped, as
+   * Three's DoubleSide and Godot's CULL_DISABLED do. */
+  cull?: CullMode
+  /** Cutout: drop a fragment whose final alpha (color x map, and for lit
+   * the vertex color too) is below this, 0..1 (Three's alphaTest, glTF
+   * alphaMode MASK with its alphaCutoff). Opaque otherwise:
+   * depth-written, not sorted, unlike `transparent`. Foliage cards and
+   * fences want it with `cull: "none"`; a mapped cutout casts its cutout
+   * (Material.shadow). */
+  alphaTest?: number
 }
 
 /**
@@ -172,15 +159,29 @@ 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 map = opts.map !== undefined
   let transparent = opts.transparent === true
-  let cls: UnlitClass = opts.map !== undefined ? (transparent ? "map-transparent" : "map") : transparent ? "color-transparent" : "color"
-  return {
-    pipeline: layout => pipelineFor(cls, layout),
-    attributes: () => programAttributes(programFor(cls)),
-    params: { uColor },
-    textures: opts.map !== undefined ? { uMap: opts.map } : undefined,
-    transparent,
+  let cull = opts.cull ?? "back"
+  let alphaTest = opts.alphaTest !== undefined
+  let key = [map, transparent, cull, alphaTest].join("|")
+  let cls = unlitClasses.get(key)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: UNLIT_VERTEX,
+      fragment: unlitFragment(map, alphaTest, transparent),
+      transparent,
+      cull,
+      label: "scene-unlit-" + key,
+    })
+    unlitClasses.set(key, cls)
   }
+  let params: ShaderParams = { uColor }
+  if (alphaTest) params.uAlphaTest = opts.alphaTest!
+  return cls.instance({
+    params,
+    textures: map ? { uMap: opts.map! } : undefined,
+    shadow: alphaTest && map ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
+  })
 }
 
 export type LitOptions = UnlitOptions & {
@@ -214,14 +215,37 @@ export type LitOptions = UnlitOptions & {
 
 // 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. Lights arrive through the scene's shared params
-// (light nodes); the base color, map and highlight are per entry. The
+// 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).
+// 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.
-function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, shadow: boolean): string {
+// 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.
+type LitClass = {
+  map: boolean
+  vertexColors: boolean
+  triplanar: boolean
+  transparent: boolean
+  shadow: boolean
+  cull: CullMode
+  alphaTest: boolean
+}
+
+function litClassKey(c: LitClass): string {
+  return Object.values(c).join("|")
+}
+
+function litFragment(c: LitClass): string {
+  let { map, vertexColors, triplanar, shadow, alphaTest } = c
+  let backFaces = c.cull !== "back"
   return glsl`
     in vec3 vWorldPos;
     in vec3 vNormal;
@@ -232,6 +256,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
     uniform float uSpecular;
     uniform float uShininess;
     ${triplanar ? "uniform float uTriplanar;" : ""}
+    ${alphaTest ? "uniform float uAlphaTest;" : ""}
     uniform vec3 uCamPos;
     uniform vec3 uHemiSky;
     uniform vec3 uHemiGround;
@@ -251,6 +276,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
 
     void main() {
       vec3 n = normalize(vNormal);
+      ${backFaces ? "if (!gl_FrontFacing) n = -n;" : ""}
       vec4 base = uColor;
       ${
         map
@@ -263,6 +289,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
           : ""
       }
       ${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);
@@ -275,7 +302,7 @@ function litFragment(map: boolean, vertexColors: boolean, triplanar: boolean, sh
         light += uLightColor[i] * lambert(n, l) * s;
         spec += uLightColor[i] * blinnSpecular(n, v, l, uShininess) * s;
       }
-      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, base.a);
+      fragColor = vec4(base.rgb * light + spec * uSpecular * base.a, ${c.transparent ? "base.a" : "1.0"});
     }
   `
 }
@@ -285,8 +312,8 @@ let litClasses = new Map<string, ShaderMaterialClass>()
 /**
  * A lit material: hemisphere ambient plus the scene's directional lights
  * (DirectionalLight nodes), Lambert diffuse, optional
- * Blinn-Phong highlight. Same options as unlit (color, map, transparent)
- * plus vertexColors, specular/shininess and triplanar mapping. One program
+ * Blinn-Phong highlight. Same options as unlit (color, map, transparent,
+ * cull, alphaTest) plus vertexColors, specular/shininess and triplanar mapping. One program
  * per option combination, one pipeline per vertex layout met, shared by
  * every instance - a thousand lit meshes still share one pipeline. No
  * lights set means black except for the hemisphere term, which also
@@ -297,26 +324,40 @@ export function lit(opts: LitOptions = {}): Material {
   let a = color.length === 4 ? color[3] : 1
   let uColor = [color[0] * a, color[1] * a, color[2] * a, a]
   let map = opts.map !== undefined
-  let vertexColors = opts.vertexColors === true
   let triplanar = map && opts.triplanar !== undefined
-  let transparent = opts.transparent === true
-  let shadow = opts.receiveShadow !== false
-  let key = [map, vertexColors, triplanar, transparent, shadow].join("|")
+  let alphaTest = opts.alphaTest !== undefined
+  let cull = opts.cull ?? "back"
+  let flags: LitClass = {
+    map,
+    vertexColors: opts.vertexColors === true,
+    triplanar,
+    transparent: opts.transparent === true,
+    shadow: opts.receiveShadow !== false,
+    cull,
+    alphaTest,
+  }
+  let key = litClassKey(flags)
   let cls = litClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
-      vertex: vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
-      fragment: litFragment(map, vertexColors, triplanar, shadow),
-      transparent,
+      vertex: flags.vertexColors ? LIT_VERTEX_COLORED : LIT_VERTEX,
+      fragment: litFragment(flags),
+      transparent: flags.transparent,
+      cull,
       label: "scene-lit-" + key,
     })
     litClasses.set(key, cls)
   }
+  let params: ShaderParams = { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 }
+  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
   let material = cls.instance({
-    params: triplanar
-      ? { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30, uTriplanar: opts.triplanar! }
-      : { uColor, uSpecular: opts.specular ?? 0, uShininess: opts.shininess ?? 30 },
+    params,
     textures: map ? { uMap: opts.map! } : undefined,
+    shadow: cutout ? shadowCutoutMaterial(shadowCull(cull), uColor, opts.alphaTest!, opts.map!) : undefined,
   })
   return material
 }
@@ -341,20 +382,79 @@ const SHADOW_DEPTH_FRAGMENT = glsl`
   }
 `
 
-let shadowDepth: Material | undefined
+let shadowDepth = new Map<CullMode, Material>()
 
 /** The override material of a scene's shadow view (internal): one class
- * for the app, built on first use. */
-export function shadowDepthMaterial(): Material {
-  if (shadowDepth === undefined) {
-    shadowDepth = shaderMaterialClass({
+ * 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)
+  if (material === undefined) {
+    material = shaderMaterialClass({
       vertex: SHADOW_DEPTH_VERTEX,
       fragment: SHADOW_DEPTH_FRAGMENT,
-      cull: "front",
-      label: "scene-shadow-depth",
+      cull,
+      label: "scene-shadow-depth-" + cull,
     }).instance()
+    shadowDepth.set(cull, material)
   }
-  return shadowDepth
+  return material
+}
+
+/** The shadow pass's cull for a material's cull: the opposite side
+ * (Three's shadowSide default), none stays none. */
+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))
+}
+
+// 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 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)
+  if (cls === undefined) {
+    cls = shaderMaterialClass({
+      vertex: SHADOW_CUTOUT_VERTEX,
+      fragment: SHADOW_CUTOUT_FRAGMENT,
+      cull,
+      label: "scene-shadow-cutout-" + cull,
+    })
+    shadowCutout.set(cull, cls)
+  }
+  return cls.instance({ params: { uColor, uAlphaTest }, textures: { uMap } })
 }
 
 export type SpriteOptions = UnlitOptions & {
@@ -436,7 +536,7 @@ export function sprite(opts: SpriteOptions = {}): Material {
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: map ? FRAGMENT_MAP_SRC : FRAGMENT_COLOR_SRC,
+      fragment: unlitFragment(map, false, transparent),
       transparent,
       cull: "none",
       label: "scene-sprite-" + key,
@@ -564,6 +664,10 @@ export type ShaderMaterialInstanceOptions = {
    * setMeshParams. */
   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. */
+  shadow?: Material
 }
 
 export type ShaderMaterialOptions = ShaderMaterialClassOptions & ShaderMaterialInstanceOptions
@@ -610,6 +714,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   let normalMatrix = /\buNormal\b/.test(opts.vertex) || /\buNormal\b/.test(opts.fragment)
   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
@@ -640,7 +745,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         // only applies when there is one.
         depthWrite: opts.depthWrite ?? (transparent && depth ? false : undefined),
         blend: opts.blend ?? (transparent ? "alpha" : undefined),
-        cull: opts.cull ?? "back",
+        cull,
         topology: opts.topology,
         label: opts.label,
       })
@@ -650,7 +755,20 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   }
   return {
     instance(inst = {}) {
-      return { normalMatrix, attributes, transparent, instanceAttributes, pipeline: pipelineFor, params: inst.params ?? {}, textures: inst.textures }
+      return {
+        normalMatrix,
+        attributes,
+        transparent,
+        instanceAttributes,
+        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)
+        },
+      }
     },
     dispose() {
       for (let pipeline of pipelines.values()) destroyRenderPipeline(pipeline)

package/src/model.ts

@@ -58,7 +58,13 @@ export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
       label: label ? label + "-image" + i : undefined,
     })
   })
-  let make = opts.material ?? ((m: ModelMaterial, map: TextureId | null): Material => lit({ color: m.color, map: map ?? undefined, transparent: m.transparent }))
+  let make = opts.material ?? ((m: ModelMaterial, map: TextureId | null): Material => lit({
+        color: m.color,
+        map: map ?? undefined,
+        transparent: m.transparent,
+        cull: m.doubleSided ? "none" : "back",
+        alphaTest: m.alphaMode === "MASK" ? m.alphaCutoff : undefined,
+      }))
   let materials = data.materials.map((m) => make(m, m.map === null ? null : textures[m.map]!))
 
   let model = createGroup() as Model

package/src/scene.ts

@@ -1537,7 +1537,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let inst = mesh._instances
     if (v.override !== null && inst !== null) return
     if (v.filter !== null && !v.filter(mesh)) return
-    let material = v.override ?? mesh.material
+    // A shadow view (the filtered kind) lets a caster's material pick its
+    // own depth variant (its cull side); any other override view draws
+    // exactly what it was given.
+    let material = v.override !== null ? (v.filter !== null ? (mesh.material.shadow ?? v.override) : v.override) : mesh.material
     let bufs = mesh._buffers!
     let entry = addDraw(v.texture, material.pipeline(mesh.geometry.layout), entrySeed(material, v.override !== null ? null : mesh._params), {
       buffer: bufs.buffer,