reze-engine 0.63.0 → 0.65.0

package/src/graph/compile.ts

@@ -344,9 +344,11 @@ export function compileGraph(graph: ShaderGraph, opts: CompileOptions = {}): Com
   }
 
   const lines: string[] = []
+  let nodeTakesLight = false
   for (const id of order) {
     const node = nodes.get(id)!
     const s = spec(node)
+    if (s.takesLight) nodeTakesLight = true
     if (s.contextOutputs) continue
     const args: Record<string, Resolved> = {}
     for (const [socket, input] of Object.entries(s.inputs)) args[socket] = resolveInput(node, socket, input.type)
@@ -360,7 +362,7 @@ export function compileGraph(graph: ShaderGraph, opts: CompileOptions = {}): Com
   const fsBody = lines.join("\n")
   // A graph takes light when its body reads any: the four shading nodes all
   // pass `sun, amb`, and a hand-written node reaching for the lamps names them.
-  const takesLight = /\bsun\b|\bamb\b|rzLight|rzLamp/.test(fsBody)
+  const takesLight = nodeTakesLight || /\bsun\b|\bamb\b|rzLight|rzLamp/.test(fsBody)
   const wgsl = assembleModule(opts.renderClass ?? "auto", opts.alphaMode ?? "opaque", fsBody, usesStyle.current, !!opacity, opts.blend ?? "over", takesLight)
   return { ok: true, wgsl, fsBody, slotMap, diagnostics, prunedNodes }
 }

package/src/graph/registry.ts

@@ -26,6 +26,9 @@ export type NodeSpec = {
   contextOutputs?: Record<string, string>
   /** Swizzle applied to the node's variable per output socket (default: none). */
   outputSelect?: Record<string, string>
+  /** The node shades by the scene's light without naming it: its graph takes
+   *  the lamps and the fog as the four shading nodes' graphs do. */
+  takesLight?: boolean
 }
 
 // ─── Literal formatting ───────────────────────────────────────────────
@@ -125,6 +128,54 @@ function foldSpecular(ior: string, level: string): string {
   return fmtFloat(Number(((r * r * 2 * Math.max(l, 0)) / 0.08).toPrecision(9)))
 }
 
+const uberNode = (slot: number): NodeSpec => ({
+  inputs: {
+    base: C([1, 1, 1], true),
+    metallic: F(0),
+    roughness: F(0.6),
+    occlusion: F(1),
+    normal: { type: "vector", contextDefault: "n" },
+    direction: { type: "vector", requiresLink: true },
+    // Unity's v into the ramp: the property map's alpha, which picks a
+    // surface's band (skin 0.702, hair and pale cloth 0.506).
+    row: F(0.702),
+    receive_shadow: F(1),
+    rim_mask: F(1),
+    rim_mid: F(0.448),
+    rim_width: F(0.11),
+    rim_tint: C([0.9623, 0.9214, 0.9214]),
+    rim_intensity: F(1),
+    rim_albedo: F(0.9),
+    rim_in_light: F(1),
+    emission: C([0, 0, 0]),
+    reflection: F(1),
+    // A face's SDF shade (ag_face_sdf); left at -1, the material reads N·L.
+    shade: F(-1),
+    // 1: the game's FACE_MODE — no GGX, the environment at a flat 0.0157.
+    face: F(0),
+  },
+  outputs: { color: "color" },
+  emit: (a) =>
+    `ag_uber(${slot}u, ${a.base}, ${a.metallic}, ${a.roughness}, ${a.occlusion}, ${a.normal}, ${a.direction}, ${a.row}, ${a.receive_shadow}, ` +
+    `${a.rim_mask}, ${a.rim_mid}, ${a.rim_width}, ${a.rim_tint}, ${a.rim_intensity}, ${a.rim_albedo}, ${a.rim_in_light}, ${a.emission}, ${a.reflection}, ${a.shade}, ${a.face}, input.worldPos, v)`,
+  takesLight: true,
+})
+const UBER_NODES: Record<string, NodeSpec> = Object.fromEntries([0, 1, 2, 3].map((s) => [`ag_uber/${s}`, uberNode(s)]))
+// The face's SDF shade, the image on the slot the type names — 104903's face
+// template (SDF_04_shaonv) by default in the AG pack.
+const faceSdfNode = (slot: number): NodeSpec => ({
+  inputs: {
+    uv: { type: "vector", contextDefault: "vec3f(input.uv, 0.0)" },
+    direction: { type: "vector", requiresLink: true },
+    normal: { type: "vector", contextDefault: "n" },
+    smoothness: F(0.1),
+    invert: F(0),
+  },
+  outputs: { value: "float" },
+  emit: (a) => `ag_face_sdf(${slot}u, ${a.uv}.xy, ${a.direction}, ${a.normal}, ${a.smoothness}, ${a.invert})`,
+})
+const FACE_SDF_NODES: Record<string, NodeSpec> = Object.fromEntries([0, 1, 2, 3].map((s) => [`ag_face_sdf/${s}`, faceSdfNode(s)]))
+
 export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // ── Context inputs (template locals; no emission) ──
   texture: {
@@ -454,6 +505,97 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     emit: (a) => `group_tex3(${a.uv}.xy)`,
   },
 
+  // ── Aether Gazer's character shading ──
+  // The game's character shader (SimPipeline/Character/Debug, which most of its
+  // characters wear), taken apart into the steps it runs — see ag_* in
+  // nodes.ts for each step's derivation from the decompiled pass. A graph
+  // composes them as the game did: a ramp lookup driven by the key light, a
+  // matcap, a reflection, the rim and the fill, with the ramp and matcap
+  // images on the style group's slots.
+
+  // The key light: CharacterEffect's direction, held in a frame that turns
+  // with the camera about the vertical (sim_TowardMatrix) — the game lights a
+  // character from where the viewer is, not from the scene's sun.
+  ag_key_light: {
+    inputs: { inclination: F(24), azimuth: F(-28) },
+    outputs: { direction: "vector" },
+    emit: (a) => `ag_key_light(${a.inclination}, ${a.azimuth})`,
+  },
+  // Where on the shadow ramp this point falls: N·L under the mask's occlusion,
+  // and the sun's cast shadow on top when the character receives it.
+  ag_shade_term: {
+    inputs: {
+      normal: { type: "vector", contextDefault: "n" },
+      direction: { type: "vector", requiresLink: true },
+      occlusion: F(1),
+      occlusion_scale: F(1),
+      receive_shadow: F(1),
+    },
+    outputs: { value: "float" },
+    emit: (a) => `ag_shade_term(${a.normal}, ${a.direction}, ${a.occlusion}, ${a.occlusion_scale}, ${a.receive_shadow}, input.worldPos)`,
+    takesLight: true,
+  },
+  // A ramp image's coordinate: u from the shade term, v the ramp's row (the
+  // game's property map picks it per texel; a PMX carries one per material).
+  ag_ramp_uv: {
+    inputs: { value: F(0), row: F(0.5) },
+    outputs: { uv: "vector" },
+    emit: (a) => `ag_ramp_uv(${a.value}, ${a.row})`,
+  },
+  // The view-space reflection the matcap, the reflection map, the rim and the
+  // fill all read: its uv into a sphere image, and how much it faces the eye.
+  ag_view_reflection: {
+    inputs: { normal: { type: "vector", contextDefault: "n" } },
+    outputs: { uv: "vector", facing: "float" },
+    outputSelect: { uv: ".xyz", facing: ".w" },
+    emit: (a) => `ag_view_reflection(${a.normal}, v)`,
+  },
+  // The matcap's lift: a metal's shine, at least 1, where the mask says.
+  ag_matcap: {
+    inputs: { color: C([1, 1, 1], true), matcap: C([1, 1, 1]), strength: F(1), mask: F(1) },
+    outputs: { color: "color" },
+    emit: (a) => `ag_matcap(${a.color}, ${a.matcap}, ${a.strength}, ${a.mask})`,
+  },
+  // The rim: the two fixed screen-side directions CharacterEffect sets, cut to
+  // the silhouette, laid on as a colour dodge where the mask allows.
+  ag_rim: {
+    inputs: {
+      color: C([1, 1, 1], true),
+      facing: F(1),
+      uv: { type: "vector", requiresLink: true },
+      rim_color: C([0.8584906, 0.8584906, 0.8584906]),
+      threshold: F(0.1),
+      fade: F(0.113),
+      range: F(0.444),
+      inclination: F(0),
+      azimuth1: F(0.8499963),
+      azimuth2: F(1),
+      mask: F(1),
+    },
+    outputs: { color: "color" },
+    emit: (a) =>
+      `ag_rim(${a.color}, ${a.facing}, ${a.uv}, ${a.rim_color}, ${a.threshold}, ${a.fade}, ${a.range}, ${a.inclination}, ${a.azimuth1}, ${a.azimuth2}, ${a.mask})`,
+  },
+  // The fill: a colour laid toward the silhouette, inner to outer.
+  ag_fill: {
+    inputs: {
+      color: C([1, 1, 1], true),
+      facing: F(1),
+      inner: C([0, 0, 0]),
+      outer: C([0, 0, 0]),
+      amount: F(0),
+      softness: F(0),
+    },
+    outputs: { color: "color" },
+    emit: (a) => `ag_fill(${a.color}, ${a.facing}, ${a.inner}, ${a.outer}, ${a.amount}, ${a.softness})`,
+  },
+
+  // Aether Gazer's current character shading (PBR/Uber) as one closure, the way
+  // Principled is one: the ramp image on the group slot named by the type.
+  // Defaults are 104903's skin.
+  ...UBER_NODES,
+  ...FACE_SDF_NODES,
+
   // ── Blender 5.2 colour utilities ──
   separate_color: {
     inputs: { color: C([1, 1, 1], true) },

package/src/graph/schema.ts

@@ -66,6 +66,15 @@ export type ShaderGraph = {
    *  matching (e.g. ["hair"]). Ignored by the compiler; round-tripped. A graph is pure
    *  shading — pass integration lives on the style group's renderClass, not here. */
   tags?: string[]
+  /**
+   * The images this look samples on `tex_image/0`…`tex_image/3`, by URL —
+   * a ramp, a matcap, the maps a game's look is built on. They belong to the
+   * LOOK, not to the model it is put on: they are read at coordinates the
+   * shading computes (a light amount, a reflection), never at the mesh's uvs,
+   * so one graph carries them to any model. A style group that brings its own
+   * images keeps those.
+   */
+  images?: ({ url: string; srgb?: boolean } | null)[]
 }
 
 export type Diagnostic = {

package/src/graph/slots.ts

@@ -137,20 +137,17 @@ ${discard}
   var n = safe_normal(input.normal);
   let v = normalize(camera.viewPos - input.worldPos);${flip}
 ${gate}
-  let l = -light.lights[0].direction.xyz;
-  let sun = select(light.lights[0].color.xyz * light.lights[0].color.w, modelLight.sun.rgb, modelLight.sun.w > 0.5);
+  // The key: the directional light this draw's layers take — the sun unless a
+  // light on its own layer stands in. The shadow stays the sun's atlas, as the
+  // game keeps the scene's shadow under a character's own key.
+  let rz_key = rzMainLight();
+  let l = -light.lights[rz_key].direction.xyz;
+  let sun = light.lights[rz_key].color.xyz * light.lights[rz_key].color.w;
   let shadow = sampleShadow(input.worldPos, n);
-  // The world: flat colour, or the HDRI's irradiance at this normal — which
-  // is what makes a loaded sky actually light her instead of only backing her.
-  // The model's fill is NOT here: see the epilogue.
-  //
-  // A model given a flat sky (setModelFlatSky - the cast, for an anime look)
-  // takes the sky's AVERAGE instead: its colour and brightness from every
-  // direction alike. The directional sky shaded a face like PBR - soft
-  // realistic gradients the toon ramp never drew - where the game gives its
-  // characters one flat base light. A flat World is its own average, so a
-  // scene without an HDRI renders exactly as before.
-  let amb = select(rzWorldAmbient(n), rzWorldAmbientAvg(), modelLight.opts.x > 0.5);
+  // The ambient: this object's own where loaded data gave it one — the game
+  // gives every renderer its own — else the world's flat colour or the HDRI's
+  // irradiance at this normal.
+  let amb = rzObjectAmbient(n);
   let tex_color = tex_s.rgb;
   // The normal the lamps' diffuse layer is lit by, for a principled walk to
   // compute it on the way (rzLightsDiffuseOnce). n is final from here on.
@@ -196,11 +193,11 @@ function epilogue(renderClass: RenderClass, alphaMode: AlphaMode, hasOpacity: bo
   // alpha, into a glowing disc under the spot above it.
   //
   // The model's fill (Engine.setModelFill) rides here too, as brightness: the
-  // surface colour times the fill, on every pixel of her alike. It used to
-  // enter the graph's ambient, where an NPR ramp read it as LIGHT — sliding it
-  // moved her shadows, and under a hard step flipped whole regions at once.
-  // After the graph it lifts her evenly and leaves every shadow where it is.
-  const LIT = takesLight ? ` + (rzLightsDiffuseOnce(input.worldPos, n) + modelLight.fill.rgb) * albedo` : ""
+  // surface colour times the fill, on every pixel of her alike. In the graph's
+  // ambient an NPR ramp would read it as LIGHT — sliding it would move her
+  // shadows, and under a hard step flip whole regions at once. After the graph
+  // it lifts her evenly and leaves every shadow where it is.
+  const LIT = takesLight ? ` + (rzLightsDiffuseOnce(input.worldPos, n) + objectLight.fill.rgb) * albedo` : ""
 
   const ALBEDO = `  let albedo = tex_color;
 `

package/src/index.ts

@@ -14,11 +14,14 @@ export {
   type BloomOptions,
   type DepthOfFieldOptions,
   type ViewTransformOptions,
+  type ViewTransformName,
   type LoadModelFromFilesOptions,
   type MaterialPreset,
   type MaterialPresetMap,
   type ModelTransform,
   type SceneLight,
+  RENDERING_LAYER_DEFAULT,
+  RENDERING_LAYER_CHARACTER,
   type ModelAttachment,
   type GizmoDragEvent,
   type GizmoDragCallback,
@@ -215,3 +218,12 @@ export {
  */
 export { EFFECT_MATH_API, PARTICLE_STRUCT_WGSL } from "./shaders/passes/hosted-api"
 export type { EyeTrackingOptions } from "./model"
+
+/**
+ * The game's own materials (src/unity): a stage package drawn by its translated
+ * shaders (Engine.setNativeStage) and a model dressed in a native look
+ * (Engine.setModelNativeLook) — the shapes their files take.
+ */
+export type { NativeStagePackage, NativeStageReader } from "./unity/stage"
+export type { NativeLook, NativeMaterialSpec, NativeTexture } from "./unity/looks"
+export type { NativeShader, NativeShaderInfo } from "./unity/host"

package/src/model.ts

@@ -3,6 +3,7 @@ import { Engine } from "./engine"
 import { joinAssetPath, type AssetReader } from "./asset-reader"
 import { Rigidbody, Joint } from "./physics"
 import { IKSolverSystem } from "./ik-solver"
+import { buildOutlineVertices } from "./outline-normals"
 import { VMDLoader, type VMDKeyFrame } from "./vmd-loader"
 import { VMDWriter, type VmdTrackSelection } from "./vmd-writer"
 import {
@@ -564,8 +565,10 @@ export class Model {
     morphing: Morphing,
     rigidbodies: Rigidbody[] = [],
     joints: Joint[] = [],
-    loadWarnings: string[] = []
+    loadWarnings: string[] = [],
+    edgeScales: Float32Array | null = null
   ) {
+    this.edgeScales = edgeScales
     // Store base vertex data (original positions before morphing)
     this.baseVertexData = new Float32Array(vertexData)
     this.vertexData = vertexData
@@ -1001,6 +1004,20 @@ export class Model {
     return this.vertexData
   }
 
+  /** PMX per-vertex edge scale, when the source had one. */
+  private edgeScales: Float32Array | null = null
+  private outlineVertices: Float32Array<ArrayBuffer> | null = null
+
+  /**
+   * The outline hull's own vertex stream: per vertex, the smoothed rest-pose
+   * normal (xyz) and the PMX edge scale (w). See outline-normals.ts. Built on
+   * first ask — only models with an edge-flagged material ever ask.
+   */
+  getOutlineVertices(): Float32Array<ArrayBuffer> {
+    this.outlineVertices ??= buildOutlineVertices(this.baseVertexData, VERTEX_STRIDE, this.indexData, this.edgeScales ?? undefined)
+    return this.outlineVertices
+  }
+
   getTextures(): Texture[] {
     return this.textures
   }

package/src/outline-normals.ts

@@ -0,0 +1,110 @@
+// The inverted hull's own push direction, one per vertex, built once at load.
+//
+// The hull is the model pushed out along a normal. Pushed along the MESH's
+// normals it tears wherever the mesh carries two vertices at one position —
+// every hard edge and every UV seam — because the two copies go two ways and
+// the gap between them shows the body through the line: the jaw, the finger
+// joints, the parting in the hair. Aether Gazer bakes a smoothed normal into
+// vertex colour for exactly this (Character/Debug.shader, pass "Outline"); a
+// PMX has nowhere to carry one, so it is computed here instead: the normals of
+// every vertex at one position, averaged, so the copies agree and the hull
+// stays closed.
+//
+// Each vertex's vote is weighted by the corner angles it owns, which is what
+// makes a hard corner come out as the corner's true bisector rather than
+// leaning toward whichever side happened to be cut into more triangles.
+//
+// Rest pose only, as the game's is: a morph moves the positions and leaves this
+// alone, and skinning turns it exactly as it turns the normal.
+
+/** Positions closer than this (model units) are one position. */
+export const OUTLINE_WELD_EPSILON = 1e-4
+
+/**
+ * Smoothed outline normals, packed with the PMX per-vertex edge scale:
+ * xyz = unit direction, w = edge scale — four floats per vertex.
+ *
+ * @param vertexData interleaved [pos3, normal3, uv2] per vertex
+ * @param indices    triangle list
+ * @param edgeScales per-vertex PMX edge scale, or omitted for 1
+ */
+export function buildOutlineVertices(
+  vertexData: ArrayLike<number>,
+  stride: number,
+  indices: ArrayLike<number>,
+  edgeScales?: ArrayLike<number>,
+): Float32Array<ArrayBuffer> {
+  const n = Math.floor(vertexData.length / stride)
+  const out = new Float32Array(n * 4)
+
+  // Corner angles each vertex owns. A vertex no triangle uses keeps a token
+  // weight, so it still has a direction of its own.
+  const weight = new Float32Array(n).fill(1e-6)
+  for (let t = 0; t + 2 < indices.length; t += 3) {
+    const a = indices[t], b = indices[t + 1], c = indices[t + 2]
+    if (a >= n || b >= n || c >= n) continue
+    weight[a] += cornerAngle(vertexData, stride, a, b, c)
+    weight[b] += cornerAngle(vertexData, stride, b, c, a)
+    weight[c] += cornerAngle(vertexData, stride, c, a, b)
+  }
+
+  // Weld by quantized position.
+  const inv = 1 / OUTLINE_WELD_EPSILON
+  const group = new Int32Array(n)
+  const ids = new Map<string, number>()
+  let groups = 0
+  for (let i = 0; i < n; i++) {
+    const o = i * stride
+    const key = `${Math.round(vertexData[o] * inv)},${Math.round(vertexData[o + 1] * inv)},${Math.round(vertexData[o + 2] * inv)}`
+    let g = ids.get(key)
+    if (g === undefined) {
+      g = groups++
+      ids.set(key, g)
+    }
+    group[i] = g
+  }
+
+  const sum = new Float32Array(groups * 3)
+  for (let i = 0; i < n; i++) {
+    const o = i * stride
+    const w = weight[i]
+    const g = group[i] * 3
+    sum[g] += vertexData[o + 3] * w
+    sum[g + 1] += vertexData[o + 4] * w
+    sum[g + 2] += vertexData[o + 5] * w
+  }
+
+  for (let i = 0; i < n; i++) {
+    const o = i * stride
+    const nx = vertexData[o + 3], ny = vertexData[o + 4], nz = vertexData[o + 5]
+    const g = group[i] * 3
+    let x = sum[g], y = sum[g + 1], z = sum[g + 2]
+    const len = Math.hypot(x, y, z)
+    // Two sheets back to back at one position (a double-sided skirt, a shell
+    // and its lining) cancel to nothing, or to a direction pointing INTO one of
+    // them. Either way the welded answer is wrong for this vertex, and its own
+    // normal is the honest one.
+    if (len < 1e-6 || x * nx + y * ny + z * nz <= 0) {
+      x = nx
+      y = ny
+      z = nz
+    }
+    const l = Math.hypot(x, y, z) || 1
+    out[i * 4] = x / l
+    out[i * 4 + 1] = y / l
+    out[i * 4 + 2] = z / l
+    out[i * 4 + 3] = edgeScales ? edgeScales[i] : 1
+  }
+  return out
+}
+
+/** The angle at vertex `a` of triangle (a, b, c), in radians. */
+function cornerAngle(v: ArrayLike<number>, stride: number, a: number, b: number, c: number): number {
+  const oa = a * stride, ob = b * stride, oc = c * stride
+  const ux = v[ob] - v[oa], uy = v[ob + 1] - v[oa + 1], uz = v[ob + 2] - v[oa + 2]
+  const wx = v[oc] - v[oa], wy = v[oc + 1] - v[oa + 1], wz = v[oc + 2] - v[oa + 2]
+  const lu = Math.hypot(ux, uy, uz), lw = Math.hypot(wx, wy, wz)
+  if (lu < 1e-12 || lw < 1e-12) return 0
+  const cos = (ux * wx + uy * wy + uz * wz) / (lu * lw)
+  return Math.acos(Math.max(-1, Math.min(1, cos)))
+}

package/src/pmx-loader.ts

@@ -36,6 +36,9 @@ export class PmxLoader {
   private inverseBindMatrices: Float32Array | null = null
   private joints0: Uint16Array | null = null
   private weights0: Uint8Array | null = null
+  /** PMX per-vertex edge scale — the outline's width multiplier, as the
+   *  game's outline takes vertex colour alpha. */
+  private edgeScales: Float32Array | null = null
   private morphs: Morph[] = []
   private vertexCount: number = 0
   private rigidbodies: Rigidbody[] = []
@@ -150,6 +153,7 @@ export class PmxLoader {
     // Prepare skinning arrays (4 influences per vertex)
     const joints = new Uint16Array(count * 4)
     const weights = new Uint8Array(count * 4) // UNORM8, will be normalized to 255
+    const edgeScales = new Float32Array(count)
 
     for (let i = 0; i < count; i++) {
       const px = this.getFloat32()
@@ -238,11 +242,12 @@ export class PmxLoader {
       } else {
         throw new Error(`Invalid bone weight type: ${type}`)
       }
-      this.offset += 4 // edge scale
+      edgeScales[i] = this.getFloat32()
     }
 
     this.joints0 = joints
     this.weights0 = weights
+    this.edgeScales = edgeScales
     return { positions, normals, uvs }
   }
 
@@ -1136,7 +1141,8 @@ export class PmxLoader {
       morphing,
       this.rigidbodies,
       this.joints,
-      this.warnings
+      this.warnings,
+      this.edgeScales
     )
   }
 

package/src/shaders/lights.ts

@@ -28,7 +28,8 @@ import { subjectMaskApi } from "./cast-api"
 //   [0..2] position, world space               [3] radius
 //   [4..6] colour PREMULTIPLIED by intensity   [7] type
 //   [8..10] aim, unit, pointing away from the light   [11] cos of the outer angle
-//   [12] cos of the inner angle                [13..15] spare
+//   [12] cos of the inner angle
+//   [13] the rendering layers it does NOT reach (u32 bits)   [14..15] spare
 //
 // then the grid: LIGHT_MASK_WORDS words of lamp bits per cell.
 //
@@ -40,6 +41,12 @@ import { subjectMaskApi } from "./cast-api"
 // branchless: it stores aim (0,0,0) and both cosines at -1, which makes the
 // cone term below saturate to exactly 1. `type` says which a light is for
 // anyone reading the buffer; the shading never asks.
+//
+// LAYERS, as the game's pipeline (URP's rendering layers) gates its lights: a
+// draw carries layer bits, and a light reaches it only where its own mask
+// shares one. Stored INVERTED — the layers a light does not reach — so the
+// zero every writer that predates layers leaves in [13] reaches everything,
+// which is what an effect's lamp and a plain document light mean.
 
 import { castDistanceStub } from "./passes/cast-distance"
 import { audioApi } from "./audio-api"
@@ -243,8 +250,9 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
 `
 }
 
-/** The rz*Light accessors, with the buffer declared at the given binding. */
-export function lightsApi(group: number, binding: number): string {
+/** The rz*Light accessors, with the buffer declared at the given binding.
+ *  `layers` is the WGSL expression for the drawing's rendering-layer bits. */
+export function lightsApi(group: number, binding: number, layers: string): string {
   const R = LIGHT_HEADER / 4
   const S = LIGHT_STRIDE / 4
   return /* wgsl */ `
@@ -286,6 +294,10 @@ fn rzLightAim(i: u32) -> vec3f { return _rzLightVec(i, 2u).xyz; }
  *  light stores (-1, -1), which saturates the cone term to 1. */
 fn rzLightCone(i: u32) -> vec2f { return vec2f(_rzLightVec(i, 2u).w, _rzLightVec(i, 3u).x); }
 
+/** Does light i reach this drawing's rendering layers? Read as bits, never as
+ *  a float — see the layout. */
+fn _rzLightReaches(i: u32) -> bool { return ((${layers}) & ~_rzLights[${R}u + i * ${S}u + 3u].y) != 0u; }
+
 /** The document lamps that can reach p: its grid cell's bits, or the outside
  *  mask beyond the grid. Written so a NaN position fails the inside test. */
 fn _rzLightCellMask(p: vec3f) -> vec4u {
@@ -312,6 +324,7 @@ fn _rzLightCellMask(p: vec3f) -> vec4u {
  * writes in candela over 683.
  */
 fn _rzLightOne(i: u32, p: vec3f, n: vec3f) -> vec3f {
+  if (!_rzLightReaches(i)) { return vec3f(0.0); }
   let pr = _rzLightVec(i, 0u);
   let d = pr.xyz - p;
   let dist = length(d);