@chromatic-coherence/generative-engine 1.4.0 → 1.6.0

package/README.md

@@ -127,9 +127,25 @@ whole flock (a wandering heart, lobes that split and merge, a ripple phase, flap
 wings) is evaluated in the vertex stage from time alone. Ten thousand birds, zero CPU.
 The instance matrices are the shared flock frame — place, scale and steer it whole.
 
+## Real water & planar reflections (v1.5)
+
+`w.water = { on, level, size, hue, amp, distort, alpha }` — one water table per world.
+The scene renders a second time through the reflected camera (solids and every instanced
+batch, GPU flocks included), clipped at the plane; the surface is a wave-displaced grid
+sampling that reflection in screen space with a fresnel blend. The table fills wherever
+the ground dips below `level` — carve a basin and it becomes a lake that reflects the sky.
+
+## Skeletal figures (v1.6)
+
+Bones, grown from code like everything else — no asset pipeline. `humanoid()` and
+`quadruped()` build rigged figures (procedural segments bound to a small skeleton);
+`w.figure(rig, opts)` uploads one and returns a handle; `fig.pose(walkPose(t))` bends it
+in the vertex stage — scene, shadows and water reflections alike. `walkPose` / `trotPose`
+ship as procedural cycles; `composePose` takes any per-joint rotations you write.
+
 ## Roadmap
 
-Planar mirrors · real water · skeletal figures. The chart editions stay lean.
+The engine's four founding frontiers are landed. What comes next, the scenes will ask for. The chart editions stay lean.
 
 ## Licence
 

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from "./math.js";
 export * from "./geometry.js";
 export * from "./world.js";
 export * from "./objectives.js";
+export * from "./skeletal.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./math.js";
 export * from "./geometry.js";
 export * from "./world.js";
 export * from "./objectives.js";
+export * from "./skeletal.js";

package/dist/shaders.d.ts

@@ -1,7 +1,9 @@
 export declare const FACE_VS = "#version 300 es\nin vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;\nin vec3 aPos2; in vec3 aNorm2;\nuniform mat4 uVP; uniform mat4 uSVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;\nout float vGA; out float vBlood;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  float w = uMW[g];\n  vec3 p = mix(aPos, aPos2, w), n = mix(aNorm, aNorm2, w);\n  vec4 wp = uGM[g] * vec4(p, 1.0);\n  vPos = wp.xyz; vNorm = uNM[g] * n; vCol = aCol; vGA = uGA[g]; vBlood = aBlood;\n  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;\n}";
-export declare const FACE_FS = "#version 300 es\nprecision highp float;\nin vec3 vPos; in vec3 vNorm; in vec4 vCol; in float vZ; in vec4 vSh;\nin float vGA; in float vBlood;\nuniform vec3 uLdir; uniform float uAmb; uniform float uDif; uniform float uSigned;\nuniform vec3 uLp[8]; uniform float uLi[8]; uniform float uLf[8]; uniform int uLn;\nuniform vec3 uCam; uniform float uFogK; uniform float uSpec; uniform vec3 uBg;\nuniform vec3 uSkyC; uniform vec3 uGroundC; uniform float uPulse;\nuniform float uShadowOn; uniform float uShadowSoft; uniform float uShadowBias;\nuniform lowp sampler2DShadow uShadow; uniform float uShadowPx;\nout vec4 fragColor;\nfloat h3(vec3 p){ return fract(sin(dot(p, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }\nfloat vnoise(vec3 p){ vec3 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(h3(i), h3(i + vec3(1,0,0)), f.x), mix(h3(i + vec3(0,1,0)), h3(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(h3(i + vec3(0,0,1)), h3(i + vec3(1,0,1)), f.x), mix(h3(i + vec3(0,1,1)), h3(i + vec3(1,1,1)), f.x), f.y), f.z); }\nfloat shadowFactor(){\n  vec3 pr = vSh.xyz / vSh.w * 0.5 + 0.5;\n  if (pr.x < 0.0 || pr.x > 1.0 || pr.y < 0.0 || pr.y > 1.0 || pr.z > 1.0) return 1.0;\n  float ref = pr.z - uShadowBias;\n  // 3x3 taps over a hardware-compared (LINEAR sampler2DShadow => free 2x2 PCF each) map\n  float s = 0.0;\n  for (int sy = -1; sy <= 1; sy++)\n    for (int sx = -1; sx <= 1; sx++)\n      s += texture(uShadow, vec3(pr.xy + vec2(float(sx), float(sy)) * uShadowPx * uShadowSoft, ref));\n  s /= 9.0;\n  return 0.35 + 0.65 * s;\n}\nvoid main(){\n  vec3 n = normalize(vNorm);\n  vec3 V = normalize(uCam - vPos);\n  float skin = clamp(vBlood * 5.0, 0.0, 1.0);\n  { // procedural micro-relief: perturb the shading normal by a fine noise gradient\n    float bs = 5.5, e = 0.12, n0 = vnoise(vPos * bs);\n    vec3 g = vec3(vnoise(vPos * bs + vec3(e, 0.0, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, e, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, 0.0, e)) - n0) / e;\n    n = normalize(n - g * (0.10 + 0.30 * skin));\n  }\n  float d = dot(n, normalize(uLdir));\n  float shade = uAmb + uDif * mix(abs(d), max(d, 0.0), uSigned);\n  float spec = 0.0;\n  float sh = uShadowOn > 0.5 ? shadowFactor() : 1.0;\n  for (int i = 0; i < 8; i++) { if (i >= uLn) break;\n    vec3 v = uLp[i] - vPos; float d2 = dot(v, v); vec3 L = v * inversesqrt(d2 + 1e-4);\n    float lam = dot(n, L); lam = mix(abs(lam), max(lam, 0.0), uSigned);\n    float fall = 1.0 / (1.0 + d2 / (uLf[i] * uLf[i]));\n    float k = (i == 0) ? sh : 1.0;\n    shade += uLi[i] * lam * fall * k;\n    // GGX microfacet + Fresnel \u2014 roughness from the face's gloss (colour alpha slot)\n    vec3 H = normalize(L + V);\n    float nh = max(dot(n, H), 0.0);\n    float rough = clamp(1.0 - vCol.a, 0.08, 1.0), a2 = rough * rough; a2 = a2 * a2;\n    float dnm = nh * nh * (a2 - 1.0) + 1.0;\n    float ggx = a2 / (3.14159 * dnm * dnm);\n    float fres = 0.04 + 0.96 * pow(1.0 - max(dot(H, V), 0.0), 5.0);\n    spec += uLi[i] * min(ggx, 6.0) * fres * fall * k * 0.16;\n  }\n  // coloured hemispheric ambient: cool from above, warm from below\n  vec3 tint = mix(uGroundC, uSkyC, n.y * 0.5 + 0.5);\n  vec3 lit = vCol.rgb * (uAmb * tint + vec3(shade - uAmb));\n  // the perfusion term: blood near the surface changes how it meets the light\n  float b = clamp(vBlood + uPulse * vBlood * 6.0, 0.0, 1.0);\n  lit *= mix(vec3(1.0), vec3(1.07, 0.95, 0.94), b);\n  lit += vec3(0.62, 0.06, 0.08) * (b * 0.20 * (1.0 - abs(d)));\n  // pore noise, only where there is blood (skin, not cloth)\n  float pore = vnoise(vPos * 2.4) * 0.6 + vnoise(vPos * 6.0) * 0.4;\n  lit *= 1.0 + (pore - 0.5) * 0.09 * skin;\n  // subsurface rim: grazing light bleeds through thin tissue, warm\n  float fres = pow(1.0 - clamp(dot(n, V), 0.0, 1.0), 3.0);\n  lit += vec3(0.55, 0.09, 0.10) * fres * skin * (0.28 + 0.5 * b);\n  float fog = clamp(uFogK / vZ, 0.08, 1.0);\n  vec3 outC = lit + vec3(1.0) * spec * uSpec * vCol.a;\n  // fog and fades resolve toward the REAL background colour (the engine owns its ground)\n  fragColor = vec4(mix(uBg, outC, fog * vGA), 1.0);\n}";
+export declare const FACE_FS = "#version 300 es\nprecision highp float;\nin vec3 vPos; in vec3 vNorm; in vec4 vCol; in float vZ; in vec4 vSh;\nin float vGA; in float vBlood;\nuniform vec3 uLdir; uniform float uAmb; uniform float uDif; uniform float uSigned;\nuniform vec3 uLp[8]; uniform float uLi[8]; uniform float uLf[8]; uniform int uLn;\nuniform vec3 uCam; uniform float uFogK; uniform float uSpec; uniform vec3 uBg;\nuniform vec3 uSkyC; uniform vec3 uGroundC; uniform float uPulse;\nuniform float uShadowOn; uniform float uShadowSoft; uniform float uShadowBias;\nuniform lowp sampler2DShadow uShadow; uniform float uShadowPx;\nuniform float uClipY;\nout vec4 fragColor;\nfloat h3(vec3 p){ return fract(sin(dot(p, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }\nfloat vnoise(vec3 p){ vec3 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(h3(i), h3(i + vec3(1,0,0)), f.x), mix(h3(i + vec3(0,1,0)), h3(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(h3(i + vec3(0,0,1)), h3(i + vec3(1,0,1)), f.x), mix(h3(i + vec3(0,1,1)), h3(i + vec3(1,1,1)), f.x), f.y), f.z); }\nfloat shadowFactor(){\n  vec3 pr = vSh.xyz / vSh.w * 0.5 + 0.5;\n  if (pr.x < 0.0 || pr.x > 1.0 || pr.y < 0.0 || pr.y > 1.0 || pr.z > 1.0) return 1.0;\n  float ref = pr.z - uShadowBias;\n  // 3x3 taps over a hardware-compared (LINEAR sampler2DShadow => free 2x2 PCF each) map\n  float s = 0.0;\n  for (int sy = -1; sy <= 1; sy++)\n    for (int sx = -1; sx <= 1; sx++)\n      s += texture(uShadow, vec3(pr.xy + vec2(float(sx), float(sy)) * uShadowPx * uShadowSoft, ref));\n  s /= 9.0;\n  return 0.35 + 0.65 * s;\n}\nvoid main(){\n  if (vPos.y < uClipY) discard;   // W11: the reflection pass clips at the water plane\n  vec3 n = normalize(vNorm);\n  vec3 V = normalize(uCam - vPos);\n  float skin = clamp(vBlood * 5.0, 0.0, 1.0);\n  { // procedural micro-relief: perturb the shading normal by a fine noise gradient\n    float bs = 5.5, e = 0.12, n0 = vnoise(vPos * bs);\n    vec3 g = vec3(vnoise(vPos * bs + vec3(e, 0.0, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, e, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, 0.0, e)) - n0) / e;\n    n = normalize(n - g * (0.10 + 0.30 * skin));\n  }\n  float d = dot(n, normalize(uLdir));\n  float shade = uAmb + uDif * mix(abs(d), max(d, 0.0), uSigned);\n  float spec = 0.0;\n  float sh = uShadowOn > 0.5 ? shadowFactor() : 1.0;\n  for (int i = 0; i < 8; i++) { if (i >= uLn) break;\n    vec3 v = uLp[i] - vPos; float d2 = dot(v, v); vec3 L = v * inversesqrt(d2 + 1e-4);\n    float lam = dot(n, L); lam = mix(abs(lam), max(lam, 0.0), uSigned);\n    float fall = 1.0 / (1.0 + d2 / (uLf[i] * uLf[i]));\n    float k = (i == 0) ? sh : 1.0;\n    shade += uLi[i] * lam * fall * k;\n    // GGX microfacet + Fresnel \u2014 roughness from the face's gloss (colour alpha slot)\n    vec3 H = normalize(L + V);\n    float nh = max(dot(n, H), 0.0);\n    float rough = clamp(1.0 - vCol.a, 0.08, 1.0), a2 = rough * rough; a2 = a2 * a2;\n    float dnm = nh * nh * (a2 - 1.0) + 1.0;\n    float ggx = a2 / (3.14159 * dnm * dnm);\n    float fres = 0.04 + 0.96 * pow(1.0 - max(dot(H, V), 0.0), 5.0);\n    spec += uLi[i] * min(ggx, 6.0) * fres * fall * k * 0.16;\n  }\n  // coloured hemispheric ambient: cool from above, warm from below\n  vec3 tint = mix(uGroundC, uSkyC, n.y * 0.5 + 0.5);\n  vec3 lit = vCol.rgb * (uAmb * tint + vec3(shade - uAmb));\n  // the perfusion term: blood near the surface changes how it meets the light\n  float b = clamp(vBlood + uPulse * vBlood * 6.0, 0.0, 1.0);\n  lit *= mix(vec3(1.0), vec3(1.07, 0.95, 0.94), b);\n  lit += vec3(0.62, 0.06, 0.08) * (b * 0.20 * (1.0 - abs(d)));\n  // pore noise, only where there is blood (skin, not cloth)\n  float pore = vnoise(vPos * 2.4) * 0.6 + vnoise(vPos * 6.0) * 0.4;\n  lit *= 1.0 + (pore - 0.5) * 0.09 * skin;\n  // subsurface rim: grazing light bleeds through thin tissue, warm\n  float fres = pow(1.0 - clamp(dot(n, V), 0.0, 1.0), 3.0);\n  lit += vec3(0.55, 0.09, 0.10) * fres * skin * (0.28 + 0.5 * b);\n  float fog = clamp(uFogK / vZ, 0.08, 1.0);\n  vec3 outC = lit + vec3(1.0) * spec * uSpec * vCol.a;\n  // fog and fades resolve toward the REAL background colour (the engine owns its ground)\n  fragColor = vec4(mix(uBg, outC, fog * vGA), 1.0);\n}";
 export declare const FACE_INST_VS = "#version 300 es\nin vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;\nin vec3 aPos2; in vec3 aNorm2;\nin vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3; in vec4 aIP;\nuniform mat4 uVP; uniform mat4 uSVP; uniform float uT; uniform vec3 uWindDir;\nuniform float uFlight;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;\nout float vGA; out float vBlood;\n// W10 FLIGHT: aIP = (a0, r0, ph, lobe). The flock's heart wanders, three lobes orbit\n// it breathing apart and back, each bird orbits its lobe with a ripple phase \u2014 the\n// murmuration, evaluated per vertex from uT alone. The instance matrix is the flock\n// frame (shared), so one batch = one flock you can place, scale and steer.\nvec3 flightPos(vec4 ip, float t){\n  float a0 = ip.x, r0 = ip.y, ph = ip.z, lobe = ip.w;\n  float cx = sin(t * 0.11) * 700.0, cz = -500.0 + cos(t * 0.07) * 380.0;\n  float cy = 430.0 + sin(t * 0.16) * 110.0;\n  float spread = 180.0 + 140.0 * sin(t * 0.21 + 1.3);\n  float la = t * 0.34 + lobe * 2.0944;\n  vec3 lc = vec3(cx + cos(la) * spread, cy + sin(la * 2.0 + lobe) * 60.0, cz + sin(la) * spread * 0.7);\n  float aa = a0 + t * (0.5 + 0.25 * sin(ph));\n  float wob = sin(t * 1.1 + ph) * 0.35;\n  float rr = r0 * (0.75 + 0.25 * sin(t * 0.5 + ph + lobe));\n  return lc + vec3(cos(aa) * rr, sin(aa * 1.7 + ph) * rr * 0.32 + wob * 24.0, sin(aa) * rr * (0.55 + wob * 0.2));\n}\nvec3 flightLocal(vec3 pl, vec4 ip, float t){\n  float aa = ip.x + t * (0.5 + 0.25 * sin(ip.z));\n  pl.y += sin(t * 11.0 + ip.z * 3.0) * abs(pl.z) * 0.9;   // the flap, growing to the wingtips\n  float ca = cos(aa + 1.5708), sa = sin(aa + 1.5708);      // heading = the orbit tangent\n  return vec3(pl.x * ca - pl.z * sa, pl.y, pl.x * sa + pl.z * ca);\n}\nvoid main(){\n  int g = int(aGrp + 0.5);\n  float w = uMW[g];\n  mat4 inst = mat4(aI0, aI1, aI2, aI3);\n  vec3 p = mix(aPos, aPos2, w), n = mix(aNorm, aNorm2, w);\n  if (uFlight > 0.5) {\n    p = flightPos(aIP, uT) + flightLocal(p, aIP, uT);\n  } else {\n    // W9 GPU WIND: per-instance (phase, freq, amp); displacement grows with height,\n    // plus a second harmonic so the sway breathes instead of ticking\n    float sw = sin(uT * aIP.y + aIP.x) + 0.5 * sin(uT * aIP.y * 2.3 + aIP.x * 1.7);\n    p += uWindDir * (sw * aIP.z * max(p.y, 0.0));\n  }\n  vec4 wp = uGM[g] * (inst * vec4(p, 1.0));\n  vPos = wp.xyz; vNorm = uNM[g] * (mat3(inst) * n); vCol = aCol; vGA = uGA[g]; vBlood = aBlood;\n  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;\n}";
 export declare const DEPTH_INST_VS = "#version 300 es\nin vec3 aPos; in float aGrp; in vec3 aPos2;\nin vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3; in vec4 aIP;\nuniform mat4 uVP; uniform float uT; uniform vec3 uWindDir;\nuniform float uFlight;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\n// W10 FLIGHT: aIP = (a0, r0, ph, lobe). The flock's heart wanders, three lobes orbit\n// it breathing apart and back, each bird orbits its lobe with a ripple phase \u2014 the\n// murmuration, evaluated per vertex from uT alone. The instance matrix is the flock\n// frame (shared), so one batch = one flock you can place, scale and steer.\nvec3 flightPos(vec4 ip, float t){\n  float a0 = ip.x, r0 = ip.y, ph = ip.z, lobe = ip.w;\n  float cx = sin(t * 0.11) * 700.0, cz = -500.0 + cos(t * 0.07) * 380.0;\n  float cy = 430.0 + sin(t * 0.16) * 110.0;\n  float spread = 180.0 + 140.0 * sin(t * 0.21 + 1.3);\n  float la = t * 0.34 + lobe * 2.0944;\n  vec3 lc = vec3(cx + cos(la) * spread, cy + sin(la * 2.0 + lobe) * 60.0, cz + sin(la) * spread * 0.7);\n  float aa = a0 + t * (0.5 + 0.25 * sin(ph));\n  float wob = sin(t * 1.1 + ph) * 0.35;\n  float rr = r0 * (0.75 + 0.25 * sin(t * 0.5 + ph + lobe));\n  return lc + vec3(cos(aa) * rr, sin(aa * 1.7 + ph) * rr * 0.32 + wob * 24.0, sin(aa) * rr * (0.55 + wob * 0.2));\n}\nvec3 flightLocal(vec3 pl, vec4 ip, float t){\n  float aa = ip.x + t * (0.5 + 0.25 * sin(ip.z));\n  pl.y += sin(t * 11.0 + ip.z * 3.0) * abs(pl.z) * 0.9;   // the flap, growing to the wingtips\n  float ca = cos(aa + 1.5708), sa = sin(aa + 1.5708);      // heading = the orbit tangent\n  return vec3(pl.x * ca - pl.z * sa, pl.y, pl.x * sa + pl.z * ca);\n}\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vec3 p = mix(aPos, aPos2, uMW[g]);\n  if (uFlight > 0.5) {\n    p = flightPos(aIP, uT) + flightLocal(p, aIP, uT);\n  } else {\n    float sw = sin(uT * aIP.y + aIP.x) + 0.5 * sin(uT * aIP.y * 2.3 + aIP.x * 1.7);\n    p += uWindDir * (sw * aIP.z * max(p.y, 0.0));\n  }\n  gl_Position = uVP * (uGM[g] * (mat4(aI0, aI1, aI2, aI3) * vec4(p, 1.0)));\n}";
+export declare const FACE_SKIN_VS = "#version 300 es\nin vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;\nin vec3 aPos2; in vec3 aNorm2; in float aBone;\nuniform mat4 uVP; uniform mat4 uSVP; uniform mat4 uBones[16];\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;\nout float vGA; out float vBlood;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  mat4 bm = uBones[int(aBone + 0.5)];\n  vec3 p = (bm * vec4(aPos, 1.0)).xyz;\n  vec3 n = mat3(bm) * aNorm;\n  vec4 wp = uGM[g] * vec4(p, 1.0);\n  vPos = wp.xyz; vNorm = uNM[g] * n; vCol = aCol; vGA = uGA[g]; vBlood = aBlood;\n  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;\n}";
+export declare const DEPTH_SKIN_VS = "#version 300 es\nin vec3 aPos; in float aGrp; in float aBone;\nuniform mat4 uVP; uniform mat4 uBones[16];\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nvoid main(){\n  int g = int(aGrp + 0.5);\n  gl_Position = uVP * (uGM[g] * (uBones[int(aBone + 0.5)] * vec4(aPos, 1.0)));\n}";
 export declare const DEPTH_VS = "#version 300 es\nin vec3 aPos; in float aGrp; in vec3 aPos2;\nuniform mat4 uVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vec3 p = mix(aPos, aPos2, uMW[g]);\n  gl_Position = uVP * (uGM[g] * vec4(p, 1.0));\n}";
 export declare const DEPTH_FS = "#version 300 es\nprecision mediump float;\nvoid main(){}";
 export declare const LINE_VS = "#version 300 es\nin vec3 aPos; in vec4 aCol; in float aGrp;\nuniform mat4 uVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec4 vCol; out float vZ; out float vGA;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vCol = aCol; vGA = uGA[g];\n  vec4 p = uVP * (uGM[g] * vec4(aPos, 1.0)); vZ = p.w; gl_Position = p;\n}";
@@ -18,4 +20,6 @@ export declare const AOBLUR_FS = "#version 300 es\nprecision mediump float;\nin
 export declare const COMPOSITE_FS = "#version 300 es\nprecision mediump float;\nin vec2 vUv;\nuniform sampler2D uScene; uniform sampler2D uBloom; uniform sampler2D uAO;\nuniform float uBloomStr; uniform float uAOStr;\nuniform float uFilm; uniform float uGrade; uniform float uVig; uniform float uInk;\nout vec4 fragColor;\nvoid main(){\n  vec3 c = texture(uScene, vUv).rgb;\n  c *= mix(1.0, texture(uAO, vUv).r, uAOStr);\n  c += texture(uBloom, vUv).rgb * uBloomStr;\n  if (uFilm > 0.5) { // ACES-ish filmic: highlights roll off instead of clipping\n    c = (c * (2.51 * c + 0.03)) / (c * (2.43 * c + 0.59) + 0.14);\n  }\n  c = clamp(c, 0.0, 1.0);\n  if (uGrade > 0.5) { // violet-cool shadows, warm highlights\n    float luma = dot(c, vec3(0.299, 0.587, 0.114));\n    c *= mix(vec3(0.85, 0.83, 1.07), vec3(1.07, 0.99, 0.92), smoothstep(0.12, 0.72, luma));\n    c = clamp(c, 0.0, 1.0);\n  }\n  if (uVig > 0.0) { // cinematic vignette, in the composite now (off the overlay)\n    vec2 q = vUv - vec2(0.5, 0.54);\n    float r = smoothstep(0.35, 0.9, length(q * vec2(1.15, 1.0)));\n    vec3 dk = uInk > 0.5 ? vec3(0.20, 0.19, 0.30) : vec3(0.024, 0.016, 0.055);\n    c = mix(c, dk, uVig * r * (uInk > 0.5 ? 0.3 : 1.0));\n  }\n  fragColor = vec4(c, 1.0);\n}";
 export declare const DOF_FS = "#version 300 es\nprecision highp float;\nin vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;\nuniform float uNear; uniform float uFar; uniform float uFocus; uniform float uRange;\nuniform float uMaxBlur; uniform vec2 uPx;\nout vec4 fragColor;\nfloat lin(float d){ return uNear * uFar / (uFar - d * (uFar - uNear)); }\nconst vec2 DISC[12] = vec2[](\n  vec2(-0.326, -0.406), vec2(-0.840, -0.074), vec2(-0.696, 0.457), vec2(-0.203, 0.621),\n  vec2(0.962, -0.195), vec2(0.473, -0.480), vec2(0.519, 0.767), vec2(0.185, -0.893),\n  vec2(0.507, 0.064), vec2(0.896, 0.412), vec2(-0.322, -0.933), vec2(-0.792, -0.598));\nvoid main(){\n  float z = lin(texture(uDepth, vUv).r);\n  float coc = clamp(abs(z - uFocus) / max(1.0, uRange), 0.0, 1.0) * uMaxBlur;\n  vec3 acc = texture(uTex, vUv).rgb;\n  float wsum = 1.0;\n  for (int i = 0; i < 12; i++) {\n    vec2 off = DISC[i] * coc * uPx;\n    // a sharp (in-focus) neighbour must not bleed into a blurred one: weight each tap\n    // by ITS OWN CoC so foreground focus stays crisp against a soft background\n    float zt = lin(texture(uDepth, vUv + off).r);\n    float ct = clamp(abs(zt - uFocus) / max(1.0, uRange), 0.0, 1.0);\n    float w = 0.25 + 0.75 * ct;\n    acc += texture(uTex, vUv + off).rgb * w;\n    wsum += w;\n  }\n  fragColor = vec4(acc / wsum, 1.0);\n}";
 export declare const MOBLUR_FS = "#version 300 es\nprecision highp float;\nin vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;\nuniform mat4 uInvVP; uniform mat4 uPrevVP; uniform float uStrength;\nout vec4 fragColor;\nvoid main(){\n  float d = texture(uDepth, vUv).r;\n  vec4 ndc = vec4(vUv * 2.0 - 1.0, d * 2.0 - 1.0, 1.0);\n  vec4 wp = uInvVP * ndc; wp /= wp.w;\n  vec4 pc = uPrevVP * wp;\n  vec2 prevUv = (pc.xy / pc.w) * 0.5 + 0.5;\n  vec2 vel = (vUv - prevUv) * uStrength;\n  float vlen = length(vel);\n  if (vlen < 1e-5 || pc.w <= 0.0) { fragColor = vec4(texture(uTex, vUv).rgb, 1.0); return; }\n  vel = vlen > 0.04 ? vel * (0.04 / vlen) : vel;  // clamp the streak to 4% of the screen\n  vec3 acc = vec3(0.0);\n  for (int i = 0; i < 8; i++) {\n    float t = (float(i) / 7.0) - 0.5;\n    acc += texture(uTex, clamp(vUv + vel * t, vec2(0.001), vec2(0.999))).rgb;\n  }\n  fragColor = vec4(acc / 8.0, 1.0);\n}";
+export declare const WATER_VS = "#version 300 es\nin vec3 aPos;\nuniform mat4 uVP; uniform float uT; uniform float uLevel; uniform float uAmp;\nout vec3 vW; out vec3 vN; out float vZ;\nvoid main(){\n  vec3 p = aPos;\n  float y = sin(p.x * 0.020 + uT * 1.3) + sin(p.z * 0.017 + uT * 1.1)\n          + 0.5 * sin((p.x + p.z) * 0.031 + uT * 2.2);\n  float dx = 0.020 * cos(p.x * 0.020 + uT * 1.3) + 0.0155 * cos((p.x + p.z) * 0.031 + uT * 2.2);\n  float dz = 0.017 * cos(p.z * 0.017 + uT * 1.1) + 0.0155 * cos((p.x + p.z) * 0.031 + uT * 2.2);\n  p.y = uLevel + y * uAmp;\n  vW = p; vN = normalize(vec3(-dx * uAmp, 1.0, -dz * uAmp));\n  vec4 cp = uVP * vec4(p, 1.0); vZ = cp.w; gl_Position = cp;\n}";
+export declare const WATER_FS = "#version 300 es\nprecision highp float;\nin vec3 vW; in vec3 vN; in float vZ;\nuniform sampler2D uRefl; uniform vec2 uRes; uniform vec3 uTint; uniform vec3 uCam;\nuniform float uFogK; uniform vec3 uBg; uniform float uDistort; uniform float uAlpha;\nout vec4 fragColor;\nvoid main(){\n  vec2 uv = gl_FragCoord.xy / uRes;\n  vec3 refl = texture(uRefl, clamp(uv + vN.xz * uDistort, 0.001, 0.999)).rgb;\n  vec3 V = normalize(uCam - vW);\n  float fres = 0.06 + 0.94 * pow(1.0 - max(dot(vN, V), 0.0), 3.0);\n  vec3 c = mix(uTint, refl, clamp(0.35 + fres * 0.6, 0.0, 0.95));\n  float fog = clamp(uFogK / vZ, 0.08, 1.0);\n  fragColor = vec4(mix(uBg, c, fog), uAlpha);\n}";
 export declare const FXAA_FS = "#version 300 es\nprecision mediump float;\nin vec2 vUv; uniform sampler2D uTex; uniform vec2 uPx;\nout vec4 fragColor;\nfloat luma(vec3 c){ return dot(c, vec3(0.299, 0.587, 0.114)); }\nvoid main(){\n  vec3 cM = texture(uTex, vUv).rgb;\n  float lM = luma(cM);\n  float lN = luma(texture(uTex, vUv + vec2(0.0, -uPx.y)).rgb);\n  float lS = luma(texture(uTex, vUv + vec2(0.0, uPx.y)).rgb);\n  float lW = luma(texture(uTex, vUv + vec2(-uPx.x, 0.0)).rgb);\n  float lE = luma(texture(uTex, vUv + vec2(uPx.x, 0.0)).rgb);\n  float lMin = min(lM, min(min(lN, lS), min(lW, lE)));\n  float lMax = max(lM, max(max(lN, lS), max(lW, lE)));\n  float range = lMax - lMin;\n  if (range < max(0.0312, lMax * 0.125)) { fragColor = vec4(cM, 1.0); return; }\n  vec2 dir = normalize(vec2((lE + lS) - (lW + lN), (lN + lE) - (lS + lW)) + 1e-6);\n  vec3 a = texture(uTex, vUv + dir * uPx * 0.5).rgb;\n  vec3 b = texture(uTex, vUv - dir * uPx * 0.5).rgb;\n  fragColor = vec4(mix(cM, (a + b) * 0.5, 0.75), 1.0);\n}";

package/dist/shaders.js

@@ -31,6 +31,7 @@ uniform vec3 uCam; uniform float uFogK; uniform float uSpec; uniform vec3 uBg;
 uniform vec3 uSkyC; uniform vec3 uGroundC; uniform float uPulse;
 uniform float uShadowOn; uniform float uShadowSoft; uniform float uShadowBias;
 uniform lowp sampler2DShadow uShadow; uniform float uShadowPx;
+uniform float uClipY;
 out vec4 fragColor;
 float h3(vec3 p){ return fract(sin(dot(p, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }
 float vnoise(vec3 p){ vec3 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);
@@ -49,6 +50,7 @@ float shadowFactor(){
   return 0.35 + 0.65 * s;
 }
 void main(){
+  if (vPos.y < uClipY) discard;   // W11: the reflection pass clips at the water plane
   vec3 n = normalize(vNorm);
   vec3 V = normalize(uCam - vPos);
   float skin = clamp(vBlood * 5.0, 0.0, 1.0);
@@ -186,6 +188,30 @@ void main(){
   }
   gl_Position = uVP * (uGM[g] * (mat4(aI0, aI1, aI2, aI3) * vec4(p, 1.0)));
 }`;
+// W12 SKELETAL: rigid skinning — one bone per vertex, 16 mat4s per figure,
+// composed on the CPU (composePose) and applied here before the group transform.
+export const FACE_SKIN_VS = `#version 300 es
+in vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;
+in vec3 aPos2; in vec3 aNorm2; in float aBone;
+uniform mat4 uVP; uniform mat4 uSVP; uniform mat4 uBones[16];${GROUPS}
+out vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;
+out float vGA; out float vBlood;
+void main(){
+  int g = int(aGrp + 0.5);
+  mat4 bm = uBones[int(aBone + 0.5)];
+  vec3 p = (bm * vec4(aPos, 1.0)).xyz;
+  vec3 n = mat3(bm) * aNorm;
+  vec4 wp = uGM[g] * vec4(p, 1.0);
+  vPos = wp.xyz; vNorm = uNM[g] * n; vCol = aCol; vGA = uGA[g]; vBlood = aBlood;
+  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;
+}`;
+export const DEPTH_SKIN_VS = `#version 300 es
+in vec3 aPos; in float aGrp; in float aBone;
+uniform mat4 uVP; uniform mat4 uBones[16];${GROUPS}
+void main(){
+  int g = int(aGrp + 0.5);
+  gl_Position = uVP * (uGM[g] * (uBones[int(aBone + 0.5)] * vec4(aPos, 1.0)));
+}`;
 export const DEPTH_VS = `#version 300 es
 in vec3 aPos; in float aGrp; in vec3 aPos2;
 uniform mat4 uVP;${GROUPS}
@@ -425,6 +451,36 @@ void main(){
   }
   fragColor = vec4(acc / 8.0, 1.0);
 }`;
+// W11 WATER - a wave-displaced surface sampling the reflection pass in screen space
+export const WATER_VS = `#version 300 es
+in vec3 aPos;
+uniform mat4 uVP; uniform float uT; uniform float uLevel; uniform float uAmp;
+out vec3 vW; out vec3 vN; out float vZ;
+void main(){
+  vec3 p = aPos;
+  float y = sin(p.x * 0.020 + uT * 1.3) + sin(p.z * 0.017 + uT * 1.1)
+          + 0.5 * sin((p.x + p.z) * 0.031 + uT * 2.2);
+  float dx = 0.020 * cos(p.x * 0.020 + uT * 1.3) + 0.0155 * cos((p.x + p.z) * 0.031 + uT * 2.2);
+  float dz = 0.017 * cos(p.z * 0.017 + uT * 1.1) + 0.0155 * cos((p.x + p.z) * 0.031 + uT * 2.2);
+  p.y = uLevel + y * uAmp;
+  vW = p; vN = normalize(vec3(-dx * uAmp, 1.0, -dz * uAmp));
+  vec4 cp = uVP * vec4(p, 1.0); vZ = cp.w; gl_Position = cp;
+}`;
+export const WATER_FS = `#version 300 es
+precision highp float;
+in vec3 vW; in vec3 vN; in float vZ;
+uniform sampler2D uRefl; uniform vec2 uRes; uniform vec3 uTint; uniform vec3 uCam;
+uniform float uFogK; uniform vec3 uBg; uniform float uDistort; uniform float uAlpha;
+out vec4 fragColor;
+void main(){
+  vec2 uv = gl_FragCoord.xy / uRes;
+  vec3 refl = texture(uRefl, clamp(uv + vN.xz * uDistort, 0.001, 0.999)).rgb;
+  vec3 V = normalize(uCam - vW);
+  float fres = 0.06 + 0.94 * pow(1.0 - max(dot(vN, V), 0.0), 3.0);
+  vec3 c = mix(uTint, refl, clamp(0.35 + fres * 0.6, 0.0, 0.95));
+  float fog = clamp(uFogK / vZ, 0.08, 1.0);
+  fragColor = vec4(mix(uBg, c, fog), uAlpha);
+}`;
 // compact FXAA (luma-based, 5-tap edge blend) — runs last, on the LDR composite
 export const FXAA_FS = `#version 300 es
 precision mediump float;

package/dist/skeletal.d.ts

@@ -0,0 +1,36 @@
+import { V3 } from "./math.js";
+import { Mesh } from "./geometry.js";
+export type Bone = {
+    name: string;
+    /** parent bone index, -1 for the root */
+    parent: number;
+    /** joint position (rotations pivot here), rest pose, figure-local */
+    head: V3;
+    /** where the bone points, rest pose — children usually head here */
+    tail: V3;
+};
+/** A rigged figure: the mesh, one bone index per VERTEX, and the skeleton. */
+export type Rig = {
+    mesh: Mesh;
+    boneOf: number[];
+    bones: Bone[];
+};
+export type PoseRot = {
+    x?: number;
+    y?: number;
+    z?: number;
+};
+/** A pose: local joint rotations by bone name (radians). Missing bones rest. */
+export type Pose = Record<string, PoseRot>;
+/** Compose a pose into per-bone world matrices (figure space).
+ *  Each bone rotates about its HEAD, inside its parent's space. */
+export declare function composePose(bones: Bone[], pose: Pose): Float32Array;
+/** A humanoid: 11 bones, ~1.7 m tall by default, feet at y=0, facing +z. */
+export declare function humanoid(h?: number): Rig;
+/** A quadruped (dog-shaped): 10 bones, shoulder height h, facing +z. */
+export declare function quadruped(h?: number): Rig;
+/** The walk: phase in radians (t * cadence). Legs swing opposite, knees flex on
+ *  the back-swing, arms counter-swing, the spine counter-rotates a touch. */
+export declare function walkPose(phase: number, stride?: number): Pose;
+/** The trot: diagonal pairs move together, the tail wags, the head bobs. */
+export declare function trotPose(phase: number, stride?: number): Pose;

package/dist/skeletal.js

@@ -0,0 +1,115 @@
+// generative-engine — skeletal.ts (W12): BONES. Procedural skeletons, rigid skinning,
+// walk cycles — no asset pipeline, no files, figures grown from code like everything
+// else here. Each vertex binds to ONE bone (rigid skinning): for procedural figures the
+// segment boundaries are where joints live, so single-bone binding reads clean and the
+// whole system stays small. Max 16 bones per figure; matrices composed on the CPU
+// (16 tiny mat4 muls) and applied in the vertex stage.
+import { v3, mMul, mCompose } from "./math.js";
+import { tube, icosphere, transformMesh, mergeMesh } from "./geometry.js";
+/** Compose a pose into per-bone world matrices (figure space).
+ *  Each bone rotates about its HEAD, inside its parent's space. */
+export function composePose(bones, pose) {
+    const out = new Float32Array(bones.length * 16);
+    const world = [];
+    for (let i = 0; i < bones.length; i++) {
+        const b = bones[i];
+        const r = pose[b.name] ?? {};
+        const local = mMul(mCompose({ translate: b.head }), mMul(mCompose({ rotateX: r.x ?? 0, rotateY: r.y ?? 0, rotateZ: r.z ?? 0 }), mCompose({ translate: v3(-b.head.x, -b.head.y, -b.head.z) })));
+        const m = b.parent >= 0 ? mMul(world[b.parent], local) : local;
+        world.push(m);
+        out.set(m, i * 16);
+    }
+    return out;
+}
+/** Build a limb segment (tapered tube along a bone) bound to that bone. */
+function segment(rig, bone, a, b, r0, r1, seg = 7) {
+    const m = tube([a, b], (u) => r0 + (r1 - r0) * u, seg);
+    rig.parts.push(m);
+    for (let i = 0; i < m.pos.length / 3; i++)
+        rig.boneOf.push(bone);
+}
+function blob(rig, bone, at, r, detail = 1) {
+    const m = transformMesh(icosphere(r, detail), mCompose({ translate: at }));
+    rig.parts.push(m);
+    for (let i = 0; i < m.pos.length / 3; i++)
+        rig.boneOf.push(bone);
+}
+/** A humanoid: 11 bones, ~1.7 m tall by default, feet at y=0, facing +z. */
+export function humanoid(h = 170) {
+    const s = h / 170;
+    const hip = 92 * s, knee = 48 * s, sho = 148 * s, elb = 118 * s, neck = 158 * s;
+    const bones = [
+        { name: "pelvis", parent: -1, head: v3(0, hip, 0), tail: v3(0, hip + 20 * s, 0) }, // 0
+        { name: "spine", parent: 0, head: v3(0, hip + 8 * s, 0), tail: v3(0, sho, 0) }, // 1
+        { name: "head", parent: 1, head: v3(0, neck, 0), tail: v3(0, h, 0) }, // 2
+        { name: "legL.up", parent: 0, head: v3(-9 * s, hip, 0), tail: v3(-9 * s, knee, 0) }, // 3
+        { name: "legL.lo", parent: 3, head: v3(-9 * s, knee, 0), tail: v3(-9 * s, 4 * s, 0) }, // 4
+        { name: "legR.up", parent: 0, head: v3(9 * s, hip, 0), tail: v3(9 * s, knee, 0) }, // 5
+        { name: "legR.lo", parent: 5, head: v3(9 * s, knee, 0), tail: v3(9 * s, 4 * s, 0) }, // 6
+        { name: "armL.up", parent: 1, head: v3(-15 * s, sho, 0), tail: v3(-17 * s, elb, 0) }, // 7
+        { name: "armL.lo", parent: 7, head: v3(-17 * s, elb, 0), tail: v3(-18 * s, 96 * s, 0) }, // 8
+        { name: "armR.up", parent: 1, head: v3(15 * s, sho, 0), tail: v3(17 * s, elb, 0) }, // 9
+        { name: "armR.lo", parent: 9, head: v3(17 * s, elb, 0), tail: v3(18 * s, 96 * s, 0) }, // 10
+    ];
+    const rig = { parts: [], boneOf: [] };
+    segment(rig, 1, v3(0, hip + 4 * s, 0), v3(0, sho, 0), 10 * s, 12 * s, 9); // torso
+    blob(rig, 0, v3(0, hip, 0), 10.5 * s); // pelvis
+    blob(rig, 2, v3(0, neck + 9 * s, 0), 7.5 * s); // head
+    segment(rig, 1, v3(0, sho - 3 * s, 0), v3(0, neck, 0), 4 * s, 3.4 * s, 6); // neck
+    for (const [up, lo, sx] of [[3, 4, -1], [5, 6, 1]]) {
+        segment(rig, up, bones[up].head, bones[up].tail, 6 * s, 4.6 * s);
+        segment(rig, lo, bones[lo].head, bones[lo].tail, 4.4 * s, 2.8 * s);
+        blob(rig, lo, v3(sx * 9 * s, 3 * s, 4 * s), 4.4 * s, 0); // foot
+    }
+    for (const [up, lo] of [[7, 8], [9, 10]]) {
+        segment(rig, up, bones[up].head, bones[up].tail, 3.8 * s, 3 * s);
+        segment(rig, lo, bones[lo].head, bones[lo].tail, 2.9 * s, 2.2 * s);
+    }
+    return { mesh: mergeMesh(...rig.parts), boneOf: rig.boneOf, bones };
+}
+/** A quadruped (dog-shaped): 10 bones, shoulder height h, facing +z. */
+export function quadruped(h = 40) {
+    const s = h / 40;
+    const bones = [
+        { name: "body", parent: -1, head: v3(0, 30 * s, -14 * s), tail: v3(0, 32 * s, 14 * s) }, // 0
+        { name: "head", parent: 0, head: v3(0, 34 * s, 16 * s), tail: v3(0, 40 * s, 28 * s) }, // 1
+        { name: "tail", parent: 0, head: v3(0, 32 * s, -16 * s), tail: v3(0, 42 * s, -26 * s) }, // 2
+        { name: "legFL", parent: 0, head: v3(-6 * s, 28 * s, 10 * s), tail: v3(-6 * s, 2 * s, 10 * s) },
+        { name: "legFR", parent: 0, head: v3(6 * s, 28 * s, 10 * s), tail: v3(6 * s, 2 * s, 10 * s) },
+        { name: "legBL", parent: 0, head: v3(-6 * s, 28 * s, -10 * s), tail: v3(-6 * s, 2 * s, -10 * s) },
+        { name: "legBR", parent: 0, head: v3(6 * s, 28 * s, -10 * s), tail: v3(6 * s, 2 * s, -10 * s) },
+    ];
+    const rig = { parts: [], boneOf: [] };
+    segment(rig, 0, bones[0].head, bones[0].tail, 8 * s, 9 * s, 8);
+    blob(rig, 1, v3(0, 38 * s, 24 * s), 5.5 * s);
+    segment(rig, 1, v3(0, 36 * s, 24 * s), v3(0, 34 * s, 32 * s), 2.6 * s, 1.8 * s, 5); // snout
+    segment(rig, 2, bones[2].head, bones[2].tail, 2 * s, 1 * s, 5);
+    for (let i = 3; i <= 6; i++)
+        segment(rig, i, bones[i].head, bones[i].tail, 2.6 * s, 1.7 * s, 5);
+    return { mesh: mergeMesh(...rig.parts), boneOf: rig.boneOf, bones };
+}
+/** The walk: phase in radians (t * cadence). Legs swing opposite, knees flex on
+ *  the back-swing, arms counter-swing, the spine counter-rotates a touch. */
+export function walkPose(phase, stride = 0.6) {
+    const L = Math.sin(phase), R = Math.sin(phase + Math.PI);
+    const kneeL = Math.max(0, -Math.cos(phase)) * stride * 1.2;
+    const kneeR = Math.max(0, Math.cos(phase)) * stride * 1.2;
+    return {
+        "legL.up": { x: L * stride }, "legL.lo": { x: kneeL },
+        "legR.up": { x: R * stride }, "legR.lo": { x: kneeR },
+        "armL.up": { x: R * stride * 0.7 }, "armL.lo": { x: R * stride * 0.3 + 0.2 },
+        "armR.up": { x: L * stride * 0.7 }, "armR.lo": { x: L * stride * 0.3 + 0.2 },
+        spine: { y: Math.sin(phase) * 0.06 },
+        pelvis: { z: Math.sin(phase) * 0.05 },
+    };
+}
+/** The trot: diagonal pairs move together, the tail wags, the head bobs. */
+export function trotPose(phase, stride = 0.55) {
+    const A = Math.sin(phase), B = Math.sin(phase + Math.PI);
+    return {
+        legFL: { x: A * stride }, legBR: { x: A * stride },
+        legFR: { x: B * stride }, legBL: { x: B * stride },
+        head: { x: Math.sin(phase * 2) * 0.08 },
+        tail: { z: Math.sin(phase * 2.6) * 0.4 },
+    };
+}

package/dist/world.d.ts

@@ -1,5 +1,6 @@
 import { V3, M4, TransformSpec } from "./math.js";
 import { Mesh } from "./geometry.js";
+import { Rig, Pose } from "./skeletal.js";
 export type LineOpts = {
     hue: number;
     sat?: number;
@@ -96,6 +97,34 @@ export declare class World {
         dir: V3;
         speed: number;
     };
+    /** W11 — REAL WATER: one water table per world. The scene renders a second time
+     *  through the reflected camera (solids + instanced, flocks included) into a
+     *  reflection target; the surface is a wave-displaced grid sampling it in screen
+     *  space with a fresnel blend. The table fills wherever the ground dips below level. */
+    water: {
+        on: boolean;
+        level: number;
+        size: number;
+        hue: number;
+        sat: number;
+        light: number;
+        amp: number;
+        distort: number;
+        alpha: number;
+    };
+    private pWater;
+    private bWater;
+    private waterVerts;
+    private reflFBO;
+    private reflTex;
+    private reflDepth;
+    private reflW;
+    private reflH;
+    private clipY;
+    /** W12 — skinned figures: rig buffers + live bone matrices */
+    private pFaceS;
+    private pDepthS;
+    private figures;
     private post;
     private ink;
     private bg;
@@ -289,10 +318,25 @@ export declare class World {
     private drawLines;
     private drawPts;
     private drawRibbons;
+    /** W12 — a skinned FIGURE: bones + rigid skinning + procedural poses.
+     *  Returns a handle whose pose() re-composes the bone matrices (CPU, 16 tiny
+     *  mat4 muls); the vertices bend in the vertex stage, scene and shadow alike.
+     *  Place / turn the whole figure with its GROUP transform, like any geometry. */
+    figure(rig: Rig, o: FaceOpts): {
+        pose(p: Pose): void;
+        bones: typeof rig.bones;
+    };
+    private drawFigures;
     /** Instanced records under a given program (scene or depth pass). Divisors are reset
      *  after each draw — attribute divisor is global-per-index state and would otherwise
      *  poison the non-instanced draws that share those indices. */
     private drawInstancedAll;
+    private resizeReflection;
+    /** The reflection pass: solids + instanced re-rendered through the reflected camera,
+     *  clipped at the water plane. Lines / ribbons / points are skipped - reflections of
+     *  the light layer read as noise at half-res and cost more than they give. */
+    private renderReflection;
+    private drawWater;
     private renderFrame;
     private frameFn;
     private pausedByUser;

package/dist/world.js

@@ -4,7 +4,8 @@
 // hardware-PCF depth-texture shadows, per-group transforms + morph targets in the
 // vertex stage, mesh + ribbon primitives. Zero third-party imports, on purpose.
 import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, mInvert, normalMat3, } from "./math.js";
-import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, FACE_INST_VS, DEPTH_INST_VS, } from "./shaders.js";
+import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, FACE_INST_VS, DEPTH_INST_VS, WATER_VS, WATER_FS, FACE_SKIN_VS, DEPTH_SKIN_VS, } from "./shaders.js";
+import { composePose } from "./skeletal.js";
 import { PInfo, PostChain } from "./post.js";
 const FACE_STRIDE = 18; // pos3 norm3 rgb3 gloss1 blood1 grp1 pos2:3 norm2:3
 const LINE_STRIDE = 8; // pos3 col4 grp1
@@ -36,6 +37,24 @@ export class World {
         this.instanced = [];
         /** W9 — the one wind that blows through every swaying instanced batch */
         this.wind = { dir: v3(1, 0, 0.35), speed: 1 };
+        /** W11 — REAL WATER: one water table per world. The scene renders a second time
+         *  through the reflected camera (solids + instanced, flocks included) into a
+         *  reflection target; the surface is a wave-displaced grid sampling it in screen
+         *  space with a fresnel blend. The table fills wherever the ground dips below level. */
+        this.water = { on: false, level: 0, size: 4000, hue: 205, sat: 50, light: 30, amp: 3, distort: 0.03, alpha: 0.88 };
+        this.pWater = null;
+        this.bWater = null;
+        this.waterVerts = 0;
+        this.reflFBO = null;
+        this.reflTex = null;
+        this.reflDepth = null;
+        this.reflW = 0;
+        this.reflH = 0;
+        this.clipY = -1e9;
+        /** W12 — skinned figures: rig buffers + live bone matrices */
+        this.pFaceS = null;
+        this.pDepthS = null;
+        this.figures = [];
         this.ink = false;
         this.bg = [0.024, 0.016, 0.055];
         this.transparent = false;
@@ -501,6 +520,7 @@ export class World {
     }
     setLights(p, fogK) {
         const gl = this.gl, L = norm(this.light.dir);
+        gl.uniform1f(p.u("uClipY"), this.clipY);
         gl.uniform3f(p.u("uLdir"), L.x, L.y, L.z);
         gl.uniform1f(p.u("uAmb"), this.ink ? Math.min(1, this.light.ambient + 0.22) : this.light.ambient);
         gl.uniform1f(p.u("uDif"), this.ink ? this.light.diffuse * 0.55 : this.light.diffuse);
@@ -612,6 +632,54 @@ export class World {
         this.attrib(this.pRib, "aGrp", 1, RIB_STRIDE, 15);
         gl.drawArrays(gl.TRIANGLES, 0, verts);
     }
+    /** W12 — a skinned FIGURE: bones + rigid skinning + procedural poses.
+     *  Returns a handle whose pose() re-composes the bone matrices (CPU, 16 tiny
+     *  mat4 muls); the vertices bend in the vertex stage, scene and shadow alike.
+     *  Place / turn the whole figure with its GROUP transform, like any geometry. */
+    figure(rig, o) {
+        const gl = this.gl;
+        if (!this.pFaceS) {
+            this.pFaceS = new PInfo(gl, FACE_SKIN_VS, FACE_FS);
+            this.pDepthS = new PInfo(gl, DEPTH_SKIN_VS, DEPTH_FS);
+        }
+        const store = [];
+        const P = rig.mesh.pos, N = rig.mesh.nrm;
+        const base = [];
+        for (let i = 0; i < P.length; i += 9) {
+            this.pushFace(base, v3(P[i], P[i + 1], P[i + 2]), v3(P[i + 3], P[i + 4], P[i + 5]), v3(P[i + 6], P[i + 7], P[i + 8]), o, v3(N[i], N[i + 1], N[i + 2]), v3(N[i + 3], N[i + 4], N[i + 5]), v3(N[i + 6], N[i + 7], N[i + 8]));
+        }
+        // re-stride 18 -> 19 with the vertex's bone index appended
+        const nv = base.length / FACE_STRIDE;
+        for (let vtx = 0; vtx < nv; vtx++) {
+            for (let k = 0; k < FACE_STRIDE; k++)
+                store.push(base[vtx * FACE_STRIDE + k]);
+            store.push(rig.boneOf[vtx] ?? 0);
+        }
+        const vbuf = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, vbuf);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(store), gl.STATIC_DRAW);
+        const rec = { vbuf, verts: nv, mats: composePose(rig.bones, {}) };
+        this.figures.push(rec);
+        return { pose: (pp) => { rec.mats = composePose(rig.bones, pp); }, bones: rig.bones };
+    }
+    drawFigures(p, depthOnly) {
+        if (!this.figures.length)
+            return;
+        const gl = this.gl, SK = FACE_STRIDE + 1;
+        for (const rec of this.figures) {
+            gl.uniformMatrix4fv(p.u("uBones[0]"), false, rec.mats);
+            gl.bindBuffer(gl.ARRAY_BUFFER, rec.vbuf);
+            this.attrib(p, "aPos", 3, SK, 0);
+            if (!depthOnly) {
+                this.attrib(p, "aNorm", 3, SK, 3);
+                this.attrib(p, "aCol", 4, SK, 6);
+                this.attrib(p, "aBlood", 1, SK, 10);
+            }
+            this.attrib(p, "aGrp", 1, SK, 11);
+            this.attrib(p, "aBone", 1, SK, 18);
+            gl.drawArrays(gl.TRIANGLES, 0, rec.verts);
+        }
+    }
     /** Instanced records under a given program (scene or depth pass). Divisors are reset
      *  after each draw — attribute divisor is global-per-index state and would otherwise
      *  poison the non-instanced draws that share those indices. */
@@ -648,6 +716,120 @@ export class World {
                 gl.vertexAttribDivisor(loc, 0);
         }
     }
+    resizeReflection() {
+        const gl = this.gl;
+        const rw = Math.max(1, this.canvas.width >> 1), rh = Math.max(1, this.canvas.height >> 1);
+        if (rw === this.reflW && rh === this.reflH && this.reflFBO)
+            return;
+        this.reflW = rw;
+        this.reflH = rh;
+        if (this.reflTex)
+            gl.deleteTexture(this.reflTex);
+        if (this.reflDepth)
+            gl.deleteRenderbuffer(this.reflDepth);
+        if (this.reflFBO)
+            gl.deleteFramebuffer(this.reflFBO);
+        this.reflTex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, this.reflTex);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, rw, rh, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        this.reflDepth = gl.createRenderbuffer();
+        gl.bindRenderbuffer(gl.RENDERBUFFER, this.reflDepth);
+        gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT24, rw, rh);
+        this.reflFBO = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.reflFBO);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.reflTex, 0);
+        gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.reflDepth);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    /** The reflection pass: solids + instanced re-rendered through the reflected camera,
+     *  clipped at the water plane. Lines / ribbons / points are skipped - reflections of
+     *  the light layer read as noise at half-res and cost more than they give. */
+    renderReflection(fogK) {
+        const gl = this.gl;
+        const h = this.water.level;
+        const R = new Float32Array([1, 0, 0, 0, 0, -1, 0, 0, 0, 0, 1, 0, 0, 2 * h, 0, 1]);
+        const vpSave = this.vp;
+        this.vp = mMul(vpSave, R);
+        this.clipY = h;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.reflFBO);
+        gl.viewport(0, 0, this.reflW, this.reflH);
+        gl.clearColor(this.bg[0], this.bg[1], this.bg[2], 1);
+        gl.enable(gl.DEPTH_TEST);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+        this.pFace.use();
+        this.setVP(this.pFace);
+        this.setLights(this.pFace, fogK);
+        this.drawFaces(this.bFace, this.sFace.length / FACE_STRIDE, null);
+        if (this.dFaceA.length)
+            this.drawFaces(this.bFaceD, this.dFaceA.length / FACE_STRIDE, new Float32Array(this.dFaceA));
+        if (this.instanced.length) {
+            this.pFaceI.use();
+            this.setVP(this.pFaceI);
+            this.setLights(this.pFaceI, fogK);
+            gl.uniform1f(this.pFaceI.u("uT"), this.lastT * this.wind.speed);
+            gl.uniform3f(this.pFaceI.u("uWindDir"), this.wind.dir.x, this.wind.dir.y, this.wind.dir.z);
+            this.drawInstancedAll(this.pFaceI, false);
+        }
+        if (this.figures.length && this.pFaceS) {
+            this.pFaceS.use();
+            this.setVP(this.pFaceS);
+            this.setLights(this.pFaceS, fogK);
+            this.drawFigures(this.pFaceS, false);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.vp = vpSave;
+        this.clipY = -1e9;
+    }
+    drawWater(t, fogK) {
+        const gl = this.gl;
+        if (!this.pWater)
+            this.pWater = new PInfo(gl, WATER_VS, WATER_FS);
+        if (!this.bWater) {
+            const g = [];
+            const N = 64, S = this.water.size;
+            for (let i = 0; i < N; i++)
+                for (let j = 0; j < N; j++) {
+                    const x0 = (i / N - 0.5) * S, x1 = ((i + 1) / N - 0.5) * S;
+                    const z0 = (j / N - 0.5) * S, z1 = ((j + 1) / N - 0.5) * S;
+                    g.push(x0, 0, z0, x1, 0, z0, x1, 0, z1, x0, 0, z0, x1, 0, z1, x0, 0, z1);
+                }
+            this.bWater = gl.createBuffer();
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bWater);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(g), gl.STATIC_DRAW);
+            this.waterVerts = g.length / 3;
+        }
+        const p = this.pWater;
+        p.use();
+        gl.uniformMatrix4fv(p.u("uVP"), false, this.vp);
+        gl.uniform1f(p.u("uT"), t);
+        gl.uniform1f(p.u("uLevel"), this.water.level);
+        gl.uniform1f(p.u("uAmp"), this.water.amp);
+        gl.uniform1f(p.u("uDistort"), this.water.distort);
+        gl.uniform1f(p.u("uAlpha"), this.water.alpha);
+        const [r, gg, b] = this.col(this.water.hue, this.water.sat, this.water.light);
+        gl.uniform3f(p.u("uTint"), r, gg, b);
+        gl.uniform3f(p.u("uCam"), this.cx.x, this.cx.y, this.cx.z);
+        gl.uniform1f(p.u("uFogK"), fogK);
+        gl.uniform3f(p.u("uBg"), this.bg[0], this.bg[1], this.bg[2]);
+        gl.uniform2f(p.u("uRes"), this.canvas.width, this.canvas.height);
+        gl.activeTexture(gl.TEXTURE3);
+        gl.bindTexture(gl.TEXTURE_2D, this.reflTex);
+        gl.uniform1i(p.u("uRefl"), 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.bWater);
+        this.attrib(p, "aPos", 3, 3, 0);
+        gl.depthMask(false);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        gl.drawArrays(gl.TRIANGLES, 0, this.waterVerts);
+        if (!this.ink)
+            gl.blendFunc(gl.ONE, gl.ONE);
+        gl.activeTexture(gl.TEXTURE0);
+    }
     // ── the frame ──
     renderFrame(t, dt) {
         const gl = this.gl;
@@ -740,8 +922,19 @@ export class World {
                 this.setGroups(this.pDepthI);
                 this.drawInstancedAll(this.pDepthI, true);
             }
+            if (this.figures.length && this.pDepthS) {
+                this.pDepthS.use();
+                gl.uniformMatrix4fv(this.pDepthS.u("uVP"), false, this.svp);
+                this.setGroups(this.pDepthS);
+                this.drawFigures(this.pDepthS, true);
+            }
             gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         }
+        // W11: the reflection pass first — the world through the mirrored camera
+        if (this.water.on) {
+            this.resizeReflection();
+            this.renderReflection(fogK);
+        }
         // the scene pass — into the HDR target when the post chain is on
         if (this.post)
             this.post.begin();
@@ -772,9 +965,17 @@ export class World {
             gl.uniform3f(this.pFaceI.u("uWindDir"), this.wind.dir.x, this.wind.dir.y, this.wind.dir.z);
             this.drawInstancedAll(this.pFaceI, false);
         }
+        if (this.figures.length && this.pFaceS) {
+            this.pFaceS.use();
+            this.setVP(this.pFaceS);
+            this.setLights(this.pFaceS, fogK);
+            this.drawFigures(this.pFaceS, false);
+        }
         // the light — additive, depth-TESTED but not written (ink: normal alpha blend)
         gl.depthMask(false);
         gl.enable(gl.BLEND);
+        if (this.water.on && this.reflTex)
+            this.drawWater(t, fogK);
         if (this.ink)
             gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
         else
@@ -900,6 +1101,17 @@ export class World {
             this.gl.deleteBuffer(rec.ibuf);
         }
         this.instanced = [];
+        if (this.reflTex)
+            this.gl.deleteTexture(this.reflTex);
+        if (this.reflDepth)
+            this.gl.deleteRenderbuffer(this.reflDepth);
+        if (this.reflFBO)
+            this.gl.deleteFramebuffer(this.reflFBO);
+        if (this.bWater)
+            this.gl.deleteBuffer(this.bWater);
+        for (const f of this.figures)
+            this.gl.deleteBuffer(f.vbuf);
+        this.figures = [];
         this.post?.dispose();
         if (releaseContext)
             this.gl.getExtension("WEBGL_lose_context")?.loseContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromatic-coherence/generative-engine",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "THE THIRD ENGINE — a zero-dependency WebGL2 graphics engine grown from generative-charts-3d: HDR + bloom + SSAO post chain, hardware-PCF shadow maps, a geometry stdlib, ribbon strokes, group transforms and morph targets. The charts API rides on top unchanged.",
   "type": "module",
   "main": "./dist/index.js",