@jgengine/core 0.26.0 → 0.28.0

package/dist/ai/policeResponse.js

@@ -0,0 +1,421 @@
+import { devtools } from "../devtools/devtools.js";
+import { advanceHeat, createHeatState, } from "./heatSystem.js";
+/** The starting tier table: patrol until heat arrives, then investigate, pursue and finally cordon. */
+export const DEFAULT_POLICE_TIERS = [
+    { response: "investigate", threshold: 20, pursuers: 1, searchRadius: 25, roadblocks: 0 },
+    { response: "pursue", threshold: 60, pursuers: 3, searchRadius: 40, roadblocks: 0 },
+    { response: "roadblock", threshold: 120, pursuers: 5, searchRadius: 55, roadblocks: 3 },
+];
+/** The starting policy: linear decay, a six-second escape and a search area that grows at 2 m/s. */
+export const DEFAULT_POLICE_TUNING = {
+    tiers: DEFAULT_POLICE_TIERS,
+    decayPerSecond: 10,
+    decayDelaySeconds: 0,
+    standDownSeconds: 6,
+    escapeSeconds: 6,
+    inViewGraceSeconds: 0.25,
+    searchGrowthPerSecond: 2,
+    searchRadiusMax: 90,
+    searchLaneLimit: 12,
+    roadblockLimit: 4,
+    seed: 1,
+};
+const MAX_PENDING_CRIMES = 64;
+function resolveTuning(base, patch) {
+    const next = { ...base, tiers: base.tiers.map((tier) => ({ ...tier })) };
+    if (patch !== undefined) {
+        if (patch.tiers !== undefined)
+            next.tiers = patch.tiers.map((tier) => ({ ...tier }));
+        for (const key of [
+            "decayPerSecond",
+            "decayDelaySeconds",
+            "standDownSeconds",
+            "escapeSeconds",
+            "inViewGraceSeconds",
+            "searchGrowthPerSecond",
+            "searchRadiusMax",
+            "searchLaneLimit",
+            "roadblockLimit",
+        ]) {
+            const value = patch[key];
+            if (typeof value === "number" && Number.isFinite(value))
+                next[key] = Math.max(0, value);
+        }
+        if (typeof patch.maxHeat === "number" && Number.isFinite(patch.maxHeat))
+            next.maxHeat = Math.max(0, patch.maxHeat);
+        if (patch.spawnRingRadius !== undefined) {
+            next.spawnRingRadius = [patch.spawnRingRadius[0], patch.spawnRingRadius[1]];
+        }
+        if (typeof patch.seed === "number" && Number.isFinite(patch.seed))
+            next.seed = patch.seed;
+    }
+    next.inViewGraceSeconds = Math.max(0.001, next.inViewGraceSeconds);
+    next.escapeSeconds = Math.max(0.001, next.escapeSeconds);
+    next.searchLaneLimit = Math.max(0, Math.floor(next.searchLaneLimit));
+    next.roadblockLimit = Math.max(0, Math.floor(next.roadblockLimit));
+    validateTuning(next);
+    return next;
+}
+function validateTuning(tuning) {
+    if (tuning.tiers.length === 0)
+        throw new Error("tiers must hold at least one entry.");
+    let previous = -Infinity;
+    for (const tier of tuning.tiers) {
+        if (!Number.isFinite(tier.threshold) || tier.threshold < 0)
+            throw new Error(`tier "${tier.response}" threshold must be non-negative.`);
+        if (tier.threshold <= previous)
+            throw new Error("tiers must ascend by threshold.");
+        previous = tier.threshold;
+        for (const field of ["pursuers", "searchRadius", "roadblocks"]) {
+            const value = tier[field];
+            if (!Number.isFinite(value) || value < 0)
+                throw new Error(`tier "${tier.response}" ${field} must be non-negative.`);
+        }
+    }
+    if (!Number.isFinite(tuning.decayPerSecond) || tuning.decayPerSecond < 0)
+        throw new Error("decayPerSecond must be non-negative.");
+    if (!Number.isFinite(tuning.searchRadiusMax) || tuning.searchRadiusMax < 0)
+        throw new Error("searchRadiusMax must be non-negative.");
+    if (tuning.spawnRingRadius !== undefined) {
+        const [min, max] = tuning.spawnRingRadius;
+        if (!Number.isFinite(min) || !Number.isFinite(max) || min < 0 || max < min) {
+            throw new Error("spawnRingRadius must be a finite [min, max] with min >= 0.");
+        }
+    }
+}
+function heatConfigOf(tuning) {
+    return {
+        levels: tuning.tiers.map((tier, index) => ({ level: index + 1, threshold: tier.threshold, pursuerBudget: tier.pursuers })),
+        ...(tuning.maxHeat === undefined ? {} : { maxHeat: tuning.maxHeat }),
+        decayPerSecond: tuning.decayPerSecond,
+        decayDelaySeconds: tuning.decayDelaySeconds,
+        standDownSeconds: tuning.standDownSeconds,
+        ...(tuning.spawnRingRadius === undefined ? {} : { spawnRingRadius: tuning.spawnRingRadius }),
+        ...(tuning.seed === undefined ? {} : { seed: tuning.seed }),
+    };
+}
+function tierFor(tiers, heat) {
+    let current = null;
+    for (const tier of tiers)
+        if (heat >= tier.threshold)
+            current = tier;
+    return current;
+}
+/**
+ * The wanted level a crime sandbox needs, over the shared heat curve: a crime raises heat only while
+ * a witness holds the suspect in view, the heat bleeds on a stated linear curve once the suspect has
+ * been out of every witness's sight for `escapeSeconds`, the tier table decides what police do
+ * (patrol → investigate → pursue → roadblock), the search area sits where the suspect was last seen
+ * and grows while the trail is cold, and a roadblock tier cordons it with authored sites off the lane
+ * graph. Heat, tiers and curves are caller policy; witness facts come from `sensor/perception` memory
+ * (`sourceId`/`sourceTick` kept), so there is no second sight path.
+ *
+ * Deterministic: observers are asked in roster order, ties break on id, and the injected generator is
+ * the only source of variety. Bounded per tick: one memory query per observer, one indexed lane query,
+ * one pass over the authored roadblock sites, no path search.
+ *
+ * @capability police-response witness-gated heat, tiered police response, last-sighting search areas and lane-graph roadblocks
+ */
+export function createPoliceResponse(config) {
+    const witness = config.witness;
+    const observers = config.observers;
+    const suspectId = config.suspectId;
+    const roads = config.roads;
+    let tuning = resolveTuning(DEFAULT_POLICE_TUNING, config);
+    let heatState = createHeatState(heatConfigOf(tuning));
+    let outOfSightSeconds = 0;
+    let escaped = false;
+    let lastSighting = null;
+    const pending = [];
+    let lastTier = null;
+    let lastArea = null;
+    let lastRoadblocks = [];
+    let counters = { ticks: 0, crimes: 0, witnessed: 0, sightings: 0, escapes: 0, roadblockTicks: 0, slowestTickMs: 0 };
+    let sightingsChecked = 0;
+    let lanesInArea = 0;
+    let roadblockSites = 0;
+    /** The freshest sighting on the roster, which is also what "in view" and the search area read. */
+    function freshest() {
+        let best = null;
+        sightingsChecked = 0;
+        for (const observerId of observers()) {
+            sightingsChecked += 1;
+            const sighting = witness.memoryOf(observerId, suspectId);
+            if (sighting === null)
+                continue;
+            if (best === null || sighting.lastSeenAt > best.lastSeenAt)
+                best = sighting;
+        }
+        return best;
+    }
+    function responseLine() {
+        const area = lastArea === null ? "no area" : `${lastArea.radius.toFixed(0)} m area ${lastArea.lanes.length} lanes`;
+        return (`${heatState.heat.toFixed(0)} heat ${lastTier?.response ?? "patrol"} ${area} ${lastRoadblocks.length} roadblocks ` +
+            `${outOfSightSeconds.toFixed(1)} s out of sight ${counters.escapes} escapes ` +
+            `${counters.witnessed}/${counters.crimes} witnessed ${counters.slowestTickMs.toFixed(2)} ms slowest`);
+    }
+    const unregister = config.devtoolsName === undefined ? null : devtools.probes.register(config.devtoolsName, () => responseLine());
+    function advance(dt, ctx) {
+        const started = performance.now();
+        const sighting = freshest();
+        const inView = sighting !== null && ctx.nowMs - sighting.lastSeenAt <= tuning.inViewGraceSeconds * 1000;
+        if (sighting !== null && (lastSighting === null || sighting.lastSeenAt > lastSighting.at)) {
+            lastSighting = {
+                position: [sighting.lastKnownPos[0], sighting.lastKnownPos[2]],
+                at: sighting.lastSeenAt,
+                sourceId: sighting.sourceId,
+                sourceTick: sighting.sourceTick,
+            };
+            counters.sightings += 1;
+        }
+        outOfSightSeconds = inView ? 0 : outOfSightSeconds + dt;
+        const nowEscaped = outOfSightSeconds >= tuning.escapeSeconds;
+        if (nowEscaped && !escaped)
+            counters.escapes += 1;
+        escaped = nowEscaped;
+        const gains = [];
+        for (const amount of pending)
+            gains.push({ amount, witnessed: inView });
+        counters.crimes += pending.length;
+        if (inView)
+            counters.witnessed += pending.length;
+        pending.length = 0;
+        const heatStep = advanceHeat(heatConfigOf(tuning), heatState, dt, gains, {
+            nearWitness: !escaped,
+            activePursuers: ctx.activePursuers,
+            around: ctx.around,
+        });
+        heatState = heatStep.state;
+        const tier = tierFor(tuning.tiers, heatState.heat);
+        const tierChanged = (tier?.threshold ?? null) !== (lastTier?.threshold ?? null);
+        lastTier = tier;
+        let area = null;
+        lanesInArea = 0;
+        if (tier !== null && lastSighting !== null) {
+            const radius = Math.min(tuning.searchRadiusMax, tier.searchRadius + outOfSightSeconds * tuning.searchGrowthPerSecond);
+            const lanes = roads === undefined ? [] : roads.lanesNear(lastSighting.position[0], lastSighting.position[1], radius, tuning.searchLaneLimit);
+            lanesInArea = lanes.length;
+            area = {
+                center: lastSighting.position,
+                radius,
+                lanes: lanes.map((hit) => hit.lane),
+                lastSeenAt: lastSighting.at,
+                sourceId: lastSighting.sourceId,
+                sourceTick: lastSighting.sourceTick,
+            };
+        }
+        lastArea = area;
+        let roadblocks = [];
+        roadblockSites = 0;
+        if (tier !== null && tier.roadblocks > 0 && area !== null && roads !== undefined) {
+            const wanted = Math.min(tier.roadblocks, tuning.roadblockLimit);
+            const inside = [];
+            for (const site of roads.roadblockSites()) {
+                const distance = Math.hypot(site.at[0] - area.center[0], site.at[1] - area.center[1]);
+                if (distance > area.radius)
+                    continue;
+                inside.push({ site, distance });
+            }
+            roadblockSites = inside.length;
+            inside.sort((a, b) => a.distance - b.distance || (a.site.id < b.site.id ? -1 : a.site.id > b.site.id ? 1 : 0));
+            roadblocks = inside.slice(0, wanted).map((entry) => entry.site);
+            if (roadblocks.length > 0)
+                counters.roadblockTicks += 1;
+        }
+        lastRoadblocks = roadblocks;
+        counters.ticks += 1;
+        counters.slowestTickMs = Math.max(counters.slowestTickMs, performance.now() - started);
+        return {
+            heat: heatState.heat,
+            tier,
+            response: tier?.response ?? "patrol",
+            tierChanged,
+            pursuerBudget: heatStep.pursuerBudget,
+            wantPursuers: heatStep.wantSpawns,
+            spawnPoints: heatStep.spawnPoints,
+            searchArea: area,
+            roadblocks,
+            outOfSightSeconds,
+            escaped,
+            standDown: heatStep.standDown,
+        };
+    }
+    return {
+        reportCrime(amount) {
+            if (!Number.isFinite(amount) || amount <= 0)
+                throw new Error("reportCrime amount must be positive.");
+            pending.push(amount);
+            if (pending.length > MAX_PENDING_CRIMES)
+                pending.shift();
+        },
+        tick(dt, ctx) {
+            if (!Number.isFinite(dt) || dt < 0)
+                throw new Error("dt must be finite and non-negative.");
+            if (!Number.isFinite(ctx.nowMs))
+                throw new Error("ctx.nowMs must be finite.");
+            return advance(dt, ctx);
+        },
+        wanted: () => ({ heat: heatState.heat, tier: lastTier, response: lastTier?.response ?? "patrol" }),
+        searchArea: () => lastArea,
+        roadblocks: () => lastRoadblocks,
+        stats: () => ({
+            heat: heatState.heat,
+            response: lastTier?.response ?? "patrol",
+            ticks: counters.ticks,
+            crimes: counters.crimes,
+            witnessed: counters.witnessed,
+            sightings: counters.sightings,
+            escapes: counters.escapes,
+            roadblockTicks: counters.roadblockTicks,
+            sightingsChecked,
+            lanesInArea,
+            roadblockSites,
+            slowestTickMs: counters.slowestTickMs,
+        }),
+        retune(patch) {
+            tuning = resolveTuning(tuning, patch);
+        },
+        state() {
+            return {
+                tunables: { ...tuning, tiers: tuning.tiers.map((tier) => ({ ...tier })) },
+                heat: { ...heatState },
+                outOfSightSeconds,
+                lastSighting: lastSighting === null ? null : { ...lastSighting, position: [...lastSighting.position] },
+                pending: pending.slice(),
+                counters: {
+                    ticks: counters.ticks,
+                    crimes: counters.crimes,
+                    witnessed: counters.witnessed,
+                    sightings: counters.sightings,
+                    escapes: counters.escapes,
+                    roadblockTicks: counters.roadblockTicks,
+                },
+            };
+        },
+        restore(next) {
+            tuning = resolveTuning(DEFAULT_POLICE_TUNING, next.tunables);
+            heatState = { ...next.heat };
+            outOfSightSeconds = Math.max(0, next.outOfSightSeconds);
+            lastSighting =
+                next.lastSighting === null
+                    ? null
+                    : { ...next.lastSighting, position: [...next.lastSighting.position] };
+            pending.length = 0;
+            for (const amount of next.pending)
+                pending.push(amount);
+            counters = { ...next.counters, slowestTickMs: 0 };
+            escaped = outOfSightSeconds >= tuning.escapeSeconds;
+            lastTier = tierFor(tuning.tiers, heatState.heat);
+            lastArea = null;
+            lastRoadblocks = [];
+            lanesInArea = 0;
+            roadblockSites = 0;
+            sightingsChecked = 0;
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}
+/**
+ * Read the police road data out of an authored lane graph: `traffic_roadblock` markers become
+ * cordon sites projected onto the lane they block, and lanes are indexed so `lanesNear` answers from
+ * the local cells rather than a scan of every lane. With no roadblock markers authored, the graph's
+ * intersections are the sites, so a cordon still sits where streets meet. Built once; the index is
+ * rebuildable from the document, so it is never serialized.
+ *
+ * @capability police-roads lane-graph roadblock sites and an indexed nearby-lane query for search areas
+ */
+export function policeRoadsFromLaneGraph(graph, markers = [], options = {}) {
+    const cellSize = Math.max(0.5, options.cellSize ?? 8);
+    const joinRadius = Math.max(0, options.joinRadius ?? 8);
+    const kinds = new Set(options.roadblockKinds ?? ["traffic_roadblock"]);
+    const buckets = new Map();
+    const step = Math.max(0.5, cellSize / 2);
+    for (const laneId of graph.laneIds()) {
+        const lane = graph.lane(laneId);
+        if (lane === null)
+            continue;
+        for (let i = 0; i < lane.points.length - 1; i += 1) {
+            const a = lane.points[i];
+            const b = lane.points[i + 1];
+            const span = Math.hypot(b[0] - a[0], b[2] - a[2]);
+            const steps = Math.max(1, Math.ceil(span / step));
+            for (let s = 0; s <= steps; s += 1) {
+                const t = s / steps;
+                const key = `${Math.floor((a[0] + (b[0] - a[0]) * t) / cellSize)},${Math.floor((a[2] + (b[2] - a[2]) * t) / cellSize)}`;
+                let bucket = buckets.get(key);
+                if (bucket === undefined) {
+                    bucket = new Set();
+                    buckets.set(key, bucket);
+                }
+                bucket.add(laneId);
+            }
+        }
+    }
+    function lanesNear(x, z, radius, limit) {
+        if (!(radius > 0) || limit <= 0)
+            return [];
+        const hits = [];
+        const seen = new Set();
+        for (let cx = Math.floor((x - radius) / cellSize); cx <= Math.floor((x + radius) / cellSize); cx += 1) {
+            for (let cz = Math.floor((z - radius) / cellSize); cz <= Math.floor((z + radius) / cellSize); cz += 1) {
+                const bucket = buckets.get(`${cx},${cz}`);
+                if (bucket === undefined)
+                    continue;
+                for (const laneId of bucket) {
+                    if (seen.has(laneId))
+                        continue;
+                    seen.add(laneId);
+                    const arc = graph.project(laneId, x, z);
+                    const pose = graph.pose(laneId, arc);
+                    if (pose === null)
+                        continue;
+                    const distance = Math.hypot(pose.position[0] - x, pose.position[2] - z);
+                    if (distance > radius)
+                        continue;
+                    hits.push({ lane: laneId, arc, distance });
+                }
+            }
+        }
+        hits.sort((a, b) => a.distance - b.distance || (a.lane < b.lane ? -1 : a.lane > b.lane ? 1 : 0));
+        return hits.slice(0, limit);
+    }
+    const sites = [];
+    for (const marker of markers) {
+        if (!kinds.has(marker.kind))
+            continue;
+        const hit = lanesNear(marker.position.x, marker.position.z, joinRadius, 1)[0];
+        if (hit === undefined)
+            continue;
+        const pose = graph.pose(hit.lane, hit.arc);
+        if (pose === null)
+            continue;
+        sites.push({
+            id: marker.id,
+            lane: hit.lane,
+            arc: hit.arc,
+            at: [pose.position[0], pose.position[2]],
+            heading: pose.heading,
+        });
+    }
+    if (sites.length === 0) {
+        for (const intersection of graph.intersections()) {
+            const lane = intersection.outLanes[0];
+            if (lane === undefined)
+                continue;
+            sites.push({
+                id: `node:${intersection.node}`,
+                lane,
+                arc: 0,
+                at: [intersection.at[0], intersection.at[2]],
+                heading: graph.heading(lane, 0),
+            });
+        }
+    }
+    sites.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return {
+        lanesNear,
+        roadblockSites: () => sites,
+    };
+}

package/dist/anim/actionLayer.d.ts

@@ -0,0 +1,47 @@
+import type { AnimGraph, AnimLayer } from "./animGraph.js";
+/** A masked, optionally additive overlay layer: a resting clip plus one one-shot state per action. */
+export interface ActionLayerInput {
+    /** Layer id; also the prefix of its action state ids (`id:action`). */
+    id: string;
+    /**
+     * Bone name prefixes this layer drives (`["spine", "chest", "upperarm"]`). Required and nonempty:
+     * an overlay that names no bones would silently drive the whole rig. `UPPER_BODY_MASK` and
+     * `LOWER_BODY_MASK` (`@jgengine/core/anim/skeletonStandard`) cover a standard rig.
+     */
+    mask: readonly string[];
+    /**
+     * Clip held while no action plays. On an additive layer this state is held at its first frame,
+     * which `makeClipAdditive` makes the zero reference, so rest contributes nothing to the pose.
+     */
+    rest: string;
+    /** Trigger name → clip, or clips for a random variant, played once over the rest state. */
+    actions: Readonly<Record<string, string | readonly string[]>>;
+    /** Add the actions to the base pose instead of replacing the masked bones. Default false. */
+    additive?: boolean;
+    /** Layer influence `0..1`. Default 1. */
+    weight?: number;
+    /** Crossfade seconds into and out of an action. Default 0.1. */
+    fadeSec?: number;
+    /** Normalized time an action must reach before it returns to rest. Default 1. */
+    exitTime?: number;
+}
+/** State id of an action layer's resting state. */
+export declare const ACTION_REST_STATE = "rest";
+/**
+ * One overlay layer from plain data: a resting state plus a one-shot state per action, each joined
+ * to the rest by a consumed-trigger transition and returning on `exitTime`. Aim, reload, wave and
+ * hit reactions are the same shape, so they are one builder instead of a hand-written state machine
+ * per game. The layer is masked by bone prefix, and `additive: true` makes it a recoil/breathing
+ * overlay on top of the base pose rather than a replacement.
+ *
+ * @capability animation build a masked one-shot overlay layer for upper-body actions and hit reactions
+ */
+export declare function actionLayer(input: ActionLayerInput): AnimLayer;
+/**
+ * A graph plus overlay layers: the base layers keep their ids and order, and each overlay is
+ * appended. Duplicate layer ids are rejected rather than silently shadowing, because the shell keys
+ * its mixer actions by layer id.
+ *
+ * @capability animation attach masked action layers to a locomotion graph
+ */
+export declare function withActionLayers(graph: AnimGraph, layers: readonly ActionLayerInput[]): AnimGraph;

package/dist/anim/actionLayer.js

@@ -0,0 +1,63 @@
+/** State id of an action layer's resting state. */
+export const ACTION_REST_STATE = "rest";
+/**
+ * One overlay layer from plain data: a resting state plus a one-shot state per action, each joined
+ * to the rest by a consumed-trigger transition and returning on `exitTime`. Aim, reload, wave and
+ * hit reactions are the same shape, so they are one builder instead of a hand-written state machine
+ * per game. The layer is masked by bone prefix, and `additive: true` makes it a recoil/breathing
+ * overlay on top of the base pose rather than a replacement.
+ *
+ * @capability animation build a masked one-shot overlay layer for upper-body actions and hit reactions
+ */
+export function actionLayer(input) {
+    const mask = input.mask.map((prefix) => prefix.trim()).filter((prefix) => prefix.length > 0);
+    if (mask.length === 0)
+        throw new Error(`action layer "${input.id}" needs at least one bone name prefix in its mask`);
+    if (input.rest.trim().length === 0)
+        throw new Error(`action layer "${input.id}" needs a nonempty rest clip`);
+    const fade = input.fadeSec ?? 0.1;
+    const exitTime = input.exitTime ?? 1;
+    const states = {
+        [ACTION_REST_STATE]: input.additive === true
+            ? { kind: "clip", clip: input.rest, loop: true, speed: 0 }
+            : { kind: "clip", clip: input.rest, loop: true },
+    };
+    const transitions = [];
+    for (const [name, spec] of Object.entries(input.actions)) {
+        const clips = typeof spec === "string" ? [spec] : spec;
+        if (clips.length === 0 || clips[0].trim().length === 0)
+            continue;
+        if (name === ACTION_REST_STATE)
+            throw new Error(`action layer "${input.id}" cannot name an action "${ACTION_REST_STATE}"; that id is the resting state`);
+        states[name] = { kind: "clip", clip: clips[0], loop: false, ...(clips.length < 2 ? {} : { variants: [...clips] }) };
+        transitions.push({ from: ACTION_REST_STATE, to: name, trigger: name, duration: fade });
+        transitions.push({ from: name, to: ACTION_REST_STATE, exitTime, duration: fade });
+    }
+    return {
+        id: input.id,
+        entry: ACTION_REST_STATE,
+        states,
+        transitions,
+        mask,
+        ...(input.additive === true ? { additive: true } : {}),
+        ...(input.weight === undefined ? {} : { weight: input.weight }),
+    };
+}
+/**
+ * A graph plus overlay layers: the base layers keep their ids and order, and each overlay is
+ * appended. Duplicate layer ids are rejected rather than silently shadowing, because the shell keys
+ * its mixer actions by layer id.
+ *
+ * @capability animation attach masked action layers to a locomotion graph
+ */
+export function withActionLayers(graph, layers) {
+    const ids = new Set(graph.layers.map((layer) => layer.id));
+    const built = [];
+    for (const input of layers) {
+        if (ids.has(input.id))
+            throw new Error(`animation graph already has a layer "${input.id}"`);
+        ids.add(input.id);
+        built.push(actionLayer(input));
+    }
+    return { layers: [...graph.layers, ...built], ...(graph.events === undefined ? {} : { events: graph.events }) };
+}

package/dist/anim/ikSolver.d.ts

@@ -37,6 +37,20 @@ export interface LookAtInput {
  * @capability animation inverse kinematics solve a two-bone chain from a target and bend pole
  */
 export declare function solveTwoBone(input: TwoBoneInput, out: TwoBoneOutput): TwoBoneOutput;
+/**
+ * The product of two quaternions (`a` applied after `b`), both as `[x, y, z, w]`.
+ *
+ * @capability animation inverse kinematics compose two rotations
+ */
+export declare function multiplyQuaternions(a: Quat, b: Quat): Quat;
+/**
+ * The shortest rotation taking one unit direction to another, as a quaternion. Parallel directions
+ * give the identity; opposite directions give a half turn about a perpendicular axis. Returns the
+ * identity for a zero-length input.
+ *
+ * @capability animation inverse kinematics the shortest rotation between two directions
+ */
+export declare function quaternionFromUnitVectors(from: Vec3, to: Vec3): Quat;
 /**
  * Solves a chain with the FABRIK forward-and-backward reaching algorithm.
  * Returned tuples are new values; the input chain is not modified.

package/dist/anim/ikSolver.js

@@ -44,6 +44,43 @@ export function solveTwoBone(input, out) {
     out.tip[2] = clampedTarget[2];
     return out;
 }
+/**
+ * The product of two quaternions (`a` applied after `b`), both as `[x, y, z, w]`.
+ *
+ * @capability animation inverse kinematics compose two rotations
+ */
+export function multiplyQuaternions(a, b) {
+    return [
+        a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+        a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+        a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+        a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+    ];
+}
+/**
+ * The shortest rotation taking one unit direction to another, as a quaternion. Parallel directions
+ * give the identity; opposite directions give a half turn about a perpendicular axis. Returns the
+ * identity for a zero-length input.
+ *
+ * @capability animation inverse kinematics the shortest rotation between two directions
+ */
+export function quaternionFromUnitVectors(from, to) {
+    const a = normalize(from[0], from[1], from[2]);
+    const b = normalize(to[0], to[1], to[2]);
+    if (Math.hypot(...a) <= EPSILON || Math.hypot(...b) <= EPSILON)
+        return [0, 0, 0, 1];
+    const dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+    if (dot >= 1 - EPSILON)
+        return [0, 0, 0, 1];
+    if (dot <= -1 + EPSILON) {
+        const axis = Math.abs(a[0]) < 0.9 ? normalize(...cross(a, [1, 0, 0])) : normalize(...cross(a, [0, 1, 0]));
+        return [axis[0], axis[1], axis[2], 0];
+    }
+    const c = cross(a, b);
+    const q = [c[0], c[1], c[2], 1 + dot];
+    const length = Math.hypot(...q);
+    return [q[0] / length, q[1] / length, q[2] / length, q[3] / length];
+}
 /**
  * Solves a chain with the FABRIK forward-and-backward reaching algorithm.
  * Returned tuples are new values; the input chain is not modified.