@bitefoundry/retrieviewer 0.0.0-stage → 0.0.1

package/vendor/procedural-animals/src/species/spider/rig.js

@@ -0,0 +1,118 @@
+// Spider skeleton in bind pose (metres; dimensions below are written in millimetres).
+// Forward = +Z, up = +Y, the animal's left = +X. Two variants share the rig: the wolf spider
+// (Lycosidae, reference female Hogna carolinensis, body 25 mm) and the tarantula (Theraphosidae,
+// reference female Brachypelma hamorii, body 60 mm).
+import { buildRig } from '../../core/rig/rig.js';
+import { spiderBones, spiderLimbs, planarChain, solveBindElevations, legJoints, palpJoints, AXIAL_POINTS, AXIAL_BONES } from '../../core/rig/spider.js';
+
+const D2R = Math.PI / 180;
+const mm = (v) => v.map((x) => x * 0.001);
+
+// Per-variant anatomy (mm, degrees). leg: [I, II, III, IV] total lengths; seg: segment fractions
+// coxa, trochanter, femur, patella, tibia, metatarsus, tarsus; el: bind elevations of the segments
+// (the metatarsus is solved so the claw rests on the ground); r: segment radii (base, end).
+export const VARIANTS = {
+  wolf: {
+    unit: 0.013,
+    bodyLen: 25,
+    axial: { front: [0, 7.4, 6.5], ceph: [0, 7.6, 1.6], pedA: [0, 6.3, -4.5], pedB: [0, 6.1, -5.7], abdEnd: [0, 5.4, -17.2], spinTip: [0, 4.7, -18.5] },
+    carapace: { len: 11, wid: 8.6, top: 9.9, rearTop: 7.3, bottom: 4.5, headW: 5.2 },
+    abdomen: { c: [0, 6.5, -11.4], r: [3.9, 3.35, 6.1] },
+    chel: { base: [0.95, 7.0, 6.1], tip: [0.9, 3.8, 7.0], fang: [0.15, 4.25, 6.75], r: [0.95, 0.72], fangR: 0.2 },
+    coxa: { y: 5.1, x: [2.35, 2.75, 2.75, 2.45], z: [3.3, 1.4, -0.6, -2.6], az: [30, 66, 112, 150] },
+    leg: [35, 33, 31, 43],
+    seg: [0.08, 0.05, 0.26, 0.12, 0.2, 0.19, 0.1],
+    el: [-14, 4, 30, -6, -28, 0, -14],
+    legR: [[1.05, 0.95], [0.84, 0.8], [0.8, 0.68], [0.7, 0.63], [0.63, 0.53], [0.5, 0.4], [0.39, 0.29]],
+    hindR: 1.06,
+    tipY: 0.32,
+    palp: { base: [1.75, 5.2, 5.4], az: 14, len: 16, seg: [0.12, 0.08, 0.3, 0.15, 0.18, 0.17], el: [-30, -10, 15, -30, 0, -50], r: [[0.62, 0.55], [0.5, 0.48], [0.46, 0.42], [0.42, 0.4], [0.4, 0.37], [0.37, 0.28]], tipY: 0.55 },
+    spinR: 0.45,
+  },
+  tarantula: {
+    unit: 0.028,
+    bodyLen: 60,
+    axial: { front: [0, 13.2, 12.8], ceph: [0, 14.2, 3.5], pedA: [0, 12.0, -11.6], pedB: [0, 11.8, -13.6], abdEnd: [0, 10.8, -41.5], spinTip: [0, 9.2, -46] },
+    carapace: { len: 25, wid: 23.5, top: 16.2, rearTop: 14.0, bottom: 7.4, headW: 13 },
+    abdomen: { c: [0, 12.4, -27.6], r: [12.0, 9.6, 14.4] },
+    chel: { base: [3.0, 12.6, 11.2], tip: [2.9, 9.4, 18.0], fang: [2.6, 4.9, 16.4], r: [3.1, 2.4], fangR: 0.75 },
+    coxa: { y: 8.6, x: [5.8, 6.7, 6.7, 6.0], z: [6.2, 2.0, -2.6, -7.0], az: [26, 60, 114, 150] },
+    leg: [65, 60, 55, 72.5],
+    seg: [0.09, 0.06, 0.25, 0.14, 0.2, 0.16, 0.1],
+    el: [-10, 6, 34, -4, -30, 0, -13],
+    legR: [[3.0, 2.7], [2.4, 2.3], [2.3, 2.0], [2.05, 1.95], [1.95, 1.75], [1.65, 1.45], [1.45, 1.25]],
+    hindR: 1.04,
+    tipY: 1.3,
+    palp: { base: [4.6, 8.4, 10.8], az: 16, len: 37, seg: [0.14, 0.08, 0.28, 0.16, 0.18, 0.16], el: [-30, -10, 15, -30, 0, -40], r: [[2.2, 2.0], [1.9, 1.8], [1.8, 1.65], [1.65, 1.55], [1.55, 1.45], [1.45, 1.2]], tipY: 1.3 },
+    spinR: 1.3,
+  },
+};
+
+// Anatomy of one individual: the variant's reference numbers with the seeded proportions of
+// params (legK: leg length factor, abdK: abdomen size, palpBulb: male palpal bulbs).
+export function spiderDims(params = {}) {
+  const V = VARIANTS[params.variant] || VARIANTS.wolf;
+  const legK = params.legK || 1, abdK = params.abdK || 1;
+  const d = JSON.parse(JSON.stringify(V));
+  d.variant = VARIANTS[params.variant] ? params.variant : 'wolf';
+  d.leg = V.leg.map((l) => l * legK);
+  d.palp.len = V.palp.len * (0.5 + 0.5 * legK);
+  d.abdomen.r = V.abdomen.r.map((r) => r * abdK);
+  // a bigger abdomen hangs further back from the pedicel
+  d.abdomen.c = [0, V.abdomen.c[1] + (abdK - 1) * 0.4 * V.abdomen.r[1], V.abdomen.c[2] - (abdK - 1) * V.abdomen.r[2]];
+  d.axial.abdEnd = [0, V.axial.abdEnd[1] - (abdK - 1) * 0.3 * V.abdomen.r[1], V.axial.abdEnd[2] - 2 * (abdK - 1) * V.abdomen.r[2]];
+  d.axial.spinTip = [0, V.axial.spinTip[1] - (abdK - 1) * 0.3 * V.abdomen.r[1], V.axial.spinTip[2] - 2 * (abdK - 1) * V.abdomen.r[2]];
+  d.palpBulb = params.palpBulb || 0;
+  return d;
+}
+
+export function spiderJoints(params = {}) {
+  const d = spiderDims(params);
+  const J = {};
+  for (const [k, v] of Object.entries(d.axial)) J[k] = mm(v);
+  J.cheBaseL = mm(d.chel.base);
+  J.cheTipL = mm(d.chel.tip);
+  J.fangTipL = mm(d.chel.fang);
+  for (let i = 1; i <= 4; i++) {
+    const L = d.leg[i - 1];
+    const lens = d.seg.map((f) => f * L * 0.001);
+    const base = mm([d.coxa.x[i - 1], d.coxa.y, d.coxa.z[i - 1]]);
+    const el = solveBindElevations(base[1], lens, d.el.map((e) => e * D2R), 5, d.tipY * 0.001);
+    planarChain(J, legJoints(i, 'L'), base, d.coxa.az[i - 1] * D2R, el, lens, 1);
+  }
+  {
+    const P = d.palp;
+    const lens = P.seg.map((f) => f * P.len * 0.001);
+    const base = mm(P.base);
+    // the tibia takes up the height so the tarsus meets the ground slanting forward
+    const el = solveBindElevations(base[1], lens, P.el.map((e) => e * D2R), 4, P.tipY * 0.001);
+    planarChain(J, palpJoints('L'), base, P.az * D2R, el, lens, 1);
+  }
+  return J;
+}
+
+export function spiderRig(params = {}) {
+  const d = spiderDims(params);
+  const J = spiderJoints(params);
+  const U = d.unit;
+  return buildRig({
+    joints: J,
+    unit: U,
+    headOrigin: J.ceph,
+    meta: { dims: d },
+    bones: spiderBones(),
+    axial: {
+      points: AXIAL_POINTS,
+      bones: AXIAL_BONES,
+      // the carapace is rigid: head and prosoma share it (the engine never bends them apart); the
+      // pedicel is a short stalk, blended narrowly into the abdomen
+      blend: { 1: [-0.1, 0.1], 2: [-0.012, 0.004], 3: [-0.004, 0.02] },
+    },
+    limbs: spiderLimbs({
+      leg: { tCore: 0.5, aCore: 0.05, aBody: -0.05, midX: 0.06 },
+      palp: { tCore: 0.45, aCore: 0.04, aBody: -0.05, midX: 0.04 },
+    }),
+    appendages: [],
+    webTags: [],
+  });
+}

package/vendor/procedural-animals/src/species/spider/sculpt.js

@@ -0,0 +1,182 @@
+// The spider, sculpted as a signed distance field (reference space, metres).
+//
+// Parts (meshed separately, see regions.js): 'body' (prosoma, pedicel, abdomen, spinnerets, palps,
+// coxae and trochanters), one part per leg ('legL1' .. 'legR4': coxa -> tarsus, the coxa and
+// trochanter duplicated so both surfaces agree across the cut), 'chelL'/'chelR' (rigid chelicerae)
+// and 'fangL'/'fangR' (rigid fangs). Eyes are glossy domes (look.lids 'simple') set in shallow
+// sockets on the head.
+import { spiderDims } from './rig.js';
+import { legJoints, legBones, palpJoints, palpBones } from '../../core/rig/spider.js';
+import { add, sub, mul, lerp, norm, cross, len } from '../../core/math/vec.js';
+import { eyeFrameOf } from '../../core/sdf/eyeSocket.js';
+import { QUALITY } from '../../core/build/pipeline.js';
+
+const M = 0.001;
+const mm = (v) => v.map((x) => x * M);
+
+// Eyes per variant (mm, head-local: relative to the ceph joint; left side). r: radius; yaw: outward
+// divergence of the view axis (rad, > PI/2 looks backward); pitch: upward tilt; back: how far the
+// dome centre sits inside the surface point.
+export const EYES = {
+  // Lycosidae 4-2-2: a straight anterior row of 4 small eyes above the chelicerae, 2 huge posterior
+  // median eyes looking forward, 2 posterior lateral eyes on top looking up and back
+  wolf: [
+    // (set into the carapace surface: the domes bulge ~0.4 r; the PME sit on the front of the face)
+    { name: 'PME', c: [1.02, 1.2, 4.57], r: 0.47, yaw: 0.14, pitch: 0.02, back: 0.2 },
+    { name: 'PLE', c: [1.78, 1.54, 2.72], r: 0.3, yaw: 2.1, pitch: 0.75, back: 0.14 },
+    { name: 'AME', c: [0.42, 0.3, 5.26], r: 0.22, yaw: 0.05, pitch: -0.05, back: 0.07 },
+    { name: 'ALE', c: [1.0, 0.3, 5.05], r: 0.17, yaw: 0.55, pitch: -0.05, back: 0.05 },
+  ],
+  // Theraphosidae: 8 small eyes clustered on a raised ocular tubercle
+  tarantula: [
+    { name: 'AME', c: [0.62, 2.55, 6.1], r: 0.5, yaw: 0.08, pitch: 0.5, back: 0.2 },
+    { name: 'ALE', c: [1.62, 2.05, 6.25], r: 0.52, yaw: 0.6, pitch: 0.25, back: 0.2 },
+    { name: 'PME', c: [0.85, 2.6, 5.05], r: 0.3, yaw: 0.5, pitch: 1.0, back: 0.12 },
+    { name: 'PLE', c: [1.72, 2.2, 4.75], r: 0.42, yaw: 1.7, pitch: 0.45, back: 0.16 },
+  ],
+};
+
+export function eyeSpec(e) {
+  const r = e.r * M;
+  return { c: mm(e.c), r, back: e.back * M, yaw: e.yaw, pitch: e.pitch, tilt: 0, lid: 0, R: r * 1.1, d: r * 0.6, off: 0, irisZ: r * 0.6, irisR: r * 0.8, name: e.name };
+}
+
+// minimum radius of thin parts per quality tier (coarse meshes would lose the tarsi otherwise)
+const MIN_R = { hero: 0, high: 0, medium: 0.26, low: 0.4, crowd: 0.58 }; // ~ one cell: legs stay >= 2 voxels thick
+
+export function sculptSpider(m, rig, params) {
+  const J = rig.J, d = spiderDims(params);
+  const F = d.unit / 0.013; // size relative to the wolf spider
+  const minR = (MIN_R[params.quality] ?? 0) * M * F;
+  const R = (r) => Math.max(r * M, minR);
+  const HO = J.ceph;
+  const hl = (v) => add(HO, mm(v));
+  const X = [1, 0, 0];
+  const ellY = (o) => {
+    const y = norm(o.ydir);
+    const z = norm(cross(o.lateral || X, y));
+    return m.ell({ ...o, axis: z, up: y });
+  };
+  const wolf = d.variant === 'wolf';
+  const C = d.carapace;
+  const z0 = J.pedA[2] / M, z1 = J.front[2] / M, Lc = z1 - z0;
+  const B = { bone: 'prosoma', group: 'axial', part: 'body' };
+  const H = { bone: 'head', group: 'axial', part: 'body' };
+
+  // ------------------------------------------------------------------ PROSOMA
+  // carapace: thoracic dome, raised cephalic region, sloping rear; sternum below
+  const thTop = C.rearTop + (C.top - C.rearTop) * (wolf ? 0.55 : 0.75);
+  m.ell({ ...B, tag: 'thorax', c: mm([0, (thTop + C.bottom) / 2, z0 + 0.42 * Lc]), r: mm([C.wid / 2, (thTop - C.bottom) / 2, 0.41 * Lc]), k: 0 });
+  m.ell({ ...B, tag: 'thoraxRear', c: mm([0, (C.rearTop + C.bottom) / 2 + 0.2 * F, z0 + 0.2 * Lc]), r: mm([C.wid * 0.36, (C.rearTop - C.bottom) / 2, 0.2 * Lc]), k: 0.9 * M * F });
+  m.ell({ ...H, tag: 'cephalic', c: mm([0, C.top - (wolf ? 2.3 : 3.2) * F, z0 + 0.78 * Lc]), r: mm([C.headW / 2, (wolf ? 2.3 : 3.2) * F, 0.26 * Lc]), axis: norm([0, wolf ? 0.18 : 0.05, 1]), k: 1.2 * M * F });
+  // clypeus: the face between the anterior eyes and the chelicerae
+  m.ell({ ...H, tag: 'clypeus', c: add(J.front, mm([0, -0.2 * F, -0.9 * F])), r: mm([C.headW * 0.36, 1.1 * F, 0.9 * F]), k: 0.8 * M * F });
+  m.ell({ ...B, tag: 'sternum', c: mm([0, C.bottom + 0.45 * F, z0 + 0.5 * Lc]), r: mm([C.wid * 0.27, 0.7 * F, 0.3 * Lc]), k: 0.8 * M * F });
+  // labium and endites (mouthparts between the palp coxae)
+  m.ell({ ...B, tag: 'labium', c: mm([0, C.bottom + 0.6 * F, z0 + 0.86 * Lc]), r: mm([0.9 * F, 0.55 * F, 0.9 * F]), k: 0.5 * M * F });
+  // fovea: a short median groove on the thoracic dome, and the cephalic groove
+  m.ell({ ...B, tag: 'fovea', c: mm([0, thTop + 0.02 * F, z0 + 0.36 * Lc]), r: mm([0.16 * F, 0.3 * F, 0.9 * F]), k: 0.25 * M * F, carve: true });
+  if (!wolf) {
+    // tarantula: low wide carapace with a raised ocular tubercle
+    m.ell({ ...H, tag: 'tubercle', c: hl([0, 1.7, 5.4]), r: mm([2.3, 1.3, 1.9]), k: 1.1 * M * F });
+  }
+
+  // ------------------------------------------------------------------ EYES (sockets; the domes are eye meshes)
+  for (const e of EYES[d.variant]) {
+    const E = eyeSpec(e);
+    for (const s of [1, -1]) {
+      const ef = eyeFrameOf(E, HO, s);
+      // a raised rim around the lens, cut open by the socket the dome sits in
+      m.sphere({ ...H, tag: 'eyerim', c: add(ef.c, mul(ef.z, -E.r * 0.25)), rad: E.r * 1.05, k: E.r * 0.6 });
+      m.sphere({ ...H, tag: 'eyesocket', c: add(ef.c, mul(ef.z, E.r * 0.1)), rad: E.r * 0.98, k: E.r * 0.15, carve: true });
+    }
+  }
+
+  // ------------------------------------------------------------------ PEDICEL, ABDOMEN, SPINNERETS
+  const A = { bone: 'abdomen', group: 'axial', part: 'body' };
+  m.cone({ bone: 'pedicel', group: 'axial', part: 'body', tag: 'pedicel', a: J.pedA, b: J.pedB, ra: (wolf ? 0.75 : 1.9) * M * F / F * (wolf ? 1 : 1), rb: (wolf ? 0.7 : 1.8) * M, k: 0.3 * M * F });
+  const ac = mm(d.abdomen.c), ar = mm(d.abdomen.r);
+  m.ell({ ...A, tag: 'abdomen', c: ac, r: ar, axis: norm([0, 0.06, 1]), k: 0 });
+  m.ell({ ...A, tag: 'abdomenFront', c: add(ac, [0, -ar[1] * 0.05, ar[2] * 0.52]), r: [ar[0] * 0.7, ar[1] * 0.72, ar[2] * 0.45], k: 1.0 * M * F });
+  m.ell({ ...A, tag: 'abdomenRear', c: add(ac, [0, -ar[1] * 0.12, -ar[2] * 0.6]), r: [ar[0] * 0.72, ar[1] * 0.72, ar[2] * 0.42], k: 1.2 * M * F });
+  // spinnerets: wolf 3 short pairs; tarantula 2 visible pairs, the posterior pair long and finger-like
+  const SP = { bone: 'spinnerets', group: 'axial', part: 'body', tag: 'spinneret' };
+  const st = J.abdEnd, sd = norm(sub(J.spinTip, J.abdEnd)), sl = len(sub(J.spinTip, J.abdEnd));
+  for (const s of [1, -1]) {
+    if (wolf) {
+      m.cone({ ...SP, a: add(st, mm([0.45 * s, -0.25, 0.3])), b: add(add(st, mul(sd, sl * 0.9)), mm([0.5 * s, -0.2, 0])), ra: d.spinR * M, rb: d.spinR * 0.7 * M, k: 0.25 * M });
+      m.cone({ ...SP, a: add(st, mm([0.2 * s, -0.6, 0.3])), b: add(add(st, mul(sd, sl * 0.7)), mm([0.2 * s, -0.55, 0])), ra: d.spinR * 0.8 * M, rb: d.spinR * 0.55 * M, k: 0.25 * M });
+    } else {
+      m.cone({ ...SP, a: add(st, mm([1.1 * s, -0.4, 0.8])), b: add(add(st, mul(sd, sl * 1.15)), mm([1.9 * s, 0.9, 0])), ra: d.spinR * M, rb: d.spinR * 0.62 * M, k: 0.8 * M });
+      m.cone({ ...SP, a: add(st, mm([0.55 * s, -1.2, 0.8])), b: add(add(st, mul(sd, sl * 0.45)), mm([0.6 * s, -1.4, 0])), ra: d.spinR * 0.6 * M, rb: d.spinR * 0.45 * M, k: 0.6 * M });
+    }
+  }
+
+  // ------------------------------------------------------------------ CHELICERAE AND FANGS (rigid parts)
+  for (const S of ['L', 'R']) {
+    const s = S === 'L' ? 1 : -1;
+    const b0 = J['cheBase' + S], b1 = J['cheTip' + S], ft = J['fangTip' + S];
+    const CH = { bone: 'chelicera' + S, group: 'chel' + S, part: 'chel' + S };
+    const cr = d.chel.r.map((r) => r * M);
+    const dir = norm(sub(b1, b0));
+    m.cone({ ...CH, tag: 'chelicera', a: b0, b: add(b1, mul(dir, -cr[1] * 0.4)), ra: cr[0], rb: cr[1], k: 0 });
+    // the stout basal boss bulging forward (wolf) / the long forward-projecting paturon (tarantula)
+    ellY({ ...CH, tag: 'chelicera', c: add(lerp(b0, b1, 0.35), mm([0.1 * s * F, 0, (wolf ? 0.35 : 0.8) * F])), ydir: dir, r: [cr[0] * 0.92, len(sub(b1, b0)) * 0.4, cr[0] * 0.95], k: 0.5 * M * F });
+    // fang groove with its row of teeth: a shallow furrow on the inner face
+    ellY({ ...CH, tag: 'fangGroove', c: add(lerp(b0, b1, 0.8), mm([-0.55 * s * F, 0, 0.1 * F])), ydir: dir, r: [cr[1] * 0.35, len(sub(b1, b0)) * 0.22, cr[1] * 0.4], k: 0.2 * M * F, carve: true });
+    const FG = { bone: 'fang' + S, group: 'fang' + S, part: 'fang' + S, tag: 'fang' };
+    const fr = d.chel.fangR * M;
+    // a curved fang: base, then bending toward the tip
+    const fd = norm(sub(ft, b1)), fl = len(sub(ft, b1));
+    const bend = norm(cross(fd, [s, 0, 0]));
+    const mid = add(lerp(b1, ft, 0.5), mul(bend, fl * 0.12));
+    m.cone({ ...FG, a: add(b1, mul(fd, -fr * 0.5)), b: mid, ra: fr, rb: fr * 0.62, k: 0.08 * M * F });
+    m.cone({ ...FG, a: mid, b: ft, ra: fr * 0.62, rb: fr * 0.12, k: 0.08 * M * F });
+  }
+
+  // ------------------------------------------------------------------ PALPS (body part)
+  for (const S of ['L', 'R']) {
+    const pj = palpJoints(S), pb = palpBones(S);
+    const g = { group: 'P' + S, part: 'body' };
+    for (let k = 0; k < pb.length; k++) {
+      const [ra, rb] = d.palp.r[k];
+      const a = J[pj[k]], b = J[pj[k + 1]];
+      m.cone({ ...g, bone: pb[k], tag: k === 0 ? 'palpcoxa' : 'palp', a, b, ra: R(ra * F / F), rb: R(rb), k: (k === 0 ? 0.6 : 0.09) * M * F });
+      if (k > 0 && k < pb.length - 1) m.sphere({ ...g, bone: pb[k], tag: 'knuckle', c: b, rad: R(rb * 1.08), k: 0.08 * M * F });
+    }
+    if (d.palpBulb > 0) {
+      // male: the swollen cymbium / palpal bulb ("boxing gloves")
+      const a = J[pj[5]], b = J[pj[6]];
+      // (swollen but compact: about the width of the palp tibia plus a third)
+      ellY({ ...g, bone: pb[5], tag: 'palpbulb', c: lerp(a, b, 0.5), ydir: sub(b, a), r: mm([0.65 * (0.62 * F * d.palpBulb + 0.3 * F), len(sub(b, a)) / M * 0.36, 0.65 * (0.7 * F * d.palpBulb + 0.3 * F)]), k: 0.2 * M * F });
+    }
+  }
+
+  // ------------------------------------------------------------------ LEGS
+  for (const S of ['L', 'R']) {
+    for (let i = 1; i <= 4; i++) {
+      const lj = legJoints(i, S), lb = legBones(i, S), key = S + i;
+      const thick = i === 4 ? d.hindR : i === 3 ? (1 + d.hindR) / 2 : 1;
+      for (let k = 0; k < 7; k++) {
+        const [ra, rb] = d.legR[k];
+        const a = J[lj[k]], b = J[lj[k + 1]];
+        const parts = k <= 2 ? ['body', 'leg' + key] : ['leg' + key];
+        for (const part of parts) {
+          const g = { group: key, part, bone: lb[k] };
+          if (k === 0) {
+            // coxa: a stout cylinder set into the prosoma between carapace margin and sternum
+            m.cone({ ...g, tag: 'coxa', a: add(a, mul(norm(sub(b, a)), -0.6 * M * F)), b, ra: R(ra * thick), rb: R(rb * thick), k: part === 'body' ? 0.55 * M * F : 0.1 * M * F });
+          } else {
+            m.cone({ ...g, tag: ['coxa', 'troch', 'femur', 'patella', 'tibia', 'meta', 'tarsus'][k], a, b, ra: R(ra * thick), rb: R(rb * thick), k: 0.07 * M * F });
+            // swollen joint condyles: the knee (femur-patella) is the biggest
+            if (k < 6) m.sphere({ ...g, tag: 'knuckle', c: add(b, mul(norm(sub(b, a)), -rb * 0.25 * M)), rad: R(rb * thick * (k === 2 ? 1.12 : 1.06)), k: 0.07 * M * F });
+          }
+        }
+      }
+      // claw tuft: the rounded tarsus tip
+      const tip = J[lj[7]], ta = J[lj[6]];
+      m.sphere({ group: key, part: 'leg' + key, bone: lb[6], tag: 'claws', c: add(tip, mul(norm(sub(ta, tip)), d.legR[6][1] * 0.3 * M)), rad: R(d.legR[6][1] * thick * 1.02), k: 0.06 * M * F });
+    }
+  }
+  return m;
+}

package/vendor/procedural-animals/src/species/wolf/behaviour.js

@@ -0,0 +1,160 @@
+// Wolf body language, layered over the core actions every frame (species.motion.hooks.update, see
+// core/motion/actions.js).
+//
+// Tail carriage by mood (Schenkel 1947 in Mech & Boitani 2003): hangs at rest, ~level in the
+// travelling trot (the carriage table in motion.js), raised stiff above the back in a threat or an
+// attack, tucked between the hind legs when hit or afraid. Ears: pricked forward when alert (a look
+// target), pinned flat in an attack (core) and when howling. Hackles: the long guard hair of the
+// mane, cape and saddle lifts during an attack (P.furRaise -> the coat shader). Snarl: the jaw opens
+// on the crouch before the bite so the canines show. Howling: an idle variant every 25-60 s of
+// standing still (or on demand via `motion.input.howl = true`): head thrown back 50-60 deg, ears
+// back, jaw half open in an "O", lasting 3-6 s.
+import { clamp, smooth, lerp, angDiff } from '../../core/motion/common.js';
+import { mx, mxLegs } from '../../core/motion/actions.js';
+const sm = (w) => w * w * (3 - 2 * w);
+
+// moveTo: a wolf slows down to turn onto a point close beside or behind it. The engine caps the speed
+// only by the heading error (1.5 sk beyond 1.2 rad), so with the wolf's calm turn rate (1.8 rad/s) a
+// target inside its turning circle was circled without end. A point is reachable
+// on a turn of radius R only while it lies outside the turning circle on its side: R < d / (2 sin err)
+// (d distance, err bearing from the heading). The speed is capped so the radius at the engine's yaw
+// limit, v / w(v), keeps a margin inside that bound; near the point and well off the heading the wolf
+// all but pivots, then goes. (Engine-wide, the same cap belongs in quadruped.js drive().)
+const ARRIVE_MARGIN = 0.8;
+function arriveCap(e, st) {
+  const inp = e.input, cfg = e.cfg;
+  // arrived (drive() dropped the target and zeroed the speed): stand facing the way it went instead of
+  // pivoting on to the last bearing of the point (a front paw dragged ~2 % S in that pivot)
+  if (st.tgt && !inp.target && !inp.follow && !inp.speed && Math.hypot(st.tgt.x - e.pos.x, st.tgt.z - e.pos.z) < 0.5 * cfg.k + 0.03 * e.speed) {
+    inp.heading = e.heading + 0.25 * e.yawRate;
+    e.wantHeading = inp.heading;
+  }
+  st.tgt = inp.target && !inp.follow ? (st.tgt || { x: 0, z: 0 }) : null;
+  if (!st.tgt) return;
+  st.tgt.x = inp.target.x; st.tgt.z = inp.target.z;
+  if (!(e.wantSpeed > 0.05) || e.air?.active) return;
+  const dx = inp.target.x - e.pos.x, dz = inp.target.z - e.pos.z, d = Math.hypot(dx, dz);
+  const err = Math.abs(angDiff(e.heading, Math.atan2(dx, dz))), sn = Math.sin(err);
+  if (sn < 1e-3) return;
+  const rMax = (ARRIVE_MARGIN * d) / (2 * sn);
+  // the engine's yaw-rate limit at speed v (quadruped.js step: pivots are slower than turns on the move)
+  const wAt = (v) => Math.min(cfg.turnRate * lerp(0.55, 1, smooth(0.3, 2, v / cfg.sq)), cfg.latAccelMax / Math.max(v, 0.5 * cfg.sk));
+  if (e.wantSpeed / wAt(e.wantSpeed) <= rMax) return;
+  // v / w(v) grows with v: bisect for the fastest speed whose turning radius fits
+  let lo = 0, hi = e.wantSpeed;
+  for (let i = 0; i < 12; i++) { const m = 0.5 * (lo + hi); if (m / wAt(m) <= rMax) lo = m; else hi = m; }
+  // (a point ahead that the straight line passes within the stop radius needs no turn: the cap fades out)
+  const stopR = 0.35 * cfg.k + 0.02 * e.speed;
+  e.wantSpeed = lerp(e.wantSpeed, lo, err < 1.2 ? smooth(0.4 * stopR, 0.8 * stopR, d * sn) : 1);
+}
+
+export function wolfUpdate(P, dt, L) {
+  const e = L.engine;
+  const st = L._wolf || (L._wolf = { howlIn: 25 + e.rand() * 20, howlT: -1, howlDur: 4, howlW: 0 });
+  arriveCap(e, st);
+  // (the sleeping forepaw pull-back below overrides this animal's fold placement only while it sleeps)
+  if (st.acts && st.acts.fold && !L.postures.some((p) => p.name === 'sleep')) st.acts.fold = undefined;
+  let raise = 0;
+
+  for (const a of L.oneshots) {
+    const w = sm(a.w);
+    if (w <= 0) continue;
+    if (a.name === 'attack') {
+      const t = a.t;
+      // threat -> lunge: hackles up, tail raised stiff above the back, snarl before the bite
+      raise = Math.max(raise, w * (0.5 + 0.5 * smooth(0, 0.2, t)));
+      mx(P, 'tailLift', 0.75, w); mx(P, 'tailStiff', 1.8, w);
+      const snarl = smooth(0.0, 0.12, t) * (1 - smooth(0.22, 0.3, t));
+      P.jaw = Math.max(P.jaw, 0.3 * snarl * w); // (the lower fangs come clear of the upper lip)
+      mx(P, 'headRaise', -0.035, snarl * w);
+    } else if (a.name === 'hit') {
+      // flinch: tail clamped between the hind legs, ears flat (core), body drops (core)
+      const k = w * (1 - smooth(0.45, 0.75, a.t) * 0.6);
+      mx(P, 'tailLift', -0.8, k); mx(P, 'tailStiff', 1.6, k); mx(P, 'tailIdle', 0, k);
+    }
+  }
+  // dying / dead: ears folded back flat against the neck
+  for (const p of L.postures) {
+    if (p.name === 'death') { const w = sm(clamp(p.w, 0, 1)) * smooth(0.3, 1.0, p.t); mx(P, 'earFlat', 1.15, w); mx(P, 'earTwitch', 0, w); mx(P, 'headRoll', p.side * 0.8, w); P.headPos.y += 0.05 * e.cfg.s * w; }
+  }
+  // curled sleep (curled1: a ring on one hip, the nose tucked by the tail). The spine
+  // bends into a C (2.2 rad, rolled 0.45 onto the hip, the hind legs to the inside); the head turns back
+  // along the inside of the curl and rests on the ground by the hind feet (yaw 2.3 rad; the occiput 20 cm
+  // inside and 5 cm ahead of the turned chest's shoulders, 10 cm up: further back, the throat's stretch
+  // > 3x rose past 4 % of its triangles); the brush sweeps round the outside of the hind feet and forward
+  // to the nose (tailSide 3.4 curves it progressively, tailCurl -0.5 holds the root back: the old 2.4 rad
+  // turned it near the root and tucked it under the belly). The forelegs stay forward on the ground, as in
+  // curled1: tucked (the core's tuck places them in the unbent body frame, ~26 cm off, and the elbow
+  // flipped on the way out), reached (the paw stands up) or turned with the chest (the inner elbow dropped
+  // into the ground: 7-23 mm) they failed the metrics. (roll 0.45: 0.65 pressed the lower forearm 9-14 mm
+  // into the ground, 0.5 up to 6 mm)
+  for (const p of L.postures) {
+    if (p.name === 'sleep' && p.tune.style !== 'lateral') {
+      const c = sm(clamp(p.w, 0, 1)) * smooth(1.2, 3.2, p.t), side = p.side, k = e.cfg.k, fr = e.fr;
+      mx(P, 'roll', side * 0.45, c); mx(P, 'bend', side * 2.2, c);
+      mxLegs(P, 'side', 0, 0.55, c); mxLegs(P, 'spread', 0, 0, c);
+      // forelegs drawn back under the head (curled1: the paws just show at the front of the ring, not a leg's
+      // length ahead of it like a sphinx's): the engine's fold places the forepaw at zS + actions.fold.front.z
+      // leg lengths, flat on the ground; this animal's own copy of that tuning moves it 25 cm back once the
+      // curl has settled, the forearm and paw kept flat and the elbows folding up beside the chest. (A 'reach'
+      // blend stood the paw up and swung the elbow 10 mm into the ground; a 'sit' blend stood the forelegs up
+      // like posts; the core's tuck places the paw in the unbent body frame, ~26 cm off.) Skin penetration
+      // 0.30-0.62 % S (seeds 1-4, every morph, both sides).
+      const cF = sm(clamp(p.w, 0, 1)) * smooth(2.6, 4.4, p.t);
+      if (!st.acts) { st.acts = { ...e.cfg.actions }; e.cfg.actions = st.acts; }
+      const L0 = e.legs[0].def, z0 = (0.5 * L0.Lr + L0.Lmc) / L0.len;
+      // (k -1.45, beta 0 and z0 are the engine's own fold values: continuous as the pull-back fades)
+      st.acts.fold = cF > 1e-3 ? { front: { z: z0 - (cF * 0.25 * k) / L0.len, k: -1.45, beta: 0 } } : undefined;
+      mx(P, 'headYaw', side * 2.3, c);
+      // the chest's flat forward and left (its frame is the last frame's: the posture changes slowly)
+      const q = fr.qCh;
+      let fx = 2 * (q.x * q.z + q.w * q.y), fz = 1 - 2 * (q.x * q.x + q.y * q.y);
+      const fl = Math.hypot(fx, fz) || 1; fx /= fl; fz /= fl;
+      const lat = side * 0.2 * k, fwd = 0.05 * k;
+      const tx = fr.shC.x + fz * lat + fx * fwd, tz = fr.shC.z - fx * lat + fz * fwd;
+      const hp = P.headPos;
+      hp.x += (tx - hp.x) * c; hp.z += (tz - hp.z) * c; hp.y += (e.terrainH(tx, tz) + 0.1 * k - hp.y) * c;
+      mx(P, 'tailCurl', side * -0.5, c); mx(P, 'tailSide', side * 3.4, c); mx(P, 'tailStiff', 0.7, c);
+    }
+  }
+
+  // lying: rolled onto one hip, both hind legs to that side (lying1), not a symmetric sphinx
+  for (const p of L.postures) {
+    if (p.name === 'lie') {
+      const w = sm(clamp(p.w, 0, 1)) * smooth(0.6, 1.8, p.t);
+      mx(P, 'roll', p.side * 0.25, w);
+      mxLegs(P, 'side', 0, 0.5, w);
+    }
+  }
+
+  // alert: ears pricked forward while watching something
+  const idleW = L.idle.w;
+  if (e.input.look && raise < 0.01) mx(P, 'earFlat', -0.18, clamp(P.lookW, 0, 1));
+
+  // howling (idle variant)
+  const still = idleW > 0.95 && !L.postures.length && !L.oneshots.some((a) => !a.stopping && a.name !== 'hit');
+  if (st.howlT < 0) {
+    if (still) st.howlIn -= dt;
+    if (e.input.howl && idleW > 0.3) { e.input.howl = false; st.howlIn = 0; }
+    if (st.howlIn <= 0 && still) { st.howlT = 0; st.howlDur = 3 + e.rand() * 3; }
+  } else {
+    st.howlT += dt;
+    if (!still && idleW < 0.6) st.howlT = Math.max(st.howlT, st.howlDur);
+    if (st.howlT > st.howlDur + 1.2) { st.howlT = -1; st.howlIn = 25 + e.rand() * 35; }
+  }
+  const hw = st.howlT < 0 ? 0 : smooth(0, 0.9, st.howlT) * (1 - smooth(st.howlDur, st.howlDur + 1.2, st.howlT));
+  st.howlW = hw;
+  if (hw > 0.001) {
+    const w = hw * idleW;
+    mx(P, 'lookW', 0, w);
+    mx(P, 'headRaise', 0.07, w); mx(P, 'neckReach', -0.03, w);
+    mx(P, 'headPitch', -1.0, w);
+    // the "O" opens after the head is up, with a slight waver
+    const o = smooth(0.5, 1.2, st.howlT) * (1 - smooth(st.howlDur - 0.3, st.howlDur + 0.4, st.howlT));
+    mx(P, 'jaw', 0.2 + 0.03 * Math.sin(st.howlT * 5.1), o * w); mx(P, 'jawOmega', 6, w);
+    mx(P, 'earFlat', 0.55, w); mx(P, 'earTwitch', 0, w);
+    mx(P, 'breathAmp', 0.4, w); mx(P, 'eyelid', 0.45, o * w);
+    mx(P, 'dropH', 0.05, w);
+  }
+  P.furRaise = Math.max(P.furRaise || 0, raise);
+}