phoria2 1.3.0 → 1.4.1

package/src/debug.js

@@ -0,0 +1,283 @@
+// view.debug: pictures for a person checking a scene - each light and the way it shines, the shadow
+// cameras, bounding boxes, normals, the axes, the orbit target - and a corner readout of what a frame
+// costs. view.explain() is the text an agent reads; this is what a person looks at. Loaded only when
+// debug is turned on. The helpers are drawn by the View after the scene, not added to it, so they
+// are never picked, saved, framed or counted: lines in the scene's depth, and faintly through
+// whatever is in front of them, so a light inside a lamp can still be found.
+import { collect } from './frame.js'
+import { Geometry } from './geometry/Geometry.js'
+import { Lines } from './scene/drawables.js'
+import { Scene } from './scene/Scene.js'
+import { Box3 } from './value/Box3.js'
+import { Mat4 } from './value/Mat4.js'
+import { Vec3 } from './value/Vec3.js'
+
+/** @import { DrawItem, FrameDescription } from './frame.js' */
+/** @import { Hit } from './Raycaster.js' */
+/** @import { Camera } from './scene/cameras.js' */
+
+/**
+ * What debug draws. `true` for a helper shows it for everything; `'hovered'` (bounds and normals) only
+ * for what is under the pointer.
+ * @typedef {object} DebugOptions
+ * @property {boolean} [lights] each light: an arrow for directional ones, a small sphere and its range
+ *   for point lights, a cone for spot lights - in the light's colour
+ * @property {boolean} [shadows] the box or cone each shadow is drawn from - the usual reason a shadow
+ *   is cut off or soft
+ * @property {boolean | 'hovered'} [bounds] world bounding boxes - what culling and view.frame() see
+ * @property {boolean | 'hovered'} [normals] short lines along vertex normals (meshes up to 5,000
+ *   vertices each when all are shown)
+ * @property {boolean} [axes] x, y and z at the origin, red, green and blue
+ * @property {boolean} [camera] the point the camera orbits round
+ * @property {boolean | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'} [stats] a readout of
+ *   frame time, draw calls, triangles, programs, textures and geometries, in a corner of the canvas
+ */
+
+const COLORS = { shadow: [1, 0.8, 0], bounds: [0, 0.9, 1], normal: [1, 0.31, 0.85], camera: [1, 1, 1] }
+// normals, when shown for everything: past these a model would be a hedgehog
+const NORMALS_PER_MESH = 5000, NORMALS_IN_ALL = 40000
+
+export class DebugDraw {
+  #scene = new Scene()
+  #geometry = new Geometry({ positions: [0, 0, 0, 0, 0, 0] })
+  // the same lines twice: in the scene's depth, and faintly through what is in front of them
+  #solid = /** @type {Lines} */ (this.#scene.add(new Lines({ geometry: this.#geometry, pickable: false, frustumCulled: false,
+    material: { vertexColors: true, width: 1.5, fog: false } })))
+  #faint = /** @type {Lines} */ (this.#scene.add(new Lines({ geometry: this.#geometry, pickable: false, frustumCulled: false, renderOrder: 1e9,
+    material: { vertexColors: true, width: 1, opacity: 0.22, depthTest: false, depthWrite: false, fog: false } })))
+  /** @type {HTMLDivElement | null} */ #stats = null
+  #statsAt = 0
+  /** @type {number[]} */ #positions = []
+  /** @type {number[]} */ #colors = []
+
+  /** @param {HTMLElement | null} overlay where the stats readout goes - the layer over the canvas */
+  constructor(overlay) {
+    this.overlay = overlay
+  }
+
+  /**
+   * Add the helpers to a frame about to be drawn, after everything in it. Returns how many items were
+   * added to each list, to take out again once it is drawn.
+   * @param {FrameDescription} frame @param {DebugOptions} o
+   * @param {{ camera: Camera, hovered: Hit | null, bounds: Box3 }} at
+   * @returns {{ opaque: number, transparent: number }}
+   */
+  add(frame, o, at) {
+    this.#positions = []
+    this.#colors = []
+    const items = [...frame.opaque, ...frame.transparent]
+    const size = at.bounds.isEmpty() ? 1 : Math.max(at.bounds.getRadius(), 1e-3)
+    const middle = at.bounds.isEmpty() ? new Vec3() : at.bounds.getCenter()
+    if (o.lights) this.#lights(frame, size, middle)
+    if (o.shadows) this.#shadows(frame)
+    if (o.bounds) this.#bounds(items, o.bounds === 'hovered' ? at.hovered : null, o.bounds === 'hovered')
+    if (o.normals) this.#normals(items, o.normals === 'hovered' ? at.hovered : null, o.normals === 'hovered', size * 0.025)
+    if (o.axes) {
+      this.#segment([0, 0, 0], [size * 0.5, 0, 0], [1, 0.2, 0.2])
+      this.#segment([0, 0, 0], [0, size * 0.5, 0], [0.3, 1, 0.3])
+      this.#segment([0, 0, 0], [0, 0, size * 0.5], [0.3, 0.5, 1])
+    }
+    const target = /** @type {any} */ (at.camera).target
+    if (o.camera && target) this.#cross(target, size * 0.04, COLORS.camera)
+    if (!this.#positions.length) return { opaque: 0, transparent: 0 }
+
+    // one buffer for all of it, made again only when it changes length
+    const n = this.#positions.length
+    const colors = this.#geometry.colors
+    if (this.#geometry.positions.length === n && colors) {
+      this.#geometry.positions.set(this.#positions)
+      colors.set(this.#colors)
+      this.#geometry.needsUpdate()
+    } else {
+      this.#geometry.dispose()
+      this.#geometry = new Geometry({ positions: this.#positions, colors: this.#colors })
+      this.#solid.geometry = this.#faint.geometry = this.#geometry
+    }
+    this.#scene.updateWorldTree()
+    const drawn = collect(this.#scene, at.camera)
+    frame.opaque.push(...drawn.opaque)
+    frame.transparent.push(...drawn.transparent)
+    return { opaque: drawn.opaque.length, transparent: drawn.transparent.length }
+  }
+
+  /**
+   * The corner readout, refreshed a few times a second.
+   * @param {DebugOptions['stats']} where
+   * @param {{ drawCalls: number, triangles: number, programs: number, textures: number, geometries: number, compiling: number }} info
+   * @param {number} frameMs time between drawn frames @param {number} cpuMs time the last frame took to draw
+   */
+  stats(where, info, frameMs, cpuMs) {
+    if (!where || !this.overlay || typeof document === 'undefined') {
+      this.#stats?.remove()
+      this.#stats = null
+      return
+    }
+    const corner = where === true ? 'top-left' : where
+    if (!this.#stats) {
+      this.#stats = document.createElement('div')
+      this.#stats.className = 'phoria-debug-stats'
+      Object.assign(this.#stats.style, { position: 'absolute', zIndex: '3', pointerEvents: 'none', padding: '6px 8px', borderRadius: '6px',
+        background: 'rgba(10, 12, 16, 0.72)', color: '#e8ecf2', font: '11px/1.45 ui-monospace, SFMono-Regular, Consolas, monospace', whiteSpace: 'pre' })
+      this.overlay.append(this.#stats)
+    }
+    const [v, h] = corner.split('-')
+    Object.assign(this.#stats.style, { top: v === 'top' ? '8px' : '', bottom: v === 'bottom' ? '8px' : '', left: h === 'left' ? '8px' : '', right: h === 'right' ? '8px' : '' })
+    const now = performance.now()
+    if (now - this.#statsAt < 250) return
+    this.#statsAt = now
+    const k = (x) => (x >= 1e6 ? `${(x / 1e6).toFixed(1)}M` : x >= 1e4 ? `${Math.round(x / 1e3)}k` : String(x))
+    const fps = frameMs > 0 ? Math.round(1000 / frameMs) : 0
+    this.#stats.textContent = [
+      `${fps ? `${fps} fps  ${frameMs.toFixed(1)} ms` : 'idle'}  cpu ${cpuMs.toFixed(1)} ms`,
+      `${info.drawCalls} draws  ${k(info.triangles)} triangles`,
+      `${info.programs} programs${info.compiling ? ` (${info.compiling} compiling)` : ''}  ${info.textures} textures  ${info.geometries} geometries`,
+    ].join('\n')
+  }
+
+  dispose() {
+    this.#stats?.remove()
+    this.#stats = null
+    this.#geometry.dispose()
+  }
+
+  // ---- the helpers, as line segments in world space, colours sRGB
+
+  /** @param {ArrayLike<number>} a @param {ArrayLike<number>} b @param {ArrayLike<number>} c */
+  #segment(a, b, c) {
+    this.#positions.push(a[0], a[1], a[2], b[0], b[1], b[2])
+    this.#colors.push(c[0], c[1], c[2], c[0], c[1], c[2])
+  }
+
+  /** @param {ArrayLike<number>} p @param {number} r @param {ArrayLike<number>} c */
+  #cross(p, r, c) {
+    for (let k = 0; k < 3; k++) {
+      const a = [p[0], p[1], p[2]], b = [p[0], p[1], p[2]]
+      a[k] -= r
+      b[k] += r
+      this.#segment(a, b, c)
+    }
+  }
+
+  /** A circle round a centre, in the plane of two unit axes. @param {Vec3} centre @param {Vec3} u @param {Vec3} v @param {number} r @param {ArrayLike<number>} c */
+  #circle(centre, u, v, r, c, segments = 32) {
+    const at = (i) => {
+      const a = i / segments * Math.PI * 2, x = Math.cos(a) * r, y = Math.sin(a) * r
+      return [centre[0] + u[0] * x + v[0] * y, centre[1] + u[1] * x + v[1] * y, centre[2] + u[2] * x + v[2] * y]
+    }
+    for (let i = 0; i < segments; i++) this.#segment(at(i), at(i + 1), c)
+  }
+
+  /** The twelve edges of a box. @param {Box3} box @param {ArrayLike<number>} c */
+  #box(box, c) {
+    const { min: a, max: b } = box
+    const corner = (i) => [i & 1 ? b[0] : a[0], i & 2 ? b[1] : a[1], i & 4 ? b[2] : a[2]]
+    for (const [i, j] of EDGES) this.#segment(corner(i), corner(j), c)
+  }
+
+  /** The edges of what a view-projection matrix sees: a box for an orthographic one, a frustum for a perspective one. @param {ArrayLike<number>} viewProjection @param {ArrayLike<number>} c */
+  #frustum(viewProjection, c) {
+    const inverse = new Mat4().copy(viewProjection).invert()
+    const corner = (i) => new Vec3(i & 1 ? 1 : -1, i & 2 ? 1 : -1, i & 4 ? 1 : -1).applyMatrix4(inverse)
+    for (const [i, j] of EDGES) this.#segment(corner(i), corner(j), c)
+  }
+
+  /** @param {FrameDescription} frame @param {number} size @param {Vec3} middle */
+  #lights(frame, size, middle) {
+    for (const l of frame.lights) {
+      const c = l.color.toSRGB().map((x) => Math.min(1, x))
+      if (l.kind === 'directional' && l.direction) {
+        // an arrow coming in over the scene's middle, the way the light travels
+        const d = new Vec3().copy(l.direction).normalize()
+        const from = moved(middle, d, -size * 1.1), to = moved(middle, d, -size * 0.45)
+        this.#segment(from, to, c)
+        const [u, v] = across(d)
+        for (const s of [u, v, u.clone().negate(), v.clone().negate()]) {
+          this.#segment(to, moved(moved(to, d, -size * 0.08), s, size * 0.04), c)
+        }
+      } else if (l.kind === 'point' && l.position) {
+        const p = new Vec3().copy(l.position), r = size * 0.06
+        this.#circle(p, X, Y, r, c, 16)
+        this.#circle(p, X, Z, r, c, 16)
+        this.#circle(p, Y, Z, r, c, 16)
+        if (l.range) this.#circle(p, X, Z, l.range, c, 48)
+      } else if (l.kind === 'spot' && l.position && l.direction) {
+        // the cone out to its range (or the scene's size), with a ring where its edge is
+        const p = new Vec3().copy(l.position), d = new Vec3().copy(l.direction).normalize()
+        const length = l.range ? Math.min(l.range, size * 2) : size, r = length * Math.tan(l.angle ?? Math.PI / 4)
+        const end = moved(p, d, length)
+        const [u, v] = across(d)
+        this.#circle(end, u, v, r, c, 32)
+        for (const s of [u, v, u.clone().negate(), v.clone().negate()]) this.#segment(p, moved(end, s, r), c)
+        this.#segment(p, end, c)
+      }
+    }
+  }
+
+  /** @param {FrameDescription} frame */
+  #shadows(frame) {
+    if (frame.shadow) this.#frustum(frame.shadow.viewProjection, COLORS.shadow)
+    for (const s of frame.spotShadows) this.#frustum(s.viewProjection, COLORS.shadow)
+  }
+
+  /** @param {DrawItem[]} items @param {Hit | null} hovered @param {boolean} onlyHovered */
+  #bounds(items, hovered, onlyHovered) {
+    if (onlyHovered) {
+      if (!hovered) return
+      const node = /** @type {any} */ (hovered.node)
+      // an instance's own box, or the whole node's
+      if (hovered.instance !== null && typeof node.eachInstanceBox === 'function') {
+        let i = 0
+        node.eachInstanceBox((x0, y0, z0, x1, y1, z1) => {
+          if (i++ === hovered.instance) this.#box(new Box3([x0, y0, z0], [x1, y1, z1]), COLORS.bounds)
+        })
+      } else this.#box(node.expandBounds(new Box3()), COLORS.bounds)
+      return
+    }
+    const seen = new Set()
+    for (const item of items) {
+      if (seen.has(item.node)) continue
+      seen.add(item.node)
+      const box = /** @type {any} */ (item.node).expandBounds(new Box3())
+      if (!box.isEmpty()) this.#box(box, COLORS.bounds)
+    }
+  }
+
+  /** @param {DrawItem[]} items @param {Hit | null} hovered @param {boolean} onlyHovered @param {number} length */
+  #normals(items, hovered, onlyHovered, length) {
+    const meshes = onlyHovered
+      ? (hovered && /** @type {any} */ (hovered.node).drawMode === 'triangles' ? [/** @type {any} */ (hovered.node)] : [])
+      : [...new Set(items.map((i) => i.node))].filter((n) => /** @type {any} */ (n).drawMode === 'triangles')
+    let budget = NORMALS_IN_ALL
+    for (const node of /** @type {any[]} */ (meshes)) {
+      if (node.instanceMatrices) continue
+      const g = node.geometry, count = g.vertexCount
+      if (!g.normals || (!onlyHovered && (count > NORMALS_PER_MESH || count > budget))) continue
+      budget -= count
+      const m = node.worldMatrix, p = g.positions, n = g.normals
+      const a = new Vec3(), d = new Vec3()
+      for (let i = 0; i < count; i++) {
+        a.set(p[i * 3], p[i * 3 + 1], p[i * 3 + 2]).applyMatrix4(m)
+        // the normal turned with the node (the upper 3x3: right for rotation and even scale)
+        d.set(m[0] * n[i * 3] + m[4] * n[i * 3 + 1] + m[8] * n[i * 3 + 2], m[1] * n[i * 3] + m[5] * n[i * 3 + 1] + m[9] * n[i * 3 + 2],
+          m[2] * n[i * 3] + m[6] * n[i * 3 + 1] + m[10] * n[i * 3 + 2]).normalize()
+        this.#segment(a, [a[0] + d[0] * length, a[1] + d[1] * length, a[2] + d[2] * length], COLORS.normal)
+      }
+    }
+  }
+}
+
+const X = new Vec3(1, 0, 0), Y = new Vec3(0, 1, 0), Z = new Vec3(0, 0, 1)
+// a box's corners by bit (x, y, z), and the twelve edges between them
+const EDGES = [[0, 1], [2, 3], [4, 5], [6, 7], [0, 2], [1, 3], [4, 6], [5, 7], [0, 4], [1, 5], [2, 6], [3, 7]]
+
+/** Two unit axes across a direction. @param {Vec3} d @returns {[Vec3, Vec3]} */
+function across(d) {
+  const up = Math.abs(d[1]) < 0.9 ? Y : X
+  const u = d.clone().cross(up).normalize()
+  return [u, d.clone().cross(u).normalize()]
+}
+
+/** p moved s along d, as a new point. @param {ArrayLike<number>} p @param {ArrayLike<number>} d @param {number} s */
+function moved(p, d, s) {
+  return new Vec3(p[0] + d[0] * s, p[1] + d[1] * s, p[2] + d[2] * s)
+}

package/src/explain.js

@@ -24,6 +24,7 @@ import { Box3 } from './value/Box3.js'
  * @property {boolean} [sharedContext] drawn with the page's shared WebGL context
  * @property {{ hover: number, click: number, tooltip: boolean, highlight: boolean, keyboard?: boolean, reducedMotion?: boolean, description?: string | null }} interaction
  * @property {string[]} [notes] lines from nodes that describe themselves, such as charts
+ * @property {Record<string, unknown> | null} [debug] what debug drawing shows, when it is on
  */
 
 const fmt = (n) => (Math.abs(n) >= 1e4 || (n !== 0 && Math.abs(n) < 1e-3) ? n.toExponential(2) : String(+n.toFixed(2)))
@@ -113,6 +114,19 @@ export function explain(info) {
   const invisible = items.filter((i) => i.material.opacity === 0).length
   if (invisible) warnings.push(`${plural(invisible, 'object')} with material opacity 0 - drawn but invisible`)
 
+  // shader hooks: which drawn things have GLSL of their own, and what they read
+  const hooked = items.filter((i) => i.material.shader)
+  if (hooked.length) {
+    const parts = (/** @type {any} */ s) => ['vertex', 'fragment', 'lit'].filter((p) => s[p]).join(', ')
+    lines.push(`Shader hooks: ${hooked.map((i) => {
+      const s = /** @type {any} */ (i.material.shader), n = /** @type {any} */ (i.node)
+      const reads = [...(/\buTime\b/.test(s.vertex + s.fragment + s.lit) ? ['uTime'] : []), ...Object.keys(s.uniforms)]
+      return `${n.constructor.name}${n.name ? ` '${n.name}'` : ''} (${parts(s)}${reads.length ? `; ${reads.join(', ')}` : ''})`
+    }).join(', ')}`)
+    const unculled = hooked.filter((i) => i.material.shader?.vertex && i.material.shader.bounds === null).length
+    if (unculled) lines.push(`  ${plural(unculled, 'object')} moved by a vertex hook without shader.bounds - not frustum culled, and picked on the GPU`)
+  }
+
   if (info.labels && info.labels.total) {
     const s = info.labels
     lines.push(`Labels: ${s.shown} shown, ${s.dimmed ? `${s.dimmed} dimmed (covered by labels or geometry), ` : ''}${s.overlapped} hidden by overlap, ${s.occluded} hidden behind geometry, ${s.offscreen} off screen${s.zoomedOut ? `, ${s.zoomedOut} waiting to be zoomed in to (minScale)` : ''}`)
@@ -137,6 +151,11 @@ export function explain(info) {
     warnings.unshift(`nothing is in view: ${plural(frame.stats.culled, 'object')} are outside the camera's view - call view.frame() to fit the camera to the scene`)
   }
 
+  // debug drawing on: said, so a picture full of lines isn't a mystery
+  if (info.debug) {
+    const shown = Object.entries(info.debug).filter(([, v]) => v).map(([k, v]) => (v === true ? k : `${k} (${v})`))
+    lines.push(`Debug drawing: ${shown.join(', ') || 'nothing'} - helpers aren't part of the scene, picked or counted above`)
+  }
   lines.push(warnings.length ? `Warnings:\n${warnings.map((w) => `- ${w}`).join('\n')}` : 'No warnings.')
   return lines.join('\n')
 }

package/src/frame.js

@@ -151,6 +151,7 @@ export const LIGHT_LIMITS = { punctual: 4, directional: 2 }
  * @property {PointShadowFrame | null} pointShadow a point light's shadow, all round it
  * @property {FrameCap[]} caps section planes' caps to fill, after the opaque pass
  * @property {{ drawn: number, culled: number }} stats
+ * @property {number} [time] the View's clock in seconds, for shader hooks that read uTime
  * @property {FrameHighlight | null} highlight set by the View for hover highlighting
  * @property {any[]} overlays HTML elements carried by the nodes drawn (node.overlay)
  * @property {boolean} interactive some node has a tooltip, highlight or pointer handler
@@ -191,6 +192,7 @@ export function collect(scene, camera) {
     pointShadow: null,
     caps: [],
     stats: { drawn: 0, culled: 0 },
+    time: 0,
     highlight: null,
     overlays: [],
     interactive: false,
@@ -359,8 +361,11 @@ function drawItem(node, view, planes, clip) {
   const center = box.getCenter().applyMatrix4(worldMatrix)
   const scale = Math.max(Math.hypot(worldMatrix[0], worldMatrix[1], worldMatrix[2]),
     Math.hypot(worldMatrix[4], worldMatrix[5], worldMatrix[6]), Math.hypot(worldMatrix[8], worldMatrix[9], worldMatrix[10]))
-  // instanced meshes spread their copies anywhere, so they aren't culled as a whole
-  if (planes && node.frustumCulled && !instances && !sphereInFrustum(planes, center, box.getRadius() * scale)) return null
+  // instanced meshes spread their copies anywhere, so they aren't culled as a whole; a shader hook
+  // that moves vertices is culled by its padded bounds, or - without them - not at all
+  const hooks = material.shader?.vertex ? material.shader : null
+  const pad = hooks ? hooks.bounds : 0
+  if (planes && node.frustumCulled && !instances && pad !== null && !sphereInFrustum(planes, center, box.getRadius() * scale + pad)) return null
   // all of it on the cut-away side of a clip - points and lines aren't cut, so they stay
   const cuts = clip && node.drawMode === 'triangles' ? clip : null
   if (cuts && !instances) {

package/src/material/Material.js

@@ -7,6 +7,40 @@ import { Texture } from './Texture.js'
 
 /** A map: a Texture, its options, or just a url. @typedef {Texture | TextureOptions | string} MapInput */
 
+/**
+ * A shader uniform's value: a number (float), two to four numbers (vec2-vec4), a colour - a colour
+ * string or Color, sent linear as the shader works (vec3) - or a Texture (sampler2D).
+ * @typedef {number | number[] | ColorInput | Texture} ShaderUniform
+ */
+
+/**
+ * Small pieces of GLSL run inside phoria2's own shader, so lighting, shadows, fog, clipping,
+ * picking and outlines keep working. Every hook can read `uTime` (the View's clock, in seconds)
+ * and the uniforms given, and call - p a vec2 or vec3, every result 0-1 - `hash(x)` (the same on every
+ * GPU for the same bits), `vnoise(p)` (value noise), `snoise(p)` (simplex noise; `snoised(p)` with its
+ * gradient), and `vfbm(p)` / `sfbm(p)` / `sfbmd(p)` (octaves of either, five unless given:
+ * `sfbm(p, 8)`), `voronoi(p)` (cellular noise: vec3 of the nearest and second nearest distances and
+ * a random 0-1 for the nearest cell); and `srgb(c)` (a colour as picked to linear), `hsv2rgb`, `palette` (cosine
+ * palettes, linear), `fresnel(normal, position, power)` (rim light - `cameraPosition` is there too),
+ * `rotate2(a)` / `rotate3(axis, a)` matrices, `remap` and `saturate`.
+ * @typedef {object} ShaderHooks
+ * @property {string} [vertex] runs on each vertex before it is placed: change `local` (vec3, the
+ *   geometry's own space) - and for meshes `n`, its normal; reads `uv` (meshes), `index` (the
+ *   instance, point or segment), `size` (points: change it too) and `along` (lines: 0 at a
+ *   segment's start, 1 at its end)
+ * @property {string} [fragment] runs on each pixel before lighting: change `base` (vec4: linear
+ *   colour and alpha) and, on meshes, `emissive` and `normal` (the shading normal, world space - bend it for
+ *   relief lit per pixel); `discard` cuts the pixel away - shadows and
+ *   picking too. Reads `vUv`, `vWorldPosition`, `vNormal` (meshes), `pointUv` and `index`
+ *   (points), `distance` along the line and `index` the segment (lines)
+ * @property {string} [lit] runs after lighting: change `color` (vec3, linear) and `base.a` - glows,
+ *   scanlines and fades the light doesn't touch
+ * @property {Record<string, ShaderUniform>} [uniforms] values the hooks read, by name; change them on
+ *   `material.shader.uniforms` and the View redraws
+ * @property {number} [bounds] how far, in world units, the vertex hook can move a vertex: bounds are
+ *   padded by it for culling, framing and shadows. Without it a vertex hook turns frustum culling off
+ */
+
 /**
  * @typedef {object} MaterialOptions
  * @property {string} [name]
@@ -71,6 +105,8 @@ import { Texture } from './Texture.js'
  * @property {boolean} [depthTest] (default true)
  * @property {number} [size] Points: diameter in world units, or pixels when sizeAttenuation is off (default 1)
  * @property {boolean} [sizeAttenuation] Points: sized in the world, so smaller with distance (default true)
+ * @property {ShaderHooks | null} [shader] GLSL of your own, run at fixed points in the shader - waves,
+ *   dissolves, glows (default none)
  * @property {number} [width] Lines: width in pixels (default 1)
  * @property {number} [dash] Lines: dashed, with dashes this long in the model's units; 0 is solid (default 0)
  * @property {number} [gap] Lines: the gaps between dashes; 0 is as long as the dashes (default 0)
@@ -97,7 +133,12 @@ const DEFAULTS = {
   doubleSided: false, vertexColors: false, blending: 'normal', depthWrite: true, depthTest: true, fog: true,
   size: 1, sizeAttenuation: true, width: 1, dash: 0, gap: 0, dashOffset: 0,
 }
-const OPTIONS = ['name', ...Object.keys(COLORS), ...MAPS, ...FLAGS, ...Object.keys(NUMBERS), 'blending']
+const OPTIONS = ['name', ...Object.keys(COLORS), ...MAPS, ...FLAGS, ...Object.keys(NUMBERS), 'blending', 'shader']
+const HOOKS = ['vertex', 'fragment', 'lit', 'uniforms', 'bounds']
+// names the shader keeps for itself
+// the functions hooks can call
+const HELPERS = ['hash', 'vnoise', 'snoise', 'snoised', 'vfbm', 'sfbm', 'sfbmd', 'voronoi', 'srgb', 'hsv2rgb', 'palette', 'fresnel', 'rotate2', 'rotate3', 'remap', 'saturate']
+const RESERVED = new RegExp(`^(gl_|phoria)|^(uTime|cameraPosition|${HELPERS.join('|')})$`)
 
 // what agents (and three.js habits) will reach for
 const HINTS = {
@@ -119,6 +160,10 @@ const HINTS = {
   colour: "use 'color'",
   emissiveColor: "use 'emissive'",
   alpha: "use 'opacity'",
+  onBeforeCompile: "use 'shader': { vertex, fragment, lit, uniforms } - GLSL run inside phoria2's own shader",
+  vertexShader: "use 'shader': { vertex: 'local.y += sin(local.x + uTime);' } - a hook, not a whole shader",
+  fragmentShader: "use 'shader': { fragment: 'base.rgb *= 0.5;' } - a hook, not a whole shader",
+  uniforms: "use 'shader': { uniforms: { uAmount: 1 } }",
 }
 
 /**
@@ -176,6 +221,8 @@ export class Material {
   #maps = Object.fromEntries(MAPS.map((m) => [m, null]))
   /** @type {Set<() => void>} */
   #onDispose = new Set()
+  /** @type {Required<Omit<ShaderHooks, 'bounds'>> & { bounds: number | null } | null} */
+  #shader = null
 
   /** @param {MaterialOptions} [options] */
   constructor(options = {}) {
@@ -189,9 +236,27 @@ export class Material {
       else if (key in NUMBERS) this[key] = range(key, value, NUMBERS[key])
       else if (key === 'blending') this.blending = checkOneOf('Material', 'blending', value, ['normal', 'additive', 'multiply'])
       else if (key === 'name') this.name = String(value)
+      else if (key === 'shader') this.shader = value
     }
   }
 
+  /**
+   * GLSL hooks run inside the shader, or null. Change its uniforms in place
+   * (`material.shader.uniforms.uAmount = 2`); assign a new object to change the code.
+   * @returns {Required<Omit<ShaderHooks, 'bounds'>> & { bounds: number | null } | null}
+   */
+  get shader() { return this.#shader }
+  /** @param {ShaderHooks | null} v */
+  set shader(v) { this.#shader = shaderHooks(v) }
+
+  /** @internal Every texture the material reads: its maps, then its shader's uniform textures. @returns {[string, Texture][]} */
+  get allTextures() {
+    const maps = this.textures
+    const u = this.#shader?.uniforms
+    if (!u) return maps
+    return [...maps, ...Object.entries(u).filter(([, v]) => v instanceof Texture).map(([k, v]) => /** @type {[string, Texture]} */ ([`shader.${k}`, v]))]
+  }
+
   /** @internal
    * A Material from a Material (returned as is) or options.
    * @param {Material | MaterialOptions} input
@@ -322,12 +387,13 @@ export class Material {
     if (this.toon > 0) parts.push('toon')
     if (this.flatShading) parts.push('flat')
     if (this.vertexColors) parts.push('vcolor')
+    if (this.#shader) parts.push('hooks')
     return parts.join('+')
   }
 
   /** Resolves when every texture has loaded. @returns {Promise<void>} */
   async ready() {
-    await Promise.all(this.textures.map(([, t]) => t.ready))
+    await Promise.all(this.allTextures.map(([, t]) => t.ready))
   }
 
   /** @returns {Material} */
@@ -366,6 +432,17 @@ export class Material {
       const desc = keepTextures ? t : t.toJSON()
       if (desc) json[slot] = desc
     }
+    const s = this.#shader
+    if (s) {
+      /** @type {Record<string, unknown>} */
+      const hooks = {}
+      for (const part of ['vertex', 'fragment', 'lit']) if (s[part]) hooks[part] = s[part]
+      const uniforms = Object.entries(s.uniforms).map(([k, v]) => [k, v instanceof Texture ? (keepTextures ? v : v.toJSON())
+        : v instanceof Color ? v.getStyle() : Array.isArray(v) || ArrayBuffer.isView(v) ? Array.from(/** @type {ArrayLike<number>} */ (v)) : v])
+      if (uniforms.length) hooks.uniforms = Object.fromEntries(uniforms.filter(([, v]) => v != null))
+      if (s.bounds !== null) hooks.bounds = s.bounds
+      json.shader = hooks
+    }
     return json
   }
 }
@@ -383,3 +460,45 @@ function range(name, v, [min, max]) {
   if (n < min || n > max) fail('Material', `'${name}' must be ${max === Infinity ? `${min} or more` : `${min}-${max}`}, got ${n}`)
   return n
 }
+
+/**
+ * Shader hooks checked and copied: each piece of code a string, the uniforms by valid names, their
+ * values numbers, two to four numbers, colours or textures.
+ * @param {ShaderHooks | null | undefined} v
+ */
+function shaderHooks(v) {
+  if (v == null) return null
+  if (typeof v !== 'object' || Array.isArray(v)) fail('Material', `'shader' is { vertex, fragment, lit, uniforms, bounds } - GLSL hooks - got ${describe(v)}`)
+  checkOptions('Material shader', v, HOOKS, {
+    vertexShader: "use 'vertex' - a few lines run on each vertex, not a whole shader",
+    fragmentShader: "use 'fragment' (before lighting) or 'lit' (after) - a few lines, not a whole shader",
+  })
+  for (const part of ['vertex', 'fragment', 'lit']) {
+    if (v[part] !== undefined && typeof v[part] !== 'string') fail('Material', `shader '${part}' is GLSL as a string, got ${describe(v[part])}`)
+  }
+  if (!v.vertex && !v.fragment && !v.lit) fail('Material', "'shader' needs at least one of 'vertex', 'fragment' or 'lit'")
+  const uniforms = v.uniforms ?? {}
+  if (typeof uniforms !== 'object' || Array.isArray(uniforms)) fail('Material', `shader 'uniforms' is an object of name: value, got ${describe(uniforms)}`)
+  /** @type {Record<string, ShaderUniform>} */
+  const own = {}
+  for (const [name, value] of Object.entries(uniforms)) {
+    if (!/^[A-Za-z_]\w*$/.test(name)) fail('Material', `shader uniform '${name}' isn't a GLSL name - letters, digits and _, not starting with a digit`)
+    if (RESERVED.test(name)) fail('Material', `shader uniform '${name}' is a name phoria2 keeps${name === 'uTime' ? " - uTime is there already, the View's clock in seconds" : name === 'cameraPosition' ? " - cameraPosition is there already, the camera's world position" : HELPERS.includes(name) ? ` - ${name}() is a function every hook can call` : ''}`)
+    own[name] = uniformValue(name, value)
+  }
+  const bounds = v.bounds === undefined || v.bounds === null ? null : Math.max(0, checkNumber('Material', 'shader bounds', v.bounds))
+  return { vertex: v.vertex ?? '', fragment: v.fragment ?? '', lit: v.lit ?? '', uniforms: own, bounds }
+}
+
+/** A uniform's value as kept: numbers and arrays as given, colours as Colors, textures as Textures. @param {string} name @param {unknown} v @returns {ShaderUniform} */
+function uniformValue(name, v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  if ((Array.isArray(v) || ArrayBuffer.isView(v)) && /** @type {ArrayLike<unknown>} */ (v).length >= 2 && /** @type {ArrayLike<unknown>} */ (v).length <= 4 && Array.from(/** @type {ArrayLike<unknown>} */ (v)).every((n) => typeof n === 'number' && Number.isFinite(n))) {
+    return Array.from(/** @type {ArrayLike<number>} */ (v))
+  }
+  if (v instanceof Texture) return v
+  if (v instanceof Color) return v
+  if (v && typeof v === 'object' && 'url' in v) return new Texture(/** @type {any} */ (v))
+  if (typeof v === 'string') return Color.fromInput(v, 'Material')
+  return fail('Material', `shader uniform '${name}' is a number, two to four numbers, a colour or a Texture, got ${describe(v)}`)
+}

package/src/scene/drawables.js

@@ -215,7 +215,9 @@ export class Drawable extends Node {
 
   /** @internal @param {Box3} box */
   expandBounds(box) {
-    if (this.geometry.vertexCount) box.union(this.geometry.bounds.clone().applyMatrix4(this.worldMatrix))
+    if (!this.geometry.vertexCount) return box
+    const own = this.geometry.bounds.clone().applyMatrix4(this.worldMatrix)
+    box.union(padForHooks(own, this.material))
     return box
   }
 
@@ -249,7 +251,7 @@ export class Drawable extends Node {
   dispose() {
     this.geometry.dispose()
     this.material.dispose()
-    for (const [, t] of this.material.textures) t.dispose()
+    for (const [, t] of this.material.allTextures) t.dispose()
     super.dispose()
   }
 }
@@ -411,9 +413,11 @@ export class InstancedMesh extends Mesh {
 
   /** @internal @param {Box3} box */
   expandBounds(box) {
+    // as far as a shader hook can move a vertex, round each copy
+    const pad = this.material.shader?.vertex ? this.material.shader.bounds ?? 0 : 0
     this.eachInstanceBox((x0, y0, z0, x1, y1, z1) => {
-      box.expandByXYZ(x0, y0, z0)
-      box.expandByXYZ(x1, y1, z1)
+      box.expandByXYZ(x0 - pad, y0 - pad, z0 - pad)
+      box.expandByXYZ(x1 + pad, y1 + pad, z1 + pad)
     })
     return box
   }
@@ -647,3 +651,16 @@ export class Label extends Node {
     return json
   }
 }
+
+/**
+ * A drawable's world box, grown by as far as its shader's vertex hook says it can move a vertex.
+ * @param {import('../value/Box3.js').Box3} box @param {import('../material/Material.js').Material} material
+ */
+function padForHooks(box, material) {
+  const pad = material.shader?.vertex ? material.shader.bounds ?? 0 : 0
+  if (pad > 0 && !box.isEmpty()) {
+    box.min.set(box.min[0] - pad, box.min[1] - pad, box.min[2] - pad)
+    box.max.set(box.max[0] + pad, box.max[1] + pad, box.max[2] + pad)
+  }
+  return box
+}

package/src/watch.js

@@ -10,6 +10,8 @@
 /** @type {WeakMap<object, number>} */
 const ids = new WeakMap()
 let nextId = 1
+/** Does a material's shader hook read the clock? @param {{ vertex: string, fragment: string, lit: string }} h */
+export const usesTime = (h) => /\buTime\b/.test(h.vertex + h.fragment + h.lit)
 /** @param {object} o */
 const idOf = (o) => {
   let id = ids.get(o)
@@ -24,14 +26,17 @@ export class ChangeWatch {
   #previousCount = -1
   /** @type {string[]} */ #strings = []
   /** @type {string[]} */ #previousStrings = []
+  #time = 0
 
   /**
    * Has anything that affects the picture changed since the last call? The first call says yes.
    * @param {Scene} scene
    * @param {Camera} camera
+   * @param {number} [time] the View's clock, which shader hooks reading uTime follow
    * @returns {boolean}
    */
-  changed(scene, camera) {
+  changed(scene, camera, time = 0) {
+    this.#time = time
     this.#count = 0
     this.#strings = []
     this.#camera(camera)
@@ -194,7 +199,18 @@ export class ChangeWatch {
     this.#pushAll(m.translucencyColor)
     this.#push((m.unlit ? 1 : 0) | (m.flatShading ? 2 : 0) | (m.doubleSided ? 4 : 0) | (m.vertexColors ? 8 : 0) |
       (m.depthWrite ? 16 : 0) | (m.depthTest ? 32 : 0) | (m.sizeAttenuation ? 64 : 0) | (m.blending === 'additive' ? 128 : m.blending === 'multiply' ? 1024 : 0) | (m.transparent ? 256 : 0) | (m.fog ? 512 : 0))
-    for (const [, texture] of m.textures) this.#texture(texture)
+    for (const [, texture] of m.allTextures) this.#texture(texture)
+    const hooks = m.shader
+    if (hooks) {
+      this.#push(idOf(hooks))
+      for (const v of Object.values(hooks.uniforms)) {
+        if (typeof v === 'number') this.#push(v)
+        // numbers and colours - textures count through their versions, above
+        else if (Array.isArray(v) || ArrayBuffer.isView(v)) this.#pushAll(/** @type {ArrayLike<number>} */ (v))
+      }
+      // a hook that reads the clock moves on its own while time runs
+      if (usesTime(hooks)) this.#push(this.#time)
+    }
   }
 
   /** @param {any} texture */