@solidrt/3d 0.0.60 → 0.0.61

package/src/input.ts

@@ -27,19 +27,35 @@ export type CameraDevices = {
   keyboard?: KeyboardDevice
 }
 
-/** The orbit control's actions: `rotate`, `zoom`, `pan`. */
-export let orbitActions = { rotate: "vec2", zoom: "axis", pan: "vec2" } as const
+/** The orbit control's actions: `rotate`, `zoom`, `pan`, `focus` (an
+ * axis: a bound double tap nudges it with the tap's focal). */
+export let orbitActions = { rotate: "vec2", zoom: "axis", pan: "vec2", focus: "axis" } as const
+
+// The device half orbit and map presets share: the right stick rotates,
+// the triggers zoom, the left stick pans; the arrows rotate and
+// minus/equals zoom.
+function orbitDeviceBindings(devices: CameraDevices, out: Binding[]): Binding[] {
+  let { gamepad, keyboard } = devices
+  if (gamepad) {
+    out.push({ action: "rotate", source: invert(gamepad.rightStick) }, { action: "zoom", source: gamepad.triggers }, { action: "pan", source: invert(gamepad.leftStick) })
+  }
+  if (keyboard) {
+    out.push({ action: "rotate", source: invert(keyboard.arrows) }, { action: "zoom", source: keyboard.axis("Minus", "Equal") })
+  }
+  return out
+}
 
 /**
  * The orbit camera's standard bindings: a drag rotates, a Ctrl-drag or a
  * right-drag pans (the desktop pans, Three's and Blender's; a chorded or
  * right-button drag feeds only `pan`, never `rotate`), a pinch and the
- * wheel zoom, two fingers pan; the right stick rotates, the triggers
- * zoom, the left stick pans; the arrow keys rotate and minus/equals zoom.
+ * wheel zoom, two fingers pan, a double tap focuses; the right stick
+ * rotates, the triggers zoom, the left stick pans; the arrow keys rotate
+ * and minus/equals zoom.
  */
 export function orbitBindings(devices: CameraDevices): Binding[] {
   let out: Binding[] = []
-  let { pointer, gamepad, keyboard } = devices
+  let { pointer } = devices
   if (pointer) {
     out.push(
       { action: "rotate", source: pointer.drag },
@@ -48,32 +64,60 @@ export function orbitBindings(devices: CameraDevices): Binding[] {
       { action: "pan", source: pointer.pan },
       { action: "zoom", source: pointer.pinch },
       { action: "zoom", source: pointer.wheel },
+      { action: "focus", source: pointer.doubleTap },
     )
   }
-  if (gamepad) {
-    out.push({ action: "rotate", source: invert(gamepad.rightStick) }, { action: "zoom", source: gamepad.triggers }, { action: "pan", source: invert(gamepad.leftStick) })
-  }
-  if (keyboard) {
-    out.push({ action: "rotate", source: invert(keyboard.arrows) }, { action: "zoom", source: keyboard.axis("Minus", "Equal") })
+  return orbitDeviceBindings(devices, out)
+}
+
+/**
+ * The map preset over the same orbit control (Three's MapControls): a
+ * drag PANS, a right-drag or a Ctrl-drag rotates, two fingers rotate, a
+ * pinch and the wheel zoom, a double tap focuses; the pad and keys as
+ * orbitBindings. Pair it with `panPlane: "ground"` on the control so a
+ * pan slides over the map, not across the view.
+ */
+export function mapBindings(devices: CameraDevices): Binding[] {
+  let out: Binding[] = []
+  let { pointer } = devices
+  if (pointer) {
+    out.push(
+      { action: "pan", source: pointer.drag },
+      { action: "rotate", source: pointer.drag("Ctrl") },
+      { action: "rotate", source: pointer.drag("Right") },
+      { action: "rotate", source: pointer.pan },
+      { action: "zoom", source: pointer.pinch },
+      { action: "zoom", source: pointer.wheel },
+      { action: "focus", source: pointer.doubleTap },
+    )
   }
-  return out
+  return orbitDeviceBindings(devices, out)
 }
 
-/** The first-person control's actions: `look`, `move`, `rise`. */
-export let firstPersonActions = { look: "vec2", move: "vec2", rise: "axis" } as const
+/** The first-person control's actions: `look`, `move`, `rise`, `boost`
+ * (an axis, so a button binding reads 1 while held - the control has
+ * no button kind). */
+export let firstPersonActions = { look: "vec2", move: "vec2", rise: "axis", boost: "axis" } as const
 
 /**
  * The first-person camera's standard bindings: a drag looks around and so
  * does mouse motion while the pointer is locked (the app locks it: see
  * examples/first-person.tsx); the right stick looks, the left stick
- * walks, the shoulders rise and sink in fly mode; WASD and the arrows
- * walk, Q/E rise and sink.
+ * walks, the shoulders rise and sink in fly mode, the left stick's press
+ * boosts (the usual pad sprint); WASD and the arrows walk, Q/E rise and
+ * sink, Shift boosts.
  */
 export function firstPersonBindings(devices: CameraDevices): Binding[] {
   let out: Binding[] = []
   let { pointer, gamepad, keyboard } = devices
   if (pointer) out.push({ action: "look", source: pointer.drag }, { action: "look", source: pointer.mouseDelta })
-  if (gamepad) out.push({ action: "look", source: gamepad.rightStick }, { action: "move", source: gamepad.leftStick }, { action: "rise", source: gamepad.shoulders })
-  if (keyboard) out.push({ action: "move", source: keyboard.wasd }, { action: "move", source: keyboard.arrows }, { action: "rise", source: keyboard.axis("KeyQ", "KeyE") })
+  if (gamepad) {
+    out.push({ action: "look", source: gamepad.rightStick }, { action: "move", source: gamepad.leftStick }, { action: "rise", source: gamepad.shoulders })
+    out.push({ action: "boost", source: gamepad.button("leftStick") })
+  }
+  if (keyboard) {
+    out.push({ action: "move", source: keyboard.wasd }, { action: "move", source: keyboard.arrows }, { action: "rise", source: keyboard.axis("KeyQ", "KeyE") })
+    out.push({ action: "boost", source: keyboard.key("ShiftLeft") }, { action: "boost", source: keyboard.key("ShiftRight") })
+  }
   return out
 }

package/src/light.ts

@@ -44,6 +44,14 @@ export type ShadowOptions = {
    * every cascade; it also bounds the maps' depth range, which is what
    * `bias` is measured against. A box light ignores it. */
   distance?: number | null
+  /** Where the cascades split: `cascades - 1` fractions of the
+   * near..distance range, strictly ascending in 0..1, each the far bound
+   * of one slice (Godot's shadow_split_1..3, Unity's cascade splits).
+   * Absent or null (the default) the practical split places them,
+   * halfway between uniform and logarithmic; give them to push
+   * resolution outward (a high viewpoint over distant detail) or pull it
+   * in (close quarters). A box light ignores it. */
+  splits?: number[] | null
 }
 
 /** A directional light node: parallel rays travelling along `direction`
@@ -66,7 +74,7 @@ export type DirectionalLight = SceneNode & {
    * `receiveShadow: false`). */
   castShadow: boolean
   /** The resolved shadow options (read; write through setLight). */
-  shadow: { mapSize: number; bias: number; normalBias: number; radius: number; camera: ShadowCamera; cascades: number; distance: number | null }
+  shadow: { mapSize: number; bias: number; normalBias: number; radius: number; camera: ShadowCamera; cascades: number; distance: number | null; splits: number[] | null }
 }
 
 /** A spot light node: a cone of light from the node's WORLD position
@@ -251,6 +259,21 @@ function mergeShadow(into: DirectionalLight["shadow"], update: ShadowOptions): v
     if (d !== null && !(d > 0)) throw new Error("shadow.distance must be a positive number or null")
     into.distance = d
   }
+  if (update.splits !== undefined) {
+    let s = update.splits
+    if (s !== null) {
+      if (!Array.isArray(s)) throw new Error("shadow.splits must be an array of fractions or null")
+      s.forEach((t, i) => {
+        if (!(t > 0 && t < 1)) throw new Error("shadow.splits[" + i + "] must be a fraction strictly between 0 and 1")
+        if (i > 0 && !(t > s[i - 1]!)) throw new Error("shadow.splits must be strictly ascending")
+      })
+    }
+    into.splits = s === null ? null : [...s]
+  }
+  // Checked after both merge: cascades and splits may arrive in one update.
+  if (into.splits !== null && into.splits.length !== into.cascades - 1) {
+    throw new Error("shadow.splits must hold cascades - 1 fractions (" + (into.cascades - 1) + " for " + into.cascades + " cascades), got " + into.splits.length)
+  }
 }
 
 export function createDirectionalLight(opts: DirectionalLightOptions = {}): DirectionalLight {
@@ -260,7 +283,7 @@ export function createDirectionalLight(opts: DirectionalLightOptions = {}): Dire
   light.color = [...(opts.color ?? [1, 1, 1])] as Vec3
   light.intensity = opts.intensity ?? 1
   light.castShadow = opts.castShadow === true
-  light.shadow = { mapSize: 1024, bias: 0, normalBias: 0, radius: 1, camera: { left: -5, right: 5, top: 5, bottom: -5, near: 0.5, far: 500 }, cascades: 1, distance: null }
+  light.shadow = { mapSize: 1024, bias: 0, normalBias: 0, radius: 1, camera: { left: -5, right: 5, top: 5, bottom: -5, near: 0.5, far: 500 }, cascades: 1, distance: null, splits: null }
   if (opts.shadow !== undefined) mergeShadow(light.shadow, opts.shadow)
   return light
 }

package/src/material.ts

@@ -86,10 +86,16 @@ export type Material = {
    * stride). */
   attributes(): VertexAttribute[]
   /** True when the pipeline blends over (its `blend`, "alpha" by default,
-   * with depthWrite off):
-   * the scene draws this material's meshes after every opaque one, sorted
-   * back-to-front by mesh origin, and re-sorts them when the camera moves. */
+   * with depthWrite off): the scene draws this material's meshes after
+   * every opaque and cutout one, sorted back-to-front by the center of
+   * their world bounds and re-sorted as the camera moves. */
   transparent?: boolean
+  /** True when the fragment discards (a stock material's `alphaTest`, a
+   * shaderMaterialClass told `cutout`): the scene draws this material's
+   * meshes in the cutout queue, after the solid opaques and front-to-back
+   * like them, so the solids fill the depth before the fragments that
+   * cannot early-z. */
+  cutout?: boolean
   /** The instance buffers, when the material's pipeline declares them
    * (shaderMaterialClass's `instanceBuffers`; the stock materials'
    * `instanced`), one layout per buffer after the geometry's. Such a
@@ -177,10 +183,10 @@ export type UnlitOptions = {
   cull?: CullMode
   /** Cutout: drop a fragment whose final alpha (color x map, and the
    * vertex color under vertexColors) 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). */
+   * alphaMode MASK with its alphaCutoff). Opaque otherwise: depth-written
+   * and drawn after the solid opaques (Material.cutout), never blended
+   * like `transparent`. Foliage cards and fences want it with `cull:
+   * "none"`; a mapped cutout casts its cutout (Material.shadow). */
   alphaTest?: number
   /** Take the scene's fog (default true, Three's `material.fog`): the
    * fragment fades toward the fog color with its distance from the
@@ -290,6 +296,7 @@ export function unlit(opts: UnlitOptions = {}): Material {
       instanceBuffers: stockInstanceBuffers(instanced, instanceColors),
       instanceStyle: instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
       transparent,
+      cutout: alphaTest,
       blend,
       cull,
       label: "scene-unlit-" + key,
@@ -369,6 +376,19 @@ export type LitOptions = UnlitOptions & {
    * scene's shadow set (see SHADOW's doc) and composing `shadow` per light.
    */
   receiveShadow?: boolean
+  /** GLSL at file scope for `surface`: uniforms (each an ordinary
+   * per-entry param, `params` on the mesh or setMeshParams) and helper
+   * functions. See the tier-2 look in AGENTS.md "Custom looks". */
+  prelude?: string
+  /** GLSL declaring `void surface(inout Surface s)`, called once the
+   * program has filled the Surface from the options (base from `color`,
+   * the map and the vertex color; the normal, bent by the normal map;
+   * emissive, the light model's fields) and before it shades: rewrite any
+   * field or `discard`. Runs in the shadow twin too, so what it discards
+   * casts no shadow (the twin sees a `prelude` uniform at its zero value:
+   * mesh params reach the main entry only). One program per distinct
+   * source, like every other option. */
+  surface?: string
 }
 
 /** `phong`'s options: the lit set plus the Blinn-Phong highlight and the
@@ -440,6 +460,9 @@ type LitClass = {
   instanced: boolean
   instanceColors: boolean
   morph: boolean
+  // The tier-2 sources, "" for none: a source string is a fine key part.
+  prelude: string
+  surface: string
 }
 
 function litClassKey(c: LitClass): string {
@@ -500,6 +523,8 @@ export function phong(opts: PhongOptions = {}): Material {
     instanced: opts.instanced === true || opts.instanceColors === true,
     instanceColors: opts.instanceColors === true,
     morph: opts.morph === true,
+    prelude: opts.prelude ?? "",
+    surface: opts.surface ?? "",
   }
   let key = litClassKey(flags)
   let cls = phongClasses.get(key)
@@ -511,6 +536,7 @@ export function phong(opts: PhongOptions = {}): Material {
       instanceBuffers: stockInstanceBuffers(flags.instanced, flags.instanceColors),
       instanceStyle: flags.instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
       transparent: flags.transparent,
+      cutout: flags.alphaTest,
       blend: flags.blend,
       cull,
       label: "scene-phong-" + key,
@@ -542,15 +568,16 @@ export function phong(opts: PhongOptions = {}): Material {
     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.
+  // source resolves the base exactly as the main one does), and a
+  // surface function casts its discards. 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,
     shadow:
-      alphaTest && map
-        ? litShadowMaterial(flags, uColor, opts.alphaTest!, opts.triplanar, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+      (alphaTest && map) || flags.surface !== ""
+        ? litShadowMaterial(flags, uColor, opts.alphaTest, opts.triplanar, opts.map, mapTransform ? params.uMapTransform as number[] : undefined)
         : undefined,
   })
   return material
@@ -609,6 +636,8 @@ function standardShadowFlags(c: StandardClass): LitClass {
     instanced: c.instanced,
     instanceColors: c.instanceColors,
     morph: c.morph,
+    prelude: c.prelude,
+    surface: c.surface,
   }
 }
 
@@ -673,6 +702,8 @@ export function standard(opts: StandardOptions = {}): Material {
     instanced: opts.instanced === true || opts.instanceColors === true,
     instanceColors: opts.instanceColors === true,
     morph: opts.morph === true,
+    prelude: opts.prelude ?? "",
+    surface: opts.surface ?? "",
     metalnessMap,
     roughnessMap,
   }
@@ -686,6 +717,7 @@ export function standard(opts: StandardOptions = {}): Material {
       instanceBuffers: stockInstanceBuffers(flags.instanced, flags.instanceColors),
       instanceStyle: flags.instanceColors ? INSTANCE_COLOR_DEFAULT : undefined,
       transparent: flags.transparent,
+      cutout: flags.alphaTest,
       blend: flags.blend,
       cull,
       label: "scene-standard-" + key,
@@ -716,8 +748,8 @@ export function standard(opts: StandardOptions = {}): Material {
     params,
     textures,
     shadow:
-      alphaTest && map
-        ? litShadowMaterial(standardShadowFlags(flags), uColor, opts.alphaTest!, opts.triplanar, opts.map!, mapTransform ? params.uMapTransform as number[] : undefined)
+      (alphaTest && map) || flags.surface !== ""
+        ? litShadowMaterial(standardShadowFlags(flags), uColor, opts.alphaTest, opts.triplanar, opts.map, mapTransform ? params.uMapTransform as number[] : undefined)
         : undefined,
   })
 }
@@ -733,9 +765,9 @@ let litShadowClasses = new Map<string, ShaderMaterialClass>()
 function litShadowMaterial(
   flags: LitClass,
   uColor: number[],
-  uAlphaTest: number,
+  uAlphaTest: number | undefined,
   triplanar: number | undefined,
-  uMap: TextureId,
+  uMap: TextureId | undefined,
   uMapTransform?: number[],
 ): Material {
   // A skinned cutout keeps its skinning (flags.skinned rides into the
@@ -755,14 +787,16 @@ function litShadowMaterial(
     })
     litShadowClasses.set(key, cls)
   }
-  let params: ShaderParams = { uColor, uAlphaTest }
+  let params: ShaderParams = { uColor }
+  if (flags.alphaTest) params.uAlphaTest = 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
+  let material = cls.instance({ params, textures: flags.map ? { uMap: uMap! } : undefined })
+  // Only triplanar sampling and a surface function read 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 && flags.surface === "") material.normalMatrix = false
   return material
 }
 
@@ -886,8 +920,31 @@ export type SpriteOptions = Omit<UnlitOptions, "instanced" | "instanceColors" |
    * follows the camera, the quad stays upright on world y - trees and
    * standing characters, the classic sprite. */
   billboard?: "full" | "fixed-y"
+  /** A procedural falloff over the quad, so a glow, flare or puff needs
+   * no texture: `"radial"` multiplies the base (color and alpha, the
+   * premultiplied rule) by `(1 - 2 * |uv - 0.5|)^falloff` clamped over
+   * the inscribed disc, composing with a `map` (the map's alpha times the
+   * disc). Absent, a mapless sprite is a hard square. */
+  shape?: "radial"
+  /** The radial falloff's exponent (default 1: linear to the rim; 2 a
+   * soft puff, 0.5 a hard-edged disc), the per-entry `uFalloff`. Needs
+   * `shape`. */
+  falloff?: number
 }
 
+// The radial shape as a tier-2 surface on the unlit fragment: the
+// vertex stages always write vUv, which the fragment declares only with
+// a map, so the mapless prelude declares it itself.
+const RADIAL_PRELUDE = glsl`
+  uniform float uFalloff;
+`
+const RADIAL_SURFACE = glsl`
+  void surface(inout Surface s) {
+    float disc = clamp(1.0 - 2.0 * length(vUv - 0.5), 0.0, 1.0);
+    s.base *= pow(disc, uFalloff);
+  }
+`
+
 // The billboard vertex stages: the unit quad's corners placed along the
 // camera axes at the mesh's world position, with the quad's size read
 // off uModel's column lengths so `scale` sizes the sprite like any mesh.
@@ -963,12 +1020,22 @@ export function sprite(opts: SpriteOptions = {}): Material {
   let transparent = opts.transparent !== false
   let fixedY = opts.billboard === "fixed-y"
   let fog = fogForm(opts.fog, blend)
-  let key = [map, transparent, blend, fixedY, fog].join("|")
+  let radial = opts.shape === "radial"
+  if (opts.shape !== undefined && !radial) throw new Error('sprite: shape must be "radial", got ' + opts.shape)
+  if (opts.falloff !== undefined && !radial) throw new Error("sprite: falloff needs shape")
+  if (opts.falloff !== undefined && !(Number.isFinite(opts.falloff) && opts.falloff > 0)) throw new Error("sprite: falloff must be a positive number, got " + opts.falloff)
+  let key = [map, transparent, blend, fixedY, fog, radial].join("|")
   let cls = spriteClasses.get(key)
   if (cls === undefined) {
     cls = shaderMaterialClass({
       vertex: fixedY ? SPRITE_FIXED_Y_VERTEX_SRC : SPRITE_VERTEX_SRC,
-      fragment: unlitFragment({ map, transparent, fog }),
+      fragment: unlitFragment({
+        map,
+        transparent,
+        fog,
+        prelude: radial ? (map ? "" : "in vec2 vUv;\n") + RADIAL_PRELUDE : undefined,
+        surface: radial ? RADIAL_SURFACE : undefined,
+      }),
       transparent,
       blend,
       cull: "none",
@@ -976,7 +1043,9 @@ export function sprite(opts: SpriteOptions = {}): Material {
     })
     spriteClasses.set(key, cls)
   }
-  return cls.instance({ params: { uColor }, textures: map ? { uMap: opts.map! } : undefined })
+  let params: ShaderParams = { uColor }
+  if (radial) params.uFalloff = opts.falloff ?? 1
+  return cls.instance({ params, textures: map ? { uMap: opts.map! } : undefined })
 }
 
 /** The attributes `material` reads that `layout` does not carry (name and
@@ -1173,6 +1242,11 @@ export type ShaderMaterialClassOptions = {
    * draw belongs after the opaques so it depth-tests against them, and
    * back-to-front is harmless for the order-independent modes. */
   transparent?: boolean
+  /** The fragment discards (an alpha test of its own): the scene draws
+   * this material's meshes in the cutout queue, after the solid opaques
+   * (see Material.cutout). Ignored on a transparent material, which sorts
+   * as one. */
+  cutout?: boolean
   /** Pipeline state; defaults match unlit: depth: true, cull: "back",
    * and for transparent materials blend "alpha", depthWrite: false. */
   depth?: boolean
@@ -1251,6 +1325,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
   // The LOD cross-fade is a fragment-stage discard (Material.lodFade).
   let lodFade = /\buLodFade\b/.test(opts.fragment)
   let transparent = opts.transparent ?? (opts.blend !== undefined && opts.blend !== "none")
+  let cutout = opts.cutout === true
   let depth = opts.depth ?? true
   let cull = opts.cull ?? "back"
   // An unknown format has no record stride: it would leave here intact,
@@ -1351,6 +1426,7 @@ export function shaderMaterialClass(opts: ShaderMaterialClassOptions): ShaderMat
         lodFade,
         attributes,
         transparent,
+        cutout,
         instanceBuffers,
         instanceStyle: opts.instanceStyle,
         pipeline: pipelineFor,

package/src/math.ts

@@ -775,6 +775,17 @@ export function cascadeSplit(near: number, far: number, index: number, count: nu
   return uniform + (log - uniform) * lambda
 }
 
+/**
+ * The far bound of cascade `index` of `count`: `splits` given (the
+ * light's explicit fractions of near..far, `count - 1` of them) places
+ * it at that fraction of the range, else cascadeSplit's `lambda` does.
+ * The last slice ends at `far` either way.
+ */
+export function cascadeBoundary(near: number, far: number, index: number, count: number, lambda: number, splits: number[] | null): number {
+  if (splits === null || index >= count - 1) return cascadeSplit(near, far, index, count, lambda)
+  return near + (far - near) * splits[index]!
+}
+
 /** The camera facts a frustum slice depends on: its view matrix (rows are
  * its right, up and back axes), eye, vertical fov in degrees and, for an
  * orthographic camera, the extents (fov ignored then). */

package/src/mesh.ts

@@ -10,9 +10,9 @@ import type { AttributeAccess, Geometry } from "./geometry.ts"
 import { INSTANCE_MATRIX_ATTRIBUTES } from "./glsl.ts"
 import type { GeometryBuffers } from "./geometry-gpu.ts"
 import type { Material } from "./material.ts"
-import type { TransformUpdate, Vec3 } from "./math.ts"
+import type { TransformUpdate } from "./math.ts"
 import * as spatial from "flux:spatial"
-import { activateMorph, afterFree, createWeightsTexture, enterScene, makeNode, rebindMorph, remove, resetMorph, setTransform } from "./node.ts"
+import { activateMorph, afterFree, createWeightsTexture, enterScene, leaveScene, makeNode, rebindMorph, remove, resetMorph, setTransform } from "./node.ts"
 import type { SceneNode } from "./node.ts"
 
 export type Mesh = SceneNode & {
@@ -50,16 +50,9 @@ export type Mesh = SceneNode & {
    * Set with setDrawRange; reset by setGeometry. */
   _range: { first: number; count: number } | null
   /** The geometry-buffer reference the entry was built from, acquired at
-   * attach and what _detach releases - like _transparent, a snapshot,
-   * because setGeometry swaps mesh.geometry before the rebuild. */
+   * attach and what _detach releases - a snapshot, because setGeometry
+   * swaps mesh.geometry before the rebuild. */
   _buffers: GeometryBuffers | null
-  /** material.transparent as of the last attach - the entry's actual
-   * pipeline state, and what _detach counts against (setMaterial swaps
-   * mesh.material before the rebuild). */
-  _transparent: boolean
-  /** World-space center of the local bounds, refreshed at sort time: the
-   * transparent sort key. */
-  _center: Vec3
   _params: ShaderParams | null
   /** Per-mesh sampler bindings merged over the material's at attach (a
    * skin's uBones palette texture): create-time state, set before the
@@ -118,6 +111,11 @@ export type MeshInstances = {
   /** The node-backed population (createInstancedMesh): handles by slot
    * (null = free) and the free list; null on a record mesh. */
   nodes: InstanceSlots | null
+  /** The node the instance records are relative to when it is not the
+   * mesh itself (InstancedMeshOptions.anchor): an ancestor the mesh sits
+   * under at identity, whose subtree the instances may live anywhere in.
+   * null on a plain population and on a record mesh. */
+  anchor: SceneNode | null
   /** The level meshes of an instanced LOD (createInstancedLod), nearest
    * first - the first is the population itself, the rest its children -
    * sharing this population's instance slots, each with a matrix buffer
@@ -221,8 +219,6 @@ export function createMesh(geometry: Geometry, material: Material): Mesh {
   mesh._entry = null
   mesh._range = null
   mesh._buffers = null
-  mesh._transparent = false
-  mesh._center = [0, 0, 0]
   mesh._params = null
   mesh._textures = null
   mesh._morphOwner = geometry.morphs === undefined ? null : mesh
@@ -388,10 +384,13 @@ function markRecords(mesh: Mesh, stream: InstanceStream, lo: number, hi: number)
 type PopulationOptions = {
   /** LOCAL bounds covering the population ([minX, minY, minZ, maxX, maxY,
    * maxZ] - geometryBounds' shape), copied in: the mesh node's own box,
-   * what the frustum test and the transparent sort use. Absent, an
-   * instanced mesh culls by the union of its live instances' boxes (the
-   * core follows them) and sorts by its node position; a record mesh is
-   * never culled. */
+   * what the frustum test and the transparent sort use. On an instanced
+   * mesh it is a cull box ONLY - the instances are what picks, never the
+   * mesh's box; on a record mesh (records opaque to picking) it is also
+   * the box the queries test, twelve triangles. Absent, an instanced
+   * mesh culls by the union of its live instances' boxes (the core
+   * follows them) and sorts by its node position; a record mesh is never
+   * culled and never picked. */
   bounds?: ArrayLike<number>
   /** Debug label for the record buffer. */
   label?: string
@@ -403,6 +402,20 @@ export type InstancedMeshOptions = PopulationOptions & {
    * in one call and republishes at the next flush - amortized like a
    * dynamic array; reserve realistically to skip the copies. */
   capacity?: number
+  /** The node the instance records are relative to (default: the mesh
+   * itself). Set it to an ANCESTOR the mesh sits under at identity and
+   * instances may be placed under any node of that ancestor's subtree,
+   * not only under the mesh - a population whose copies ride a hierarchy
+   * the mesh is not the root of (createModel's shared parts: the mesh
+   * hangs at identity under the model root, the anchor, and each
+   * placement node in the model's tree carries an instance). The core
+   * writes each record as the instance's world relative to the anchor,
+   * so the draw's `uModel * instanceMatrix()` places it correctly only
+   * while the mesh's world equals the anchor's: keep the chain between
+   * them identity. Checked at scene enter (the anchor must be an
+   * ancestor of the mesh, or add throws); the identity is the caller's
+   * contract, like an instanced LOD's levels. */
+  anchor?: SceneNode
 }
 
 /** A record mesh's bounds are also its ONLY picking leaf: records are
@@ -506,6 +519,7 @@ export function createInstancedMesh(geometry: Geometry, material: Material, opts
     count: 0,
     bounds: copyBounds(opts?.bounds, "createInstancedMesh"),
     nodes: { slots: [], free: [] },
+    anchor: opts?.anchor ?? null,
     levels: null,
     morph: populationMorph(geometry, capacity, opts?.label),
   }
@@ -642,7 +656,9 @@ export function publishRecords(mesh: Mesh): void {
  * (position/rotation/quaternion/scale; absent keys at their identity)
  * under `parent` - the mesh itself by default, or a node inside the
  * mesh's subtree (a squad group within a fleet: the record stays
- * mesh-relative through it). Its record slot is fixed for its life (a
+ * mesh-relative through it) - inside the ANCHOR's subtree when the mesh
+ * was created with one (see InstancedMeshOptions.anchor). Its record
+ * slot is fixed for its life (a
  * removed instance's slot recycles to the next add); past the
  * reservation the buffers double. From here on it is a node like any
  * other: setTransform/setTransition/setVisible, lookAt, worldPosition,
@@ -654,8 +670,11 @@ export function publishRecords(mesh: Mesh): void {
 export function addInstance(mesh: InstancedMesh, update?: TransformUpdate, parent: SceneNode = mesh): InstanceNode {
   let inst: (MeshInstances & { nodes: InstanceSlots }) | null = mesh._instances
   if (inst === null) throw new Error("addInstance: the mesh's instances are disposed")
-  for (let p: SceneNode | null = parent; p !== mesh; p = p.parent) {
-    if (p === null) throw new Error("addInstance: parent must be the mesh or a node inside its subtree")
+  let root: SceneNode = inst.anchor ?? mesh
+  for (let p: SceneNode | null = parent; p !== root; p = p.parent) {
+    if (p === null) {
+      throw new Error(inst.anchor === null ? "addInstance: parent must be the mesh or a node inside its subtree" : "addInstance: parent must be the mesh's anchor or a node inside its subtree")
+    }
   }
   let slot = inst.nodes.free.pop() ?? inst.nodes.slots.length
   // The levels of an instanced LOD grow, count and blank together: one
@@ -685,6 +704,33 @@ export function addInstance(mesh: InstancedMesh, update?: TransformUpdate, paren
   return instance
 }
 
+/**
+ * @internal Move a live instance under another node of its population's
+ * frame (the mesh, or the anchor's subtree): its slot and record are
+ * kept, its local pose is now read against the new parent, and in a
+ * scene it re-enters there so the core rebinds the record against the
+ * current anchor. The generic add/remove refuse instances (slot-bound);
+ * this is the one reparent, for bindSkeleton's grafts.
+ */
+export function reparentInstance(instance: InstanceNode, parent: SceneNode): void {
+  let mesh = instance.mesh
+  if (mesh === null || instance._destroyed) throw new Error("reparentInstance: the instance is gone")
+  if (parent._destroyed) throw new Error("reparentInstance: the parent was destroyed")
+  let root: SceneNode = mesh._instances?.anchor ?? mesh
+  for (let p: SceneNode | null = parent; p !== root; p = p.parent) {
+    if (p === null) throw new Error("reparentInstance: parent must be inside the population's anchor subtree")
+  }
+  if (instance._scene) leaveScene(instance)
+  let old = instance.parent
+  if (old !== null) {
+    let at = old.children.indexOf(instance)
+    if (at >= 0) old.children.splice(at, 1)
+  }
+  instance.parent = parent
+  parent.children.push(instance)
+  if (parent._scene) enterScene(instance, parent._scene)
+}
+
 // Grow the population's buffers to `next` records: replacements (never a
 // resize). An instanced mesh's live matrix records move to the new buffer
 // in one core call and republish at the next flush; every stream's mirror
@@ -749,6 +795,7 @@ export function createRecordMesh(
     count: Math.max(0, Math.min(Math.floor(count ?? capacity), capacity)),
     bounds: copyBounds(opts?.bounds, "createRecordMesh"),
     nodes: null,
+    anchor: null,
     levels: null,
     morph: null,
   }
@@ -842,7 +889,7 @@ export function disposeInstances(mesh: InstancedMesh | RecordMesh): void {
 export function setRenderOrder(mesh: Mesh, order: number): void {
   if (mesh.renderOrder === order) return
   mesh.renderOrder = order
-  mesh._scene?._reorder()
+  mesh._scene?._reorder(mesh)
 }
 
 /**