phoria2 1.3.0 → 1.4.0

package/src/webgl/shaders.js

@@ -116,9 +116,17 @@ export const CLIP_ONLY_FRAGMENT = /* glsl */ `
 precision highp float;
 in vec3 vWorldPosition;
 out vec4 fragColor;
+#if defined(ALPHA_TEST) || defined(HOOK_FRAGMENT)
+in vec2 vUv;
+#endif
+#ifdef HOOK_FRAGMENT
+// a fragment hook's discards cut the shadow too - a dissolving thing casts what is left of it
+in vec3 vNormal;
+in vec3 vColor;
+//@hook uniforms
+#endif
 #ifdef ALPHA_TEST
 // a cut-out casts the shadow of what is left of it - leaves, fences, grilles - not of its rectangle
-in vec2 vUv;
 uniform float uOpacity;
 uniform float uAlphaTest;
 #ifdef MAP
@@ -129,6 +137,15 @@ ${SAMPLING}
 ${CLIP}
 void main() {
   clipAway(vWorldPosition);
+#ifdef HOOK_FRAGMENT
+  {
+    vec4 base = vec4(vColor, 1.0);
+    vec3 emissive = vec3(0.0);
+    vec3 normal = normalize(vNormal);
+//@hook fragment
+    if (base.a <= 0.0) discard;
+  }
+#endif
 #ifdef ALPHA_TEST
   float alpha = uOpacity;
 #ifdef MAP
@@ -225,6 +242,7 @@ uniform int uHighlightIndex; // -2 none, -1 the whole node, otherwise the instan
 uniform mat4 uView;
 out float vFogDepth;
 #endif
+//@hook uniforms
 
 out vec3 vWorldPosition;
 out vec3 vNormal;
@@ -248,25 +266,34 @@ ${COMMON}
 void main() {
   vColor = vec3(1.0);
   vHighlight = uHighlightIndex == -1 ? 1.0 : 0.0;
+  // the vertex in the geometry's own space - where a shader hook moves it
+  vec3 local = position;
+  vec3 n = normal;
+#ifdef HOOK_VERTEX
+  {
+    int index = gl_InstanceID;
+//@hook vertex
+  }
+#endif
 #ifdef INSTANCED
-  vec4 local = instanceMatrix * vec4(position, 1.0);
+  vec4 placed = instanceMatrix * vec4(local, 1.0);
   // the instance's normal matrix as its cofactor: the inverse transpose up to scale, from three
   // cross products, flipped back for mirroring transforms
   mat3 m = mat3(instanceMatrix);
   mat3 instanceNormal = mat3(cross(m[1], m[2]), cross(m[2], m[0]), cross(m[0], m[1])) * sign(dot(m[0], cross(m[1], m[2])));
-  vec3 n = instanceNormal * normal;
+  vec3 placedNormal = instanceNormal * n;
   vColor *= instanceColor;
   if (gl_InstanceID == uHighlightIndex) vHighlight = 1.0;
 #else
-  vec4 local = vec4(position, 1.0);
-  vec3 n = normal;
+  vec4 placed = vec4(local, 1.0);
+  vec3 placedNormal = n;
 #endif
 #ifdef VERTEX_COLORS
   vColor *= srgbToLinear(color);
 #endif
-  vec4 world = uModel * local;
+  vec4 world = uModel * placed;
   vWorldPosition = world.xyz;
-  vNormal = uNormalMatrix * n;
+  vNormal = uNormalMatrix * placedNormal;
   vUv = uv;
 #ifdef UV2
   vUv2 = uv2;
@@ -280,8 +307,8 @@ void main() {
 #endif
 #endif
 #ifdef TRIPLANAR
-  vObjectPosition = position;
-  vObjectNormal = normal;
+  vObjectPosition = local;
+  vObjectNormal = n;
 #ifdef INSTANCED
   vObjectToWorld = uNormalMatrix * instanceNormal;
 #else
@@ -322,6 +349,7 @@ uniform float uAlphaTest;
 #ifdef EMISSIVE_MAP
 uniform sampler2D uEmissiveMap;
 #endif
+//@hook uniforms
 
 ${SAMPLING}
 #ifdef LIT
@@ -738,6 +766,25 @@ void main() {
   vec4 base = vec4(uColor * vColor, uOpacity);
 #ifdef MAP
   base *= uMapTexel; // sRGB textures are decoded to linear by the hardware
+#endif
+  vec3 emissive = uEmissive;
+#ifdef EMISSIVE_MAP
+  emissive *= uEmissiveMapTexel.rgb;
+#endif
+#ifdef HOOK_FRAGMENT
+  // the shading normal in world space, facing the viewer - a fragment hook can bend it, for relief
+  // lit per pixel (bumps from noise) whatever the mesh's resolution
+#ifdef FLAT_SHADING
+  vec3 normal = normalize(cross(dFdx(vWorldPosition), dFdy(vWorldPosition)));
+#else
+  vec3 normal = normalize(vNormal);
+#ifdef DOUBLE_SIDED
+  if (!gl_FrontFacing) normal = -normal;
+#endif
+#endif
+  {
+//@hook fragment
+  }
 #endif
 #ifdef ALPHA_TEST
   if (base.a < uAlphaTest) discard;
@@ -745,19 +792,18 @@ void main() {
 #endif
   // how much of what is behind it this hides: its opacity - less for glass, which lets light through
   float coverage = base.a;
-  vec3 emissive = uEmissive;
-#ifdef EMISSIVE_MAP
-  emissive *= uEmissiveMapTexel.rgb;
-#endif
 
 #ifdef LIT
-#ifdef FLAT_SHADING
+#ifdef HOOK_FRAGMENT
+  // the fragment hook's normal, facing the viewer already
+  vec3 n = normalize(normal);
+#elif defined(FLAT_SHADING)
   // from the screen-space slope: it faces the camera whichever side of the face is seen
   vec3 n = normalize(cross(dFdx(vWorldPosition), dFdy(vWorldPosition)));
 #else
   vec3 n = normalize(vNormal);
 #endif
-#if defined(DOUBLE_SIDED) && !defined(FLAT_SHADING)
+#if defined(DOUBLE_SIDED) && !defined(FLAT_SHADING) && !defined(HOOK_FRAGMENT)
   if (!gl_FrontFacing) n = -n;
 #endif
   vec3 surfaceNormal = n;
@@ -948,6 +994,14 @@ void main() {
 #endif
 #else
   vec3 color = base.rgb + emissive;
+#endif
+#ifdef HOOK_LIT
+  {
+    // a fade here fades what it hides too
+    float before = max(base.a, 1e-5);
+//@hook lit
+    coverage *= clamp(base.a / before, 0.0, 1.0);
+  }
 #endif
   color = mix(color, uHighlight.rgb, vHighlight * uHighlight.a);
   // a highlight shows on glass as on anything else
@@ -981,9 +1035,13 @@ uniform mat4 uProjection;
 uniform float uSize;        // pixels (with the pixel ratio applied), or world units when attenuated
 uniform float uScale;       // projection focal term x half the buffer height: world size -> pixels at depth 1
 uniform int uHighlightIndex; // -2 none, -1 every point, otherwise the point
+//@hook uniforms
 
 out vec3 vColor;
 flat out float vHighlight;
+#ifdef HOOK_FRAGMENT
+flat out float vPointIndex;
+#endif
 #ifdef PICK
 flat out uint vPickElement; // which instance, point or segment, for GPU picking
 #endif
@@ -994,29 +1052,46 @@ out float vFogDepth;
 ${COMMON}
 
 void main() {
-  vec4 viewPosition = uView * (uModel * vec4(position, 1.0));
+  // the point in the geometry's own space, and its size as a multiple of the material's - where a
+  // shader hook changes them
+  vec3 local = position;
+#ifdef SPRITES
+  int self = int(pointIndex + 0.5);
+  float size = pointSize;
+#else
+  int self = gl_VertexID;
+  float size = 1.0;
+#endif
+#ifdef HOOK_VERTEX
+  {
+    int index = self;
+//@hook vertex
+  }
+#endif
+#ifdef HOOK_FRAGMENT
+  vPointIndex = float(self);
+#endif
+  vec4 viewPosition = uView * (uModel * vec4(local, 1.0));
 #ifdef SPRITES
   // the square's corner, turned by the point's angle: the texture turns with it
   vec2 c = vec2(corner.x * 2.0 - 1.0, corner.y);
   float s = sin(pointAngle), k = cos(pointAngle);
   vec2 turned = vec2(c.x * k - c.y * s, c.x * s + c.y * k);
-  float size = uSize * pointSize;
+  float across = uSize * size;
 #ifdef SIZE_ATTENUATION
   // world units: the square sits in the view, facing the camera
-  viewPosition.xy += turned * size * 0.5;
+  viewPosition.xy += turned * across * 0.5;
   gl_Position = uProjection * viewPosition;
 #else
   // pixels: the square is laid out on the screen
   gl_Position = uProjection * viewPosition;
-  gl_Position.xy += turned * size / uResolution * gl_Position.w;
+  gl_Position.xy += turned * across / uResolution * gl_Position.w;
 #endif
   // the image upright on the square, its top at the top, as a point's is
   vUv = vec2(c.x * 0.5 + 0.5, 0.5 - c.y * 0.5);
   vOpacity = pointOpacity;
-  int self = int(pointIndex + 0.5);
 #else
   gl_Position = uProjection * viewPosition;
-  int self = gl_VertexID;
 #endif
 #ifdef FOG
   vFogDepth = -viewPosition.z;
@@ -1025,9 +1100,9 @@ void main() {
 #elif defined(SIZE_ATTENUATION)
   // perspective shrinks with distance; an orthographic projection (w row 0, 0, 0, 1) doesn't
   float depth = uProjection[3][3] == 1.0 ? 1.0 : max(-viewPosition.z, 1e-4);
-  gl_PointSize = uSize * uScale / depth;
+  gl_PointSize = uSize * size * uScale / depth;
 #else
-  gl_PointSize = uSize;
+  gl_PointSize = uSize * size;
 #endif
   vColor = vec3(1.0);
 #ifdef VERTEX_COLORS
@@ -1054,6 +1129,10 @@ uniform float uOpacity;
 #ifdef MAP
 uniform sampler2D uMap;
 #endif
+#ifdef HOOK_FRAGMENT
+flat in float vPointIndex;
+#endif
+//@hook uniforms
 out vec4 fragColor;
 
 ${COMMON}
@@ -1075,10 +1154,22 @@ void main() {
   float r = dot(p, p);
   float edge = fwidth(r);
   base.a *= 1.0 - smoothstep(1.0 - edge, 1.0, r);
+#endif
+#ifdef HOOK_FRAGMENT
+  {
+    vec2 pointUv = at;
+    int index = int(vPointIndex + 0.5);
+//@hook fragment
+  }
 #endif
   if (base.a <= 0.0) discard;
-  base.rgb = fogged(mix(base.rgb, uHighlight.rgb, vHighlight * uHighlight.a));
-  fragColor = vec4(linearToSrgb(base.rgb) * base.a, base.a);
+  vec3 color = fogged(mix(base.rgb, uHighlight.rgb, vHighlight * uHighlight.a));
+#ifdef HOOK_LIT
+  {
+//@hook lit
+  }
+#endif
+  fragColor = vec4(linearToSrgb(color) * base.a, base.a);
 }
 `
 
@@ -1099,14 +1190,20 @@ uniform float uWidth;       // pixels, already scaled by the pixel ratio
 uniform float uNear;
 uniform int uArrows;        // arrowheads: 1 at the start of each chain, 2 at its end, 3 at both
 uniform float uArrowSize;   // their length in pixels, scaled by the pixel ratio
+//@hook uniforms
 
 // six vertices an instance make the segment's quad, as two triangles - x: 0 at its start, 1 at its
 // end; y: -1 or 1 across - and six more its two arrowheads, drawn only when asked for
 const vec2 QUAD[6] = vec2[6](vec2(0.0, -1.0), vec2(0.0, 1.0), vec2(1.0, -1.0), vec2(1.0, -1.0), vec2(0.0, 1.0), vec2(1.0, 1.0));
 
 out vec3 vColor;
-#ifdef DASHED
+#if defined(DASHED) || defined(HOOK_FRAGMENT)
 out float vDistance;        // along the chain, in the model's units
+#endif
+#ifdef HOOK_FRAGMENT
+flat out float vSegment;    // which segment, for a fragment hook's index
+#endif
+#ifdef DASHED
 flat out float vArrow;      // 1 on an arrowhead, which is never dashed
 #endif
 #ifdef PICK
@@ -1118,9 +1215,22 @@ out float vFogDepth;
 
 ${COMMON}
 
+#ifdef HOOK_VERTEX
+// a shader hook moves each end of each segment: local is the end, along 0 at the start and 1 at the end
+vec3 hookVertex(vec3 local, float along, int index) {
+//@hook vertex
+  return local;
+}
+#endif
+
 void main() {
-  vec4 a = uView * (uModel * vec4(segmentStart, 1.0));
-  vec4 b = uView * (uModel * vec4(segmentEnd, 1.0));
+  vec3 start = segmentStart, end = segmentEnd;
+#ifdef HOOK_VERTEX
+  start = hookVertex(segmentStart, 0.0, gl_InstanceID);
+  end = hookVertex(segmentEnd, 1.0, gl_InstanceID);
+#endif
+  vec4 a = uView * (uModel * vec4(start, 1.0));
+  vec4 b = uView * (uModel * vec4(end, 1.0));
   // clip the segment to the near plane so lines passing behind the camera stay correct
   float clipZ = -uNear;
   if (a.z > clipZ && b.z > clipZ) {
@@ -1170,8 +1280,13 @@ void main() {
 #endif
   clip.xy += offset / (uResolution * 0.5) * clip.w;
   gl_Position = clip;
+#if defined(DASHED) || defined(HOOK_FRAGMENT)
+  vDistance = segmentInfo.x + length(end - start) * along;
+#endif
+#ifdef HOOK_FRAGMENT
+  vSegment = float(gl_InstanceID);
+#endif
 #ifdef DASHED
-  vDistance = segmentInfo.x + length(segmentEnd - segmentStart) * along;
   vArrow = arrow;
 #endif
 #ifdef PICK
@@ -1190,8 +1305,14 @@ precision highp float;
 in vec3 vColor;
 uniform vec3 uColor;
 uniform float uOpacity;
-#ifdef DASHED
+#if defined(DASHED) || defined(HOOK_FRAGMENT)
 in float vDistance;
+#endif
+#ifdef HOOK_FRAGMENT
+flat in float vSegment;
+#endif
+//@hook uniforms
+#ifdef DASHED
 flat in float vArrow;
 uniform float uDash;        // dash and gap lengths, in the model's units
 uniform float uGap;
@@ -1206,8 +1327,22 @@ void main() {
 #ifdef DASHED
   if (vArrow < 0.5 && mod(vDistance - uDashOffset, uDash + uGap) >= uDash) discard;
 #endif
-  vec3 color = fogged(uColor * vColor);
-  fragColor = vec4(linearToSrgb(color) * uOpacity, uOpacity);
+  vec4 base = vec4(uColor * vColor, uOpacity);
+#ifdef HOOK_FRAGMENT
+  {
+    float distance = vDistance;
+    int index = int(vSegment + 0.5);
+//@hook fragment
+  }
+  if (base.a <= 0.0) discard;
+#endif
+  vec3 color = fogged(base.rgb);
+#ifdef HOOK_LIT
+  {
+//@hook lit
+  }
+#endif
+  fragColor = vec4(linearToSrgb(color) * base.a, base.a);
 }
 `
 
@@ -1220,13 +1355,286 @@ const SOURCES = {
 }
 
 /**
- * Vertex and fragment source for a kind of drawable, or a pass's own pair, with a set of feature defines.
+ * GLSL of a material's own, spliced in at the shaders' `//@hook` lines: uniform declarations, and
+ * code run on each vertex, before lighting and after it.
+ * @typedef {object} HookSource
+ * @property {string} uniforms declarations
+ * @property {string} [helpers] functions every hook can call - hash, noise, fbm
+ * @property {string} vertex
+ * @property {string} fragment
+ * @property {string} lit
+ */
+
+// Functions every shader hook can call - hooks are statements, so they can't define their own. All of
+// it is built on an integer bit-mix (lowbias32), which GLSL ES 3.00 defines exactly, so lattice
+// values and gradients are the same on every GPU - fract(sin(x) * 43758.5453) is not. Everything 0-1:
+// - hash(x): a float or vector's exact bits, mixed
+// - vnoise(p): value noise - random values at whole-number points, eased between (quintic); cheap,
+//   blocky-looking at low frequencies
+// - snoise(p): simplex noise - gradients on a simplex grid; smoother, less grid-bound, the better
+//   default; snoised(p) also gives its gradient, for normals
+// - vfbm / sfbm (p[, octaves]): octaves of either added up, each turned and scaled by 2.03 so their
+//   grids never line up; sfbmd adds the gradient. Five octaves unless told; 1-12
+// - voronoi(p): cellular (Worley) noise - a random point in every unit cell; returns the distance to
+//   the nearest (F1) and the second nearest (F2), in cells, and a random 0-1 for the nearest's cell
+// And the everyday ones people (and agents) reach for: srgb() to turn a colour as picked into the
+// linear one hooks work in, hsv2rgb() and palette() (Quilez's cosine palette) - both giving linear
+// colour - fresnel() for rim light, rotate2() / rotate3() matrices, remap() and saturate().
+// Every int highp: a fragment shader's ints are mediump unless they say so.
+export const HOOK_HELPERS = /* glsl */ `
+highp uint phoriaMix(highp uint h) {
+  h ^= h >> 16u; h *= 0x7feb352du; h ^= h >> 15u; h *= 0x846ca68bu; h ^= h >> 16u;
+  return h;
+}
+float phoriaUnit(highp uint h) { return float(h >> 8u) * (1.0 / 16777216.0); }
+float hash(float x) { return phoriaUnit(phoriaMix(floatBitsToUint(x))); }
+float hash(vec2 p) { highp uvec2 u = floatBitsToUint(p); return phoriaUnit(phoriaMix(u.x ^ phoriaMix(u.y + 0x9e3779b9u))); }
+float hash(vec3 p) { highp uvec3 u = floatBitsToUint(p); return phoriaUnit(phoriaMix(u.x ^ phoriaMix(u.y ^ phoriaMix(u.z + 0x9e3779b9u)))); }
+// a lattice point's bits: each coordinate times its own large odd number, mixed once
+highp uint phoriaCell(highp ivec3 c) {
+  highp uvec3 u = uvec3(c) * uvec3(0x8da6b343u, 0xd8163841u, 0xcb1ab31fu);
+  return phoriaMix(u.x ^ u.y ^ u.z);
+}
+
+float vnoise(vec3 p) {
+  vec3 i = floor(p), f = p - i;
+  vec3 s = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+  highp ivec3 c = ivec3(i);
+  float a = mix(phoriaUnit(phoriaCell(c)), phoriaUnit(phoriaCell(c + ivec3(1, 0, 0))), s.x);
+  float b = mix(phoriaUnit(phoriaCell(c + ivec3(0, 1, 0))), phoriaUnit(phoriaCell(c + ivec3(1, 1, 0))), s.x);
+  float d = mix(phoriaUnit(phoriaCell(c + ivec3(0, 0, 1))), phoriaUnit(phoriaCell(c + ivec3(1, 0, 1))), s.x);
+  float e = mix(phoriaUnit(phoriaCell(c + ivec3(0, 1, 1))), phoriaUnit(phoriaCell(c + ivec3(1, 1, 1))), s.x);
+  return mix(mix(a, b, s.y), mix(d, e, s.y), s.z);
+}
+float vnoise(vec2 p) {
+  vec2 i = floor(p), f = p - i;
+  vec2 s = f * f * f * (f * (f * 6.0 - 15.0) + 10.0);
+  highp ivec3 c = ivec3(ivec2(i), 0);
+  return mix(mix(phoriaUnit(phoriaCell(c)), phoriaUnit(phoriaCell(c + ivec3(1, 0, 0))), s.x),
+    mix(phoriaUnit(phoriaCell(c + ivec3(0, 1, 0))), phoriaUnit(phoriaCell(c + ivec3(1, 1, 0))), s.x), s.y);
+}
+
+// simplex: a corner's share of the value and the gradient - t^4 times the gradient's ramp, falling
+// to nothing at the corner's reach
+vec2 phoriaGrad2(highp ivec2 c) {
+  float a = phoriaUnit(phoriaCell(ivec3(c, 7))) * 6.28318530718;
+  return vec2(cos(a), sin(a));
+}
+void phoriaCorner2(vec2 x, highp ivec2 c, inout float n, inout vec2 d) {
+  float t = 0.5 - dot(x, x);
+  if (t <= 0.0) return;
+  vec2 g = phoriaGrad2(c);
+  float t2 = t * t, gx = dot(g, x);
+  n += t2 * t2 * gx;
+  d += t2 * t2 * g - 8.0 * t2 * t * gx * x;
+}
+vec3 snoised(vec2 p) {
+  const float F = 0.366025403784, G = 0.211324865405;
+  vec2 i = floor(p + (p.x + p.y) * F);
+  vec2 x0 = p - i + (i.x + i.y) * G;
+  vec2 o = x0.x > x0.y ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  highp ivec2 c = ivec2(i);
+  float n = 0.0;
+  vec2 d = vec2(0.0);
+  phoriaCorner2(x0, c, n, d);
+  phoriaCorner2(x0 - o + G, c + ivec2(o), n, d);
+  phoriaCorner2(x0 - 1.0 + 2.0 * G, c + 1, n, d);
+  // unit gradients peak near 1/70: scaled to -1-1, then to 0-1
+  return vec3(0.5 + 35.0 * n, 35.0 * d);
+}
+float snoise(vec2 p) { return snoised(p).x; }
+
+const vec3 PHORIA_EDGES[12] = vec3[12](vec3(1, 1, 0), vec3(-1, 1, 0), vec3(1, -1, 0), vec3(-1, -1, 0),
+  vec3(1, 0, 1), vec3(-1, 0, 1), vec3(1, 0, -1), vec3(-1, 0, -1), vec3(0, 1, 1), vec3(0, -1, 1), vec3(0, 1, -1), vec3(0, -1, -1));
+void phoriaCorner3(vec3 x, highp ivec3 c, inout float n, inout vec3 d) {
+  float t = 0.6 - dot(x, x);
+  if (t <= 0.0) return;
+  vec3 g = PHORIA_EDGES[phoriaCell(c) % 12u];
+  float t2 = t * t, gx = dot(g, x);
+  n += t2 * t2 * gx;
+  d += t2 * t2 * g - 8.0 * t2 * t * gx * x;
+}
+vec4 snoised(vec3 p) {
+  const float F = 1.0 / 3.0, G = 1.0 / 6.0;
+  vec3 i = floor(p + dot(p, vec3(F)));
+  vec3 x0 = p - i + dot(i, vec3(G));
+  vec3 g = step(x0.yzx, x0.xyz), l = 1.0 - g;
+  vec3 i1 = min(g, l.zxy), i2 = max(g, l.zxy);
+  highp ivec3 c = ivec3(i);
+  float n = 0.0;
+  vec3 d = vec3(0.0);
+  phoriaCorner3(x0, c, n, d);
+  phoriaCorner3(x0 - i1 + G, c + ivec3(i1), n, d);
+  phoriaCorner3(x0 - i2 + 2.0 * G, c + ivec3(i2), n, d);
+  phoriaCorner3(x0 - 1.0 + 3.0 * G, c + 1, n, d);
+  // edge gradients peak near 1/32: scaled to -1-1, then to 0-1
+  return vec4(0.5 + 16.0 * n, 16.0 * d);
+}
+float snoise(vec3 p) { return snoised(p).x; }
+
+// fbm: each octave turned (so grids don't line up into a visible lattice), scaled by 2.03 and moved
+// on, its amplitude halved; the sum divided by the amplitudes, so 0-1 like the noise
+const mat2 PHORIA_TURN2 = mat2(0.8, 0.6, -0.6, 0.8);
+const mat3 PHORIA_TURN3 = mat3(0.00, 0.80, 0.60, -0.80, 0.36, -0.48, -0.60, -0.48, 0.64);
+float vfbm(vec2 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) { v += a * vnoise(p); sum += a; p = PHORIA_TURN2 * p * 2.03 + 17.0; a *= 0.5; }
+  return v / sum;
+}
+float vfbm(vec3 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) { v += a * vnoise(p); sum += a; p = PHORIA_TURN3 * p * 2.03 + 17.0; a *= 0.5; }
+  return v / sum;
+}
+float sfbm(vec2 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) { v += a * snoise(p); sum += a; p = PHORIA_TURN2 * p * 2.03 + 17.0; a *= 0.5; }
+  return v / sum;
+}
+float sfbm(vec3 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) { v += a * snoise(p); sum += a; p = PHORIA_TURN3 * p * 2.03 + 17.0; a *= 0.5; }
+  return v / sum;
+}
+// with the gradient: each octave's, carried back through the turns and scalings so far
+vec3 sfbmd(vec2 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  vec2 d = vec2(0.0);
+  mat2 m = mat2(1.0);
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) {
+    vec3 n = snoised(p);
+    v += a * n.x;
+    d += a * (transpose(m) * n.yz);
+    sum += a;
+    p = PHORIA_TURN2 * p * 2.03 + 17.0;
+    m = PHORIA_TURN2 * m * 2.03;
+    a *= 0.5;
+  }
+  return vec3(v, d) / sum;
+}
+vec4 sfbmd(vec3 p, int octaves) {
+  float v = 0.0, a = 0.5, sum = 0.0;
+  vec3 d = vec3(0.0);
+  mat3 m = mat3(1.0);
+  for (int i = 0; i < clamp(octaves, 1, 12); i++) {
+    vec4 n = snoised(p);
+    v += a * n.x;
+    d += a * (transpose(m) * n.yzw);
+    sum += a;
+    p = PHORIA_TURN3 * p * 2.03 + 17.0;
+    m = PHORIA_TURN3 * m * 2.03;
+    a *= 0.5;
+  }
+  return vec4(v, d) / sum;
+}
+float vfbm(vec2 p) { return vfbm(p, 5); }
+float vfbm(vec3 p) { return vfbm(p, 5); }
+float sfbm(vec2 p) { return sfbm(p, 5); }
+float sfbm(vec3 p) { return sfbm(p, 5); }
+vec3 sfbmd(vec2 p) { return sfbmd(p, 5); }
+vec4 sfbmd(vec3 p) { return sfbmd(p, 5); }
+
+// cellular noise: each unit cell's own point, from its hash; the nearest and second nearest of the
+// 3 x 3 (or 3 x 3 x 3) cells round p - F1, F2 - and the nearest cell's own random number
+vec3 voronoi(vec2 p) {
+  vec2 i = floor(p), f = p - i;
+  highp ivec2 c = ivec2(i);
+  float f1 = 8.0, f2 = 8.0, id = 0.0;
+  for (int y = -1; y <= 1; y++) {
+    for (int x = -1; x <= 1; x++) {
+      highp uint h = phoriaCell(ivec3(c + ivec2(x, y), 11));
+      vec2 o = vec2(float(x), float(y)) + vec2(phoriaUnit(h), phoriaUnit(phoriaMix(h ^ 0x68e31da4u))) - f;
+      float d = dot(o, o);
+      if (d < f1) { f2 = f1; f1 = d; id = phoriaUnit(phoriaMix(h + 0x1b56c4e9u)); }
+      else if (d < f2) f2 = d;
+    }
+  }
+  return vec3(sqrt(f1), sqrt(f2), id);
+}
+vec3 voronoi(vec3 p) {
+  vec3 i = floor(p), f = p - i;
+  highp ivec3 c = ivec3(i);
+  float f1 = 8.0, f2 = 8.0, id = 0.0;
+  for (int z = -1; z <= 1; z++) {
+    for (int y = -1; y <= 1; y++) {
+      for (int x = -1; x <= 1; x++) {
+        highp uint h = phoriaCell(c + ivec3(x, y, z)) ^ 0x2545f491u;
+        h = phoriaMix(h);
+        vec3 o = vec3(float(x), float(y), float(z)) - f
+          + vec3(phoriaUnit(h), phoriaUnit(phoriaMix(h ^ 0x68e31da4u)), phoriaUnit(phoriaMix(h ^ 0xb5297a4du)));
+        float d = dot(o, o);
+        if (d < f1) { f2 = f1; f1 = d; id = phoriaUnit(phoriaMix(h + 0x1b56c4e9u)); }
+        else if (d < f2) f2 = d;
+      }
+    }
+  }
+  return vec3(sqrt(f1), sqrt(f2), id);
+}
+
+// a colour as picked (sRGB) to the linear colour hooks work in
+vec3 srgb(vec3 c) { return mix(c / 12.92, pow((c + 0.055) / 1.055, vec3(2.4)), step(vec3(0.04045), c)); }
+// hue, saturation and value 0-1 to a linear colour - the colour a colour picker shows
+vec3 hsv2rgb(vec3 hsv) {
+  vec3 k = clamp(abs(mod(hsv.x * 6.0 + vec3(0.0, 4.0, 2.0), 6.0) - 3.0) - 1.0, 0.0, 1.0);
+  return srgb(hsv.z * mix(vec3(1.0), k, hsv.y));
+}
+vec3 hsv2rgb(float h, float s, float v) { return hsv2rgb(vec3(h, s, v)); }
+// a cosine palette (Quilez): a + b cos(2 pi (c t + d)), its four vectors as picked; a linear colour
+vec3 palette(float t, vec3 a, vec3 b, vec3 c, vec3 d) { return srgb(clamp(a + b * cos(6.28318530718 * (c * t + d)), 0.0, 1.0)); }
+// how edge-on a surface is seen: 0 facing the camera, 1 side on, sharpened by the power - rim light
+float fresnel(vec3 normal, vec3 position, float power) {
+  vec3 v = normalize(cameraPosition - position);
+  return pow(1.0 - clamp(abs(dot(normalize(normal), v)), 0.0, 1.0), power);
+}
+// turning: rotate2(a) * v anticlockwise by a radians; rotate3(axis, a) * v about an axis
+mat2 rotate2(float a) { float s = sin(a), c = cos(a); return mat2(c, s, -s, c); }
+mat3 rotate3(vec3 axis, float a) {
+  vec3 u = normalize(axis);
+  float s = sin(a), c = cos(a), t = 1.0 - c;
+  return mat3(t * u.x * u.x + c, t * u.x * u.y + s * u.z, t * u.x * u.z - s * u.y,
+    t * u.x * u.y - s * u.z, t * u.y * u.y + c, t * u.y * u.z + s * u.x,
+    t * u.x * u.z + s * u.y, t * u.y * u.z - s * u.x, t * u.z * u.z + c);
+}
+// x from one range to another, not clamped
+float remap(float x, float a, float b, float c, float d) { return c + (x - a) * (d - c) / (b - a); }
+vec2 remap(vec2 x, float a, float b, float c, float d) { return c + (x - a) * (d - c) / (b - a); }
+vec3 remap(vec3 x, float a, float b, float c, float d) { return c + (x - a) * (d - c) / (b - a); }
+// clamped to 0-1, as HLSL has it
+float saturate(float x) { return clamp(x, 0.0, 1.0); }
+vec2 saturate(vec2 x) { return clamp(x, 0.0, 1.0); }
+vec3 saturate(vec3 x) { return clamp(x, 0.0, 1.0); }
+vec4 saturate(vec4 x) { return clamp(x, 0.0, 1.0); }
+`
+
+// a hook's own lines are numbered from 1 in a source string of their own, so compile errors point
+// at the line of the hook, not of the generated shader
+export const HOOK_SOURCE_NUMBERS = { vertex: 101, fragment: 102, lit: 103 }
+
+/**
+ * Vertex and fragment source for a kind of drawable, or a pass's own pair, with a set of feature
+ * defines - and a material's shader hooks, when it has them.
  * @param {ShaderKind | [string, string]} kind
  * @param {string[]} defines e.g. ['LIT', 'MAP']
+ * @param {HookSource | null} [hooks]
  * @returns {[string, string]}
  */
-export function shaderSource(kind, defines) {
+export function shaderSource(kind, defines, hooks = null) {
   const header = `#version 300 es\n${defines.map((d) => `#define ${d}\n`).join('')}`
   const [vs, fs] = typeof kind === 'string' ? SOURCES[kind] : kind
-  return [header + vs, header + fs]
+  if (!hooks) return [header + vs, header + fs]
+  const first = 2 + defines.length
+  return [header + splice(vs, hooks, first), header + splice(fs, hooks, first)]
+}
+
+/** @param {string} source @param {HookSource} hooks @param {number} first the line number of the source's first line */
+function splice(source, hooks, first) {
+  return source.split('\n').map((line, i) => {
+    const at = /^\s*\/\/@hook (\w+)$/.exec(line)
+    if (!at) return line
+    const part = /** @type {keyof HookSource} */ (at[1])
+    // the shader's own numbering carries on after the hook as if it weren't there
+    const resume = `#line ${first + i + 1} 0`
+    if (part === 'uniforms') return `${hooks.uniforms}\n${hooks.helpers ?? ''}\n${resume}`
+    return `#line 1 ${HOOK_SOURCE_NUMBERS[part]}\n${hooks[part]}\n${resume}`
+  }).join('\n')
 }