Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

51.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    gripPose.ts
 * @brief   How a hand is held: a pistol grip, a hammer's handle, a cup, said once and fitting any hand.
 *
 * @details A pose stored as bone rotations belongs to the skeleton it was made on, since the bones of two rigs do not face the same way.
 *          So a GripPose says only what is true of a hand: how far each finger bends, how far it fans out, how far the thumb comes across.
 *          The axes are worked out from each rig's own hand, once, from where its joints stand: which way the palm faces, which way each
 *          finger points. What runs each frame is then a few quaternions a joint, and nothing at all once a hand has settled on a rig no clip moves.
 *
 *          It does not know what is held. Putting the hand on an object is the attachment's business; a holder can ask for the fingers
 *          to close onto the object's grip surfaces, which each finger then does joint by joint, the pose saying how far it may go.
 */
import type { App } from '../app/app';
import { defineComponent, getComponent, Children, Name, Parent, Transform, type ComponentDef, type TransformData } from '../ecs/component';
import { defineSystem, GetWorld, Schedule } from '../ecs/system';
import { Res, Time, type TimeData } from '../ecs/resource';
import type { World } from '../ecs/world';
import { resolveChildEntity } from '../ecs/childPath';
import { fxPreviewOrPlayMode } from '../ecs/env';
import { SystemLabel } from '../ecs/systemLabels';
import { log } from '../util/logger';
import { q } from '../math/quat';
import type { Entity } from '../types';
import { leanQuat } from './quatMix';
import { boneDistance, closeFinger, surfacesUnder, type PlacedSurface } from './gripContact';

/** How one finger is held. @experimental */
export interface GripFinger {
    /** How far it bends, 0 as the rig rests to 1 closed. */
    curl: number;
    /** How far its first joint bends, where that differs from the rest of it: a finger laid along a frame, or hooked. Defaults to `curl`. */
    base?: number;
    /** How far the fingers fan out from one another, -1 to 1. */
    spread?: number;
    /** Each joint's bend, knuckle first, in degrees from where the rig rests: what a hand posed joint by joint keeps. Over `curl` and `base`. */
    bend?: [number, number, number];
    /** How far this finger leans out from the middle of the hand, in degrees: the index and middle toward the thumb, the ring and little finger away. Over `spread`. */
    fan?: number;
}

/** How the thumb is held: as a reach, since where it can rest is somewhere on the other fingers. @experimental */
export interface GripThumb {
    /** How far it goes from where it rests to what it reaches for, 0 to 1. */
    opposition: number;
    /** What it reaches for: the middle of the middle finger, as a fist or a handle has it, or the index finger's tip, as a pinch does. Defaults to `fingers`. */
    to?: 'fingers' | 'index';
    /** How far short of them it stops, in lengths of the index finger: what is held between, a grip or a mug. Defaults to 0. */
    gap?: number;
}

/** How a whole hand is held. Nothing in it names a bone, so it fits any rig. @experimental */
export interface GripPoseDef {
    thumb: GripThumb;
    index: GripFinger;
    middle: GripFinger;
    ring: GripFinger;
    pinky: GripFinger;
    /** The index finger as `trigger` takes it to 1: pressing, where the finger above is resting. Absent, `trigger` does nothing. */
    trigger?: GripFinger;
}

const f = (curl: number, base?: number, spread?: number): GripFinger => ({ curl, ...(base !== undefined ? { base } : {}), ...(spread !== undefined ? { spread } : {}) });
const thumb = (opposition: number, gap = 0, to: 'fingers' | 'index' = 'fingers'): GripThumb => ({ opposition, gap, to });

const poses = new Map<string, GripPoseDef>(Object.entries({
    open: { thumb: thumb(0), index: f(0), middle: f(0), ring: f(0), pinky: f(0) },
    relaxed: { thumb: thumb(0.25, 0.6), index: f(0.18, 0.15), middle: f(0.25, 0.2), ring: f(0.3, 0.25), pinky: f(0.35, 0.3) },
    fist: { thumb: thumb(1), index: f(1), middle: f(1), ring: f(1), pinky: f(1) },
    pistol: {
        thumb: thumb(1, 0.4), index: f(0.1, 0.32), middle: f(0.78, 0.72), ring: f(0.82, 0.76), pinky: f(0.85, 0.8),
        trigger: f(0.55, 0.42),
    },
    support: { thumb: thumb(0.9, 0.5), index: f(0.4, 0.35), middle: f(0.45, 0.4), ring: f(0.48, 0.42), pinky: f(0.5, 0.45) },
    handle: { thumb: thumb(1, 0.1), index: f(0.78, 0.7), middle: f(0.82, 0.75), ring: f(0.85, 0.78), pinky: f(0.88, 0.8) },
    pinch: { thumb: thumb(1, 0, 'index'), index: f(0.55, 0.5), middle: f(0.25, 0.2), ring: f(0.25, 0.2), pinky: f(0.25, 0.2) },
    cup: { thumb: thumb(0.9, 0.8), index: f(0.45, 0.25, 0.3), middle: f(0.45, 0.25, 0.3), ring: f(0.45, 0.25, 0.3), pinky: f(0.45, 0.25, 0.3) },
} satisfies Record<string, GripPoseDef>));

/** Adds a pose of the game's own, or replaces one by name. @experimental */
export function registerGripPose(name: string, pose: GripPoseDef): void {
    poses.set(name, pose);
}

/** The names a `GripPose` component can take. @experimental */
export function gripPoseNames(): string[] {
    return [...poses.keys()];
}

/** The pose of that name, or undefined. @experimental */
export function gripPose(name: string): GripPoseDef | undefined {
    return poses.get(name);
}

/** The fields of the `GripPose` component. @experimental */
export interface GripPoseData {
    /** The pose each hand takes; empty leaves that hand to whatever else moves it. */
    rightPose: string;
    leftPose: string;
    /** How much of it applies, over what a clip is doing with the fingers. */
    rightWeight: number;
    leftWeight: number;
    /** How far the index finger has gone from resting to pressing. */
    rightTrigger: number;
    leftTrigger: number;
    /** About how long a change of pose takes, in seconds. */
    blendSeconds: number;
    /** The hand joint, by path from this entity. Empty looks for it by name. */
    rightHand: string;
    leftHand: string;
}

/**
 * Holds a rig's hands in a named pose. Goes on the rig's root.
 *
 * @experimental
 */
export const GripPose: ComponentDef<GripPoseData> = /* @__PURE__ */ defineComponent<GripPoseData>('GripPose', {
    rightPose: '', leftPose: '', rightWeight: 1, leftWeight: 1, rightTrigger: 0, leftTrigger: 0, blendSeconds: 0.15, rightHand: '', leftHand: '',
}, {
    fields: {
        rightPose: { category: 'Right Hand', tooltip: 'open, relaxed, fist, pistol, support, handle, pinch, cup, or one the game registers. Empty leaves the hand alone.' },
        rightWeight: { min: 0, max: 1, step: 0.01, category: 'Right Hand', tooltip: 'How much of the pose applies, over what a clip is doing with the fingers.' },
        rightTrigger: { min: 0, max: 1, step: 0.01, category: 'Right Hand', tooltip: 'How far the index finger has gone from resting to pressing, in a pose that has both.' },
        rightHand: { category: 'Right Hand', advanced: true, tooltip: 'The hand joint, by path from this entity. Empty looks for it by name.' },
        leftPose: { category: 'Left Hand', tooltip: 'open, relaxed, fist, pistol, support, handle, pinch, cup, or one the game registers. Empty leaves the hand alone.' },
        leftWeight: { min: 0, max: 1, step: 0.01, category: 'Left Hand', tooltip: 'How much of the pose applies, over what a clip is doing with the fingers.' },
        leftTrigger: { min: 0, max: 1, step: 0.01, category: 'Left Hand', tooltip: 'How far the index finger has gone from resting to pressing, in a pose that has both.' },
        leftHand: { category: 'Left Hand', advanced: true, tooltip: 'The hand joint, by path from this entity. Empty looks for it by name.' },
        blendSeconds: { min: 0, step: 0.01, unit: 's', tooltip: 'About how long a change of pose takes.' },
    },
});

interface Quat { w: number; x: number; y: number; z: number }
interface Vec3 { x: number; y: number; z: number }

/** The fingers, in the order a hand's numbers are kept. */
const FINGERS = ['thumb', 'index', 'middle', 'ring', 'pinky'] as const;
type FingerName = (typeof FINGERS)[number];

const NAME_OF: Record<FingerName, RegExp> = {
    thumb: /thumb/i, index: /index|pointer/i, middle: /middle/i, ring: /(?<![a-z])ring|[a-z]ring(?=[\d_.:-]|$)/i, pinky: /pinky|pinkie|little/i,
};
/** A bone inside the palm: nothing a pose bends, and what the first joint of a finger may hang from. */
const INSIDE_PALM = /metacarpal|palm/i;

/** How far each joint of a finger bends when it is closed: first, second, third. In radians. */
const CLOSED = [Math.PI / 2, (100 * Math.PI) / 180, (70 * Math.PI) / 180];
const SPREAD = (15 * Math.PI) / 180;
const FAN: Record<FingerName, number> = { thumb: 0, index: 1, middle: 0.15, ring: -0.6, pinky: -1 };

const add = (a: Vec3, b: Vec3): Vec3 => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z });
const sub = (a: Vec3, b: Vec3): Vec3 => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z });
const dot = (a: Vec3, b: Vec3): number => a.x * b.x + a.y * b.y + a.z * b.z;
const scale = (a: Vec3, k: number): Vec3 => ({ x: a.x * k, y: a.y * k, z: a.z * k });
const cross = (a: Vec3, b: Vec3): Vec3 => ({ x: a.y * b.z - a.z * b.y, y: a.z * b.x - a.x * b.z, z: a.x * b.y - a.y * b.x });
const norm = (a: Vec3): Vec3 => { const l = Math.hypot(a.x, a.y, a.z); return l < 1e-9 ? { x: 0, y: 0, z: 0 } : scale(a, 1 / l); };
const axisAngle = (axis: Vec3, radians: number): Quat => {
    const s = Math.sin(radians / 2);
    return { w: Math.cos(radians / 2), x: axis.x * s, y: axis.y * s, z: axis.z * s };
};

const nameOf = (world: World, e: Entity): string => (world.tryGet(e, Name) as { value?: string } | null)?.value ?? '';
const childrenOf = (world: World, e: Entity): Entity[] => (world.tryGet(e, Children) as { entities?: Entity[] } | null)?.entities ?? [];

/** One joint a hand moves: where it rests, and the turns a pose asks of it, in its own frame. */
interface Joint {
    entity: Entity;
    rest: Quat;
    /** Where it stands from its parent as the rig rests. */
    at: Vec3;
    curlAxis: Vec3;
    /** On a finger's first joint. */
    spreadAxis?: Vec3;
    /** What this wrote last, to tell it from what a clip has written since. */
    written: Quat;
}

/** A finger's joints, knuckle first. Those it has no joint for are left out. */
type Finger = {
    name: FingerName; joints: Joint[]; fan: number;
    /** Where its first joint's parent stands in the hand, and its turn: the hand itself, or a bone in the palm. */
    root: { p: Vec3; r: Quat };
    /** Its tip, from the last joint a pose bends. */
    tip: Vec3;
};

/** Numbers a hand is held by, kept flat so two poses can be eased between: each finger's three joint bends and its lean (radians), then the thumb's reach, how much of it is for the index tip, and its gap. */
const PER_FINGER = 4;
const NUMBERS = FINGERS.length * PER_FINGER + 3;
const REACH = NUMBERS - 3, TO_INDEX = NUMBERS - 2, GAP = NUMBERS - 1;

/** Which way a positive `fan` leans each finger along its spread axis: out from the middle of the hand. */
const FAN_SIDE: Record<FingerName, number> = { thumb: 0, index: 1, middle: 1, ring: -1, pinky: -1 };
const RAD = Math.PI / 180;
const clampTo = (v: number, lo: number, hi: number): number => (v > lo ? (v < hi ? v : hi) : lo);

/** A finger's three joint bends and its lean, in radians: a bend by joint where it says one, else its curl and base. */
function anglesOf(name: FingerName, finger: GripFinger | undefined): [number, number, number, number] {
    const curl = clamp01(finger?.curl ?? 0), base = clamp01(finger?.base ?? finger?.curl ?? 0);
    const bend = (i: number, fallback: number): number => {
        const deg = finger?.bend?.[i];
        return typeof deg === 'number' && Number.isFinite(deg) ? clampTo(deg, -45, 130) * RAD : fallback;
    };
    const fan = finger?.fan;
    return [
        bend(0, base * CLOSED[0]!), bend(1, curl * CLOSED[1]!), bend(2, curl * CLOSED[2]!),
        typeof fan === 'number' && Number.isFinite(fan) ? FAN_SIDE[name] * clampTo(fan, -30, 30) * RAD : clampTo(finger?.spread ?? 0, -1, 1) * FAN[name] * SPREAD,
    ];
}

function numbersOf(pose: GripPoseDef | null, out: Float64Array): void {
    let i = 0;
    for (const name of FINGERS) {
        const angles = name === 'thumb' ? [0, 0, 0, 0] : anglesOf(name, pose?.[name]);
        for (const a of angles) out[i++] = a;
    }
    out[REACH] = clamp01(pose?.thumb?.opposition ?? 0);
    out[TO_INDEX] = pose?.thumb?.to === 'index' ? 1 : 0;
    out[GAP] = Math.max(0, pose?.thumb?.gap ?? 0);
}

const clamp01 = (v: number): number => (v > 0 ? (v < 1 ? v : 1) : 0);

/**
 * A pose with every finger said joint by joint, in degrees: what an editor starts from when a preset is to be changed one joint at a time. It holds
 * the hand exactly as the preset does.
 *
 * @experimental
 */
export function gripPoseByJoint(pose: GripPoseDef): GripPoseDef {
    const deg = (r: number): number => Math.round((r / RAD) * 10) / 10;
    const byJoint = (name: FingerName, finger: GripFinger | undefined): GripFinger => {
        const [a0, a1, a2, lean] = anglesOf(name, finger);
        const side = FAN_SIDE[name];
        return { curl: finger?.curl ?? 0, bend: [deg(a0), deg(a1), deg(a2)], fan: side ? deg(lean / side) : 0 };
    };
    const out: GripPoseDef = {
        thumb: { opposition: clamp01(pose.thumb?.opposition ?? 0), to: pose.thumb?.to === 'index' ? 'index' : 'fingers', gap: Math.max(0, pose.thumb?.gap ?? 0) },
        index: byJoint('index', pose.index), middle: byJoint('middle', pose.middle), ring: byJoint('ring', pose.ring), pinky: byJoint('pinky', pose.pinky),
    };
    if (pose.trigger) out.trigger = byJoint('index', pose.trigger);
    return out;
}

/** A pose read from JSON as an editor writes it, any part it leaves out taken as open. Null for text that is not one. @experimental */
export function gripPoseFromJson(text: string): GripPoseDef | null {
    if (!text) return null;
    let raw: unknown;
    try { raw = JSON.parse(text); } catch { return null; }
    if (!raw || typeof raw !== 'object') return null;
    const o = raw as Record<string, unknown>;
    const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
    const finger = (v: unknown): GripFinger => {
        const f = (v && typeof v === 'object' ? v : {}) as Record<string, unknown>;
        const out: GripFinger = { curl: num(f.curl) ?? 0 };
        if (num(f.base) !== undefined) out.base = num(f.base);
        if (num(f.spread) !== undefined) out.spread = num(f.spread);
        if (Array.isArray(f.bend) && f.bend.length === 3 && f.bend.every((x) => num(x) !== undefined)) out.bend = [f.bend[0], f.bend[1], f.bend[2]] as [number, number, number];
        if (num(f.fan) !== undefined) out.fan = num(f.fan);
        return out;
    };
    const t = (o.thumb && typeof o.thumb === 'object' ? o.thumb : {}) as Record<string, unknown>;
    const pose: GripPoseDef = {
        thumb: { opposition: num(t.opposition) ?? 0, to: t.to === 'index' ? 'index' : 'fingers', gap: num(t.gap) ?? 0 },
        index: finger(o.index), middle: finger(o.middle), ring: finger(o.ring), pinky: finger(o.pinky),
    };
    if (o.trigger) pose.trigger = finger(o.trigger);
    return pose;
}

/** What is known of one hand on one rig. */
interface HandState {
    hand: Entity;
    fingers: Finger[];
    /** Which fingers it could not find, to say so once. */
    missing: FingerName[];
    /** The numbers now, and how much of them is applied now: both eased. */
    current: Float64Array;
    wanted: Float64Array;
    /** The pose's own numbers: what `wanted` is, until fingers closing onto a surface stop short of them. */
    posed: Float64Array;
    /** The fingers whose bones touch a surface, and the surfaces and the hand as this frame has them while the hand closes onto any. */
    touching: FingerName[];
    thumbTouching: boolean;
    surfaces: PlacedSurface[] | null;
    world: { p: Vec3; r: Quat; s: number };
    weight: number;
    /** How fast each number is moving, and the weight after them. */
    speed: Float64Array;
    /** Whether `current` and `weight` have arrived and everything written still stands. */
    settled: boolean;
    pose: string;
    trigger: number;
    /** What the thumb reaches with, where it has a chain long enough to bend. */
    thumb: ThumbReach | null;
    /** The hand's own directions, in its frame. */
    palm: Vec3;
    across: Vec3;
    /** The index finger's length: what a gap is measured in, and about how thick a finger is. */
    reachUnit: number;
    index: Entity[];
    middle: Entity[];
}

/** The thumb as a chain that reaches: where its root stands and how long each bone is, as the rig rests, in the hand's frame. */
interface ThumbReach {
    root: Vec3;
    lengths: [number, number, number];
    /** Each bone's direction as it rests, and each joint's turn from the hand. */
    restDirs: [Vec3, Vec3, Vec3];
    restTurns: [Quat, Quat, Quat];
    /** The turn of the joint the thumb's root hangs from. */
    parentTurn: Quat;
    restTip: Vec3;
}

/** A finger's bones in order, from the hand: those named for it, knuckle first, those in the palm passed through. */
function fingerChain(world: World, hand: Entity, name: FingerName): Entity[] {
    const pattern = NAME_OF[name];
    const search = (at: Entity, depth: number): Entity | null => {
        if (depth > 3) return null;
        for (const child of childrenOf(world, at)) {
            if (pattern.test(nameOf(world, child)) && !INSIDE_PALM.test(nameOf(world, child))) return child;
        }
        for (const child of childrenOf(world, at)) {
            const named = nameOf(world, child);
            // Through the palm's own bones, and not into something held.
            if (INSIDE_PALM.test(named)) { const found = search(child, depth + 1); if (found !== null) return found; }
        }
        return null;
    };
    const first = search(hand, 0);
    if (first === null) return [];
    const chain = [first];
    for (let at = first, guard = 0; guard < 6; guard++) {
        const next = childrenOf(world, at).find((c) => pattern.test(nameOf(world, c))) ?? null;
        if (next === null) break;
        chain.push(next);
        at = next;
    }
    return chain;
}

/** Where a joint stands from the hand, and its turn from it. */
function fromHand(world: World, chain: Entity[]): { at: Vec3[]; turn: Quat[] } {
    let position: Vec3 = { x: 0, y: 0, z: 0 };
    let rotation: Quat = { w: 1, x: 0, y: 0, z: 0 };
    const at: Vec3[] = [], turn: Quat[] = [];
    for (const joint of chain) {
        const local = world.get(joint, Transform) as TransformData;
        position = add(position, q.rotate(rotation, local.position));
        rotation = q.normalize(q.mul(rotation, local.rotation));
        at.push(position);
        turn.push(rotation);
    }
    return { at, turn };
}

/** Which way the palm faces, and toward the thumb across it, in the hand's own frame. Null with too few fingers to tell. */
function palmOf(world: World, side: 'right' | 'left', chains: Partial<Record<FingerName, Entity[]>>): { palm: Vec3; across: Vec3; forward: Vec3 } | null {
    const knuckle = (name: FingerName): Vec3 | null => {
        const chain = chains[name];
        return chain && chain.length ? fromHand(world, chain).at[0]! : null;
    };
    const outer = knuckle('index') ?? knuckle('middle');
    const inner = knuckle('pinky') ?? knuckle('ring') ?? knuckle('middle');
    const middle = knuckle('middle') ?? outer;
    if (!outer || !inner || !middle) return null;
    const across = norm(sub(outer, inner));
    if (Math.hypot(across.x, across.y, across.z) < 0.5) return null;
    // The way the fingers themselves point, and square to the knuckles: a wrist is rarely straight behind its middle finger.
    const long = chains.middle && chains.middle.length > 1 ? chains.middle : chains.index && chains.index.length > 1 ? chains.index : null;
    const placed = long ? fromHand(world, long).at : null;
    const along = placed ? sub(placed[1]!, placed[0]!) : middle;
    const forward = norm(sub(along, scale(across, dot(along, across))));
    // A right hand with its fingers ahead and its thumb to the left has its palm down: which is the cross product, one way round for each hand.
    const palm = norm(scale(cross(forward, across), side === 'right' ? -1 : 1));
    return Math.hypot(palm.x, palm.y, palm.z) < 0.5 ? null : { palm, across, forward };
}

/** The hand's joints, with the turns a pose asks of each. They are worked out from the rig as it stands now, once. */
function buildHand(world: World, hand: Entity, side: 'right' | 'left'): HandState | null {
    const chains: Partial<Record<FingerName, Entity[]>> = {};
    for (const name of FINGERS) chains[name] = fingerChain(world, hand, name);
    const shape = palmOf(world, side, chains);
    if (!shape) return null;
    const { palm, across } = shape;
    const fingers: Finger[] = [];
    const missing: FingerName[] = [];
    for (const name of FINGERS) {
        const chain = chains[name]!;
        if (chain.length === 0) { missing.push(name); continue; }
        const { at, turn } = fromHand(world, chain);
        // Its first joint to its second is the way it points; a finger of one joint points as the joint does from the hand.
        const pointing = norm(chain.length > 1 ? sub(at[1]!, at[0]!) : at[0]!);
        const bend = norm(cross(pointing, palm));
        // The last bone of a chain that goes on past three is the tip's end, which nothing bends.
        const moved = chain.slice(0, 3);
        const joints: Joint[] = moved.map((entity, i) => {
            const toJoint = q.conjugate(turn[i]!);
            const rest = q.normalize((world.get(entity, Transform) as TransformData).rotation);
            const at0 = (world.get(entity, Transform) as TransformData).position;
            const joint: Joint = { entity, rest: { ...rest }, at: { x: at0.x, y: at0.y, z: at0.z }, curlAxis: norm(q.rotate(toJoint, bend)), written: { ...rest } };
            if (i === 0) {
                joint.spreadAxis = norm(q.rotate(toJoint, palm));
                // Toward the index finger for a positive spread.
                if (dot(cross(palm, pointing), across) < 0) joint.spreadAxis = scale(joint.spreadAxis, -1);
            }
            return joint;
        });
        fingers.push({ name, joints, fan: FAN[name], root: rootOf(world, hand, chain[0]!), tip: tipOf(world, chain) });
    }
    const index = chains.index ?? [], middle = chains.middle ?? [];
    const lengthOf = (chain: Entity[]): number => {
        const at = chain.length ? fromHand(world, chain).at : [];
        let n = 0;
        for (let i = 1; i < at.length; i++) n += Math.hypot(at[i]!.x - at[i - 1]!.x, at[i]!.y - at[i - 1]!.y, at[i]!.z - at[i - 1]!.z);
        return n;
    };
    const reachUnit = lengthOf(index) || lengthOf(middle) || 0;
    return {
        hand, fingers, missing, current: new Float64Array(NUMBERS), wanted: new Float64Array(NUMBERS), posed: new Float64Array(NUMBERS), touching: [], thumbTouching: false, surfaces: null,
        world: { p: { x: 0, y: 0, z: 0 }, r: { w: 1, x: 0, y: 0, z: 0 }, s: 1 }, weight: 0, speed: new Float64Array(NUMBERS + 1), settled: false, pose: '', trigger: 0,
        thumb: thumbReach(world, chains.thumb ?? []), palm, across, reachUnit, index, middle,
    };
}

/** Where a finger's first joint's parent stands in the hand as the rig rests, and its turn: through any bone in the palm between. */
function rootOf(world: World, hand: Entity, first: Entity): { p: Vec3; r: Quat } {
    const up: Entity[] = [];
    for (let at = (world.tryGet(first, Parent) as { entity?: Entity } | null)?.entity, guard = 0; at !== undefined && at !== hand && guard < 8; guard++) {
        up.unshift(at);
        at = (world.tryGet(at, Parent) as { entity?: Entity } | null)?.entity;
    }
    let p: Vec3 = { x: 0, y: 0, z: 0 }, r: Quat = { w: 1, x: 0, y: 0, z: 0 };
    for (const e of up) {
        const local = world.get(e, Transform) as TransformData;
        p = add(p, q.rotate(r, local.position));
        r = q.normalize(q.mul(r, local.rotation));
    }
    return { p, r };
}

/** A finger's tip from its last bent joint: the next bone where the chain has one, else most of the bone before, as fingers end. */
function tipOf(world: World, chain: Entity[]): Vec3 {
    if (chain.length > 3) return { ...(world.get(chain[3]!, Transform) as TransformData).position };
    const last = chain[chain.length - 1]!;
    const local = world.get(last, Transform) as TransformData;
    // The bone before, seen from the last joint: its own place from its parent, turned into its frame.
    return scale(q.rotate(q.conjugate(q.normalize(local.rotation)), local.position), 0.8);
}

/** The thumb's chain as it rests: null with fewer than three bones, since two cannot both reach and curl. */
function thumbReach(world: World, chain: Entity[]): ThumbReach | null {
    if (chain.length < 3) return null;
    const { at, turn } = fromHand(world, chain);
    const segment = (i: number): Vec3 => sub(at[i + 1]!, at[i]!);
    const third = chain.length > 3 ? segment(2) : scale(segment(1), 0.85);
    const lengths: [number, number, number] = [Math.hypot(...xyz(segment(0))), Math.hypot(...xyz(segment(1))), Math.hypot(...xyz(third))];
    if (lengths.some((l) => !(l > 1e-6))) return null;
    const local0 = (world.get(chain[0]!, Transform) as TransformData).rotation;
    return {
        root: at[0]!, lengths, restDirs: [norm(segment(0)), norm(segment(1)), norm(third)], restTurns: [turn[0]!, turn[1]!, turn[2]!],
        parentTurn: q.normalize(q.mul(turn[0]!, q.conjugate(local0))), restTip: add(at[2]!, third),
    };
}

const xyz = (v: Vec3): [number, number, number] => [v.x, v.y, v.z];

/** Where a bent chain's tip is, when its second and third joints each turn by `bend`, measured along its first bone and square to it. */
function chainTip(lengths: readonly number[], bend: number): [number, number] {
    const [a, b, c] = lengths as [number, number, number];
    return [a + b * Math.cos(bend) + c * Math.cos(2 * bend), b * Math.sin(bend) + c * Math.sin(2 * bend)];
}

/**
 * The thumb's joints turned so its tip lands on `goal`, its bones curling toward `inward`: the bend found by halving, the plane by where the goal is.
 * Answers each joint's turn from the hand; `points`, where given, gets where its root, its joints and its tip then stand in the hand.
 */
function reachThumb(reach: ThumbReach, goal: Vec3, inward: Vec3, points?: Vec3[]): [Quat, Quat, Quat] {
    const toGoal = sub(goal, reach.root);
    const total = reach.lengths[0] + reach.lengths[1] + reach.lengths[2];
    const want = Math.min(Math.max(Math.hypot(...xyz(toGoal)), total * 0.35), total - 1e-6);
    let lo = 0, hi = 1.7;
    for (let i = 0; i < 24; i++) {
        const mid = (lo + hi) / 2;
        const [x, y] = chainTip(reach.lengths, mid);
        if (Math.hypot(x, y) > want) lo = mid; else hi = mid;
    }
    const bend = (lo + hi) / 2;
    const [tx, ty] = chainTip(reach.lengths, bend);
    const lean = Math.atan2(ty, tx);
    const u = norm(toGoal);
    const off = sub(inward, scale(u, dot(inward, u)));
    const v = Math.hypot(...xyz(off)) > 1e-6 ? norm(off) : norm(cross(u, { x: 0, y: 0, z: 1 }));
    const along = (angle: number): Vec3 => add(scale(u, Math.cos(angle)), scale(v, Math.sin(angle)));
    const dirs = [along(-lean), along(bend - lean), along(2 * bend - lean)];
    if (points) {
        let at = reach.root;
        points.push(at);
        for (let i = 0; i < 3; i++) { at = add(at, scale(dirs[i]!, reach.lengths[i]!)); points.push(at); }
    }
    // Each bone turned the least way from where its parent left it: no twist added along it.
    const turns: Quat[] = [];
    let parentNow = reach.parentTurn, parentRest = reach.parentTurn;
    for (let i = 0; i < 3; i++) {
        const carried = q.normalize(q.mul(q.mul(parentNow, q.conjugate(parentRest)), reach.restTurns[i]!));
        const facing = q.rotate(q.mul(parentNow, q.conjugate(parentRest)), reach.restDirs[i]!);
        const turned = q.normalize(q.mul(q.rotationTo(facing, dirs[i]!), carried));
        turns.push(turned);
        parentRest = reach.restTurns[i]!;
        parentNow = turned;
    }
    return turns as [Quat, Quat, Quat];
}

const NAMED_HAND = /hand|wrist/i;
const NOT_A_HAND = /thumb|index|middle|ring|pinky|pinkie|little|finger|metacarpal|palm/i;
const IS_RIGHT = /right|(^|[^a-z])r($|[^a-z])/i;
const IS_LEFT = /left|(^|[^a-z])l($|[^a-z])/i;

/**
 * The palm of a hand joint, in the hand's own frame: its centre (halfway to the middle knuckle), and the turn whose +Z is the way the fingers point
 * and whose +Y is the way the palm faces. Null for a hand whose fingers say neither. @internal
 */
export function palmFrameOf(world: World, hand: Entity, side: 'right' | 'left'): { center: Vec3; turn: Quat } | null {
    const chains: Partial<Record<FingerName, Entity[]>> = {};
    for (const name of FINGERS) chains[name] = fingerChain(world, hand, name);
    const shape = palmOf(world, side, chains);
    const knuckle = (chains.middle?.length ? chains.middle : chains.index?.length ? chains.index : chains.ring) ?? null;
    if (!shape || !knuckle?.length) return null;
    const z = shape.forward, y = norm(sub(shape.palm, scale(z, dot(shape.palm, z))));
    const x = cross(y, z);
    return { center: scale(fromHand(world, [knuckle[0]!]).at[0]!, 0.5), turn: basisTurn(x, y, z) };
}

/** The turn that takes +X, +Y, +Z to three square unit vectors. */
function basisTurn(x: Vec3, y: Vec3, z: Vec3): Quat {
    const trace = x.x + y.y + z.z;
    let w: number, qx: number, qy: number, qz: number;
    if (trace > 0) {
        const s = Math.sqrt(trace + 1) * 2;
        w = s / 4; qx = (y.z - z.y) / s; qy = (z.x - x.z) / s; qz = (x.y - y.x) / s;
    } else if (x.x > y.y && x.x > z.z) {
        const s = Math.sqrt(1 + x.x - y.y - z.z) * 2;
        w = (y.z - z.y) / s; qx = s / 4; qy = (y.x + x.y) / s; qz = (z.x + x.z) / s;
    } else if (y.y > z.z) {
        const s = Math.sqrt(1 + y.y - x.x - z.z) * 2;
        w = (z.x - x.z) / s; qx = (y.x + x.y) / s; qy = s / 4; qz = (z.y + y.z) / s;
    } else {
        const s = Math.sqrt(1 + z.z - x.x - y.y) * 2;
        w = (x.y - y.x) / s; qx = (z.x + x.z) / s; qy = (z.y + y.z) / s; qz = s / 4;
    }
    return q.normalize({ w, x: qx, y: qy, z: qz });
}

/** The joint named for that hand under `root`, nearest first. @internal */
export function findHand(world: World, root: Entity, side: 'right' | 'left'): Entity | null {
    const wanted = side === 'right' ? IS_RIGHT : IS_LEFT;
    const queue: Entity[] = [root];
    for (let i = 0; i < queue.length && i < 512; i++) {
        const at = queue[i]!;
        const name = nameOf(world, at);
        if (at !== root && NAMED_HAND.test(name) && !NOT_A_HAND.test(name) && wanted.test(name) && fingerChain(world, at, 'middle').length + fingerChain(world, at, 'index').length > 0) return at;
        queue.push(...childrenOf(world, at));
    }
    return null;
}

/** What one rig's hands are doing. */
interface RigState { right: HandState | null; left: HandState | null; rightHand: string; leftHand: string; tried: { right: boolean; left: boolean }; byComponent: boolean; blend: number }

const SAME = 1e-6;
const same = (a: Quat, b: Quat): boolean => Math.abs(a.w - b.w) < SAME && Math.abs(a.x - b.x) < SAME && Math.abs(a.y - b.y) < SAME && Math.abs(a.z - b.z) < SAME;

/**
 * A number moved toward where it is wanted, critically damped: it starts from still and comes to rest without passing it. Going a fixed share of the
 * gap each frame would be at its fastest on the first, and a finger with far to go visibly jumps.
 */
function ease(value: number, wanted: number, state: HandState, slot: number, blend: number, dt: number): number {
    if (blend <= 0) { state.speed[slot] = 0; return wanted; }
    const omega = 6 / blend;
    const gap = value - wanted;
    const carry = (state.speed[slot]! + omega * gap) * dt;
    const fade = Math.exp(-omega * dt);
    const speed = (state.speed[slot]! - omega * carry) * fade;
    const next = wanted + (gap + carry) * fade;
    if (Math.abs(next - wanted) < 1e-3 && Math.abs(speed) < 1e-2) { state.speed[slot] = 0; return wanted; }
    state.speed[slot] = speed;
    return next;
}

/** A finger's joints and tip in the world, its joints bent by `bends` and its first leaning by `lean`, from the hand as this frame has it. */
function fingerInWorld(state: HandState, finger: Finger, bends: readonly number[], lean: number): Vec3[] {
    let p = finger.root.p, r = finger.root.r;
    const out: Vec3[] = [];
    const w = state.world;
    const toWorld = (v: Vec3): Vec3 => add(w.p, q.rotate(w.r, scale(v, w.s)));
    for (let i = 0; i < finger.joints.length; i++) {
        const joint = finger.joints[i]!;
        p = add(p, q.rotate(r, joint.at));
        let turn = axisAngle(joint.curlAxis, bends[i] ?? 0);
        if (joint.spreadAxis && lean !== 0) turn = q.mul(axisAngle(joint.spreadAxis, lean), turn);
        r = q.normalize(q.mul(r, q.mul(joint.rest, turn)));
        out.push(toWorld(p));
    }
    out.push(toWorld(add(p, q.rotate(r, finger.tip))));
    return out;
}

/** A finger's bone from the line through it to its skin: a share of the index finger's length, as fingers are. */
const THICKNESS = 0.08;

/**
 * Each finger closed from open toward the pose, joint by joint, until it meets a surface: what `wanted` asks of its bends then. Answers whether
 * that changed anything. The thumb is moved out of the surfaces where it reaches (`thumbTurns`).
 */
function closeOnto(world: World, state: HandState, surfaces: PlacedSurface[]): boolean {
    const t = world.get(state.hand, Transform) as TransformData;
    state.world = { p: { ...t.worldPosition }, r: q.normalize(t.worldRotation), s: Math.abs(t.worldScale.x) || 1 };
    state.surfaces = surfaces;
    const skin = state.reachUnit * THICKNESS * state.world.s;
    let changed = false;
    const touching: FingerName[] = [];
    for (const finger of state.fingers) {
        if (finger.name === 'thumb') continue;
        const at = FINGERS.indexOf(finger.name) * PER_FINGER;
        const n = finger.joints.length;
        const limit = Array.from({ length: n }, (_, i) => state.posed[at + i]!);
        const lean = state.posed[at + 3]!;
        const start = limit.map((b) => Math.min(0, b));
        // A bone already within its thickness of a surface as the finger opens (a handle pressed into the palm) may go on, but no deeper than it started.
        const open = fingerInWorld(state, finger, start, lean);
        const reach = Array.from({ length: n }, (_, k) => Math.min(skin, boneDistance(surfaces, open[k]!, open[k + 1]!) - 1e-6));
        const { bends, touched } = closeFinger(start, limit, (b, from) => {
            const points = fingerInWorld(state, finger, b, lean);
            for (let k = from; k < n; k++) if (boneDistance(surfaces, points[k]!, points[k + 1]!) <= reach[k]!) return k;
            return -1;
        });
        if (touched) touching.push(finger.name);
        for (let i = 0; i < n; i++) {
            if (Math.abs(state.wanted[at + i]! - bends[i]!) > 1e-5) { state.wanted[at + i] = bends[i]!; changed = true; }
        }
    }
    state.touching = touching;
    return changed;
}

/** Whether every joint still stands as this last wrote it: something else (a clip, an editor sampling one) may have turned them since. */
function standsAsWritten(world: World, state: HandState): boolean {
    for (const finger of state.fingers) {
        for (const joint of finger.joints) {
            if (!world.valid(joint.entity) || !same((world.get(joint.entity, Transform) as TransformData).rotation, joint.written)) return false;
        }
    }
    return true;
}

/**
 * Holds one hand a frame: eases its numbers on, and turns each joint to them over what is there. `poseName` tells one pose from the next; `def` is it.
 * `surfaces`, where there are any, are what the fingers close onto.
 */
function holdHand(world: World, state: HandState, poseName: string, def: GripPoseDef | null, weight: number, trigger: number, blend: number, dt: number, moved: boolean, surfaces: PlacedSurface[] | null): void {
    const pose = poseName ? def : null;
    if (poseName !== state.pose) {
        if (poseName && !pose) log.warn('animation', `there is no grip pose called "${poseName}": the hand is left alone`);
        state.pose = poseName;
        // A new pose eases on from where the hand is; a hand let go keeps its numbers and fades by its weight.
        if (pose) { numbersOf(pose, state.posed); state.wanted.set(state.posed); }
        state.settled = false;
    }
    if (pose && surfaces && surfaces.length) {
        if (closeOnto(world, state, surfaces)) state.settled = false;
    } else if (state.surfaces) {
        // Nothing to close onto any more: back to the pose itself.
        state.surfaces = null;
        state.touching = [];
        if (pose) state.wanted.set(state.posed);
        state.settled = false;
    }
    const wantedWeight = pose ? clamp01(weight) : 0;
    const press = pose?.trigger ? clamp01(trigger) : 0;
    if (press !== state.trigger) { state.trigger = press; state.settled = false; }
    if (wantedWeight !== state.weight) state.settled = false;
    if (state.settled && !moved && standsAsWritten(world, state)) return;

    let arrived = true;
    for (let i = 0; i < NUMBERS; i++) {
        const next = ease(state.current[i]!, state.wanted[i]!, state, i, blend, dt);
        state.current[i] = next;
        if (next !== state.wanted[i]) arrived = false;
    }
    state.weight = ease(state.weight, wantedWeight, state, NUMBERS, blend, dt);
    if (state.weight !== wantedWeight) arrived = false;

    // The thumb last: what it reaches for is where the other fingers have just been put.
    const ordered = [...state.fingers.filter((x) => x.name !== 'thumb'), ...state.fingers.filter((x) => x.name === 'thumb')];
    for (const finger of ordered) {
        const reached = finger.name === 'thumb' && state.thumb ? thumbTurns(world, state) : null;
        const at = FINGERS.indexOf(finger.name) * PER_FINGER;
        const bends = [state.current[at]!, state.current[at + 1]!, state.current[at + 2]!];
        const lean = state.current[at + 3]!;
        if (finger.name === 'index' && press > 0 && pose?.trigger) {
            const pressed = anglesOf('index', pose.trigger);
            for (let i = 0; i < 3; i++) bends[i] = bends[i]! + (pressed[i]! - bends[i]!) * press;
        }
        for (let i = 0; i < finger.joints.length; i++) {
            const joint = finger.joints[i]!;
            let target: Quat;
            if (reached) {
                // From the joint's turn from the hand to its own: its parent is the joint before, or for the first what the thumb hangs from.
                const parent = i === 0 ? state.thumb!.parentTurn : reached[i - 1]!;
                target = q.normalize(q.mul(q.conjugate(parent), reached[i]!));
            } else {
                let turn = axisAngle(joint.curlAxis, bends[i]!);
                if (joint.spreadAxis && lean !== 0) turn = q.mul(axisAngle(joint.spreadAxis, lean), turn);
                target = q.normalize(q.mul(joint.rest, turn));
            }
            const local = world.get(joint.entity, Transform) as TransformData;
            // Moved since this wrote it, a clip is speaking and the pose goes over that; otherwise over how the rig rests.
            const from = same(local.rotation, joint.written) ? joint.rest : local.rotation;
            const out = { w: from.w, x: from.x, y: from.y, z: from.z };
            if (state.weight >= 1) { out.w = target.w; out.x = target.x; out.y = target.y; out.z = target.z; }
            else leanQuat(out, target, state.weight);
            const written = q.normalize(out);
            world.update(joint.entity, Transform, (t: TransformData) => { t.rotation = { w: written.w, x: written.x, y: written.y, z: written.z }; });
            joint.written = { ...((world.get(joint.entity, Transform) as TransformData).rotation) };
        }
    }
    state.settled = arrived;
}

/**
 * Where the thumb goes this frame, as each joint's turn from the hand: from where it rests toward the middle of the middle finger (or the index tip) as
 * they now stand, on the palm's side of them by a finger's thickness and the pose's gap. Null with no reach asked, which leaves it as it rests.
 */
function thumbTurns(world: World, state: HandState): [Quat, Quat, Quat] | null {
    const reach = state.thumb!;
    const amount = state.current[REACH]!;
    if (amount <= 0) return null;
    const middleOf = (chain: Entity[]): Vec3 | null => {
        if (chain.length < 3) return null;
        const at = fromHand(world, chain).at;
        return scale(add(at[1]!, at[2]!), 0.5);
    };
    const tipOf = (chain: Entity[]): Vec3 | null => (chain.length ? fromHand(world, chain).at[chain.length - 1]! : null);
    // The middle finger's, not the index's: an index finger on a trigger would move the thumb with it.
    const fingers = middleOf(state.middle) ?? middleOf(state.index);
    const index = tipOf(state.index) ?? fingers;
    if (!fingers || !index) return null;
    const toIndex = state.current[TO_INDEX]!;
    const on = add(scale(fingers, 1 - toIndex), scale(index, toIndex));
    const thickness = state.reachUnit * 0.16;
    const contact = add(on, scale(state.palm, thickness + state.current[GAP]! * state.reachUnit));
    const inward = norm(add(scale(state.across, -0.8), scale(state.palm, 0.6)));
    const goalAt = (a: number): Vec3 => add(scale(reach.restTip, 1 - a), scale(contact, a));
    state.thumbTouching = false;
    if (!state.surfaces) return reachThumb(reach, goalAt(amount), inward);
    // Over a surface, the thumb comes in along the same way and stops where a bone of it meets one: a goal on the far side of a handle, past
    // where the thumb can reach, would otherwise straighten it through the handle.
    const w = state.world, surfaces = state.surfaces;
    const skin = state.reachUnit * THICKNESS * w.s;
    const bonesAt = (a: number): Vec3[] => {
        const points: Vec3[] = [];
        reachThumb(reach, goalAt(a), inward, points);
        return points.map((p) => add(w.p, q.rotate(w.r, scale(p, w.s))));
    };
    const open = bonesAt(0);
    const limit = [0, 1, 2].map((k) => Math.min(skin, boneDistance(surfaces, open[k]!, open[k + 1]!) - 1e-6));
    const { bends, touched } = closeFinger([0], [amount], (a, from) => {
        if (from > 0) return -1;
        const points = bonesAt(a[0]!);
        return [0, 1, 2].some((k) => boneDistance(surfaces, points[k]!, points[k + 1]!) <= limit[k]!) ? 0 : -1;
    });
    state.thumbTouching = touched;
    return reachThumb(reach, goalAt(bends[0]!), inward);
}

function letGo(world: World, state: HandState | null): void {
    if (!state) return;
    for (const finger of state.fingers) {
        for (const joint of finger.joints) {
            if (world.valid(joint.entity) && world.has(joint.entity, Transform)) {
                world.update(joint.entity, Transform, (t: TransformData) => { t.rotation = { w: joint.rest.w, x: joint.rest.x, y: joint.rest.y, z: joint.rest.z }; });
            }
        }
    }
}

/**
 * A hand pose something else asks of a rig each frame: a holder handing the fingers its grip. Over the rig's own GripPose for that hand, if it has
 * one. `key` tells one pose from the next. @internal
 */
export interface HeldHand {
    key: string; pose: GripPoseDef | null; weight: number;
    /** An object whose grip surfaces, on it and under it, the fingers close onto, the pose saying how far they may. */
    wrap?: Entity;
}
/** @internal */
export interface HeldHands { right?: HeldHand; left?: HeldHand; blendSeconds: number; rightHand: string; leftHand: string }

const asked = new WeakMap<App, Map<Entity, HeldHands>>();

/** Asks for a rig's hands this frame. Read by the next run of the grip-pose system, then forgotten. @internal */
export function askHeldHands(app: App, rig: Entity, hands: HeldHands): void {
    let map = asked.get(app);
    if (!map) { map = new Map(); asked.set(app, map); }
    map.set(rig, hands);
}

/** Every hand this has posed put back as the rig rests, and forgotten: an editor leaving its preview. @internal */
export function releaseGripPoses(app: App): void {
    const known = rigs.get(app);
    if (known) {
        for (const state of known.values()) { letGo(app.world, state.right); letGo(app.world, state.left); }
        known.clear();
    }
    asked.get(app)?.clear();
}

/** What a rig's hand was found to have. @experimental */
export interface GripHandStatus {
    /** The joint it took for the hand, or null where none could be found. */
    hand: Entity | null;
    /** How many joints a pose moves on it. */
    joints: number;
    /** The fingers it has no bones for: a pose simply does without them. */
    missing: string[];
    /** The pose it is in. */
    pose: string;
    /** How much of it applies now. */
    weight: number;
    /** The fingers whose bones touch a surface they were closed onto. */
    touching: string[];
}

/** One joint a pose bends, and the axis it bends about in its own frame: a positive bend turns it that way. @experimental */
export interface GripJoint {
    finger: string;
    /** 0 the knuckle, 1 the middle joint, 2 the last. */
    joint: number;
    entity: Entity;
    axis: { x: number; y: number; z: number };
    /** The bone it turns, to the next joint or the fingertip, in its own frame: where a handle shows which way a bend moves it. */
    bone: { x: number; y: number; z: number };
}

/** The joints each hand of a rig bends, once the grip-pose system has seen it: what an editor puts a handle on. @experimental */
export function gripHandJoints(app: App, rig: Entity): { right: GripJoint[]; left: GripJoint[] } | null {
    const state = rigs.get(app)?.get(rig);
    if (!state) return null;
    const of = (h: HandState | null): GripJoint[] => (h ? h.fingers.filter((f) => f.name !== 'thumb').flatMap((f) => f.joints.map((j, i) => ({
        finger: f.name, joint: i, entity: j.entity, axis: { ...j.curlAxis }, bone: { ...(f.joints[i + 1]?.at ?? f.tip) },
    }))) : []);
    return { right: of(state.right), left: of(state.left) };
}

const rigs = new WeakMap<App, Map<Entity, RigState>>();

/** What each hand of a rig with a `GripPose` was found to have, once the system has seen it. @experimental */
export function gripPoseStatus(app: App, rig: Entity): { right: GripHandStatus; left: GripHandStatus } | null {
    const state = rigs.get(app)?.get(rig);
    if (!state) return null;
    const of = (h: HandState | null): GripHandStatus => ({
        hand: h?.hand ?? null, joints: h ? h.fingers.reduce((n, finger) => n + finger.joints.length, 0) : 0, missing: h ? [...h.missing] : [...FINGERS], pose: h?.pose ?? '', weight: h?.weight ?? 0,
        touching: h ? [...(h.thumbTouching && h.surfaces ? ['thumb'] : []), ...h.touching] : [],
    });
    return { right: of(state.right), left: of(state.left) };
}

/** Holds every rig's hands. Runs after the animator, since what a clip says of the fingers is what a pose goes over. */
export function installGripPose(app: App): void {
    const known = new Map<Entity, RigState>();
    rigs.set(app, known);
    // By name: what moves the bones is the animator's or the timeline's, which this does not need to carry.
    const hasClipOn = (world: World, rig: Entity): boolean => ['Animator', 'TimelinePlayer'].some((name) => { const def = getComponent(name); return !!def && world.has(rig, def); });
    // system-access: the hand's joints are found by walking the rig, so which entities it writes is known only then, and only their Transforms.
    app.addSystemToSchedule(Schedule.Update, defineSystem([Res(Time), GetWorld()], (time: TimeData, world: World) => {
        const wanted = asked.get(app) ?? new Map<Entity, HeldHands>();
        asked.set(app, wanted);
        const comps = new Set(world.getEntitiesWithComponents([GripPose]));
        for (const [rig, state] of known) {
            if (!world.valid(rig)) { known.delete(rig); continue; }
            if (comps.has(rig) || wanted.has(rig)) continue;
            // A component taken off lets go at once, as it always has; hands a holder stopped asking for fade out below.
            if (state.byComponent) { letGo(world, state.right); letGo(world, state.left); known.delete(rig); }
        }
        const rigsNow = new Set<Entity>([...comps, ...wanted.keys(), ...known.keys()]);
        // Closing onto a surface measures where the hand and the object are this frame, after the hold has moved both.
        const placed = new Map<Entity, PlacedSurface[]>();
        let composed = false;
        const surfacesOf = (object: Entity | undefined): PlacedSurface[] | null => {
            if (object === undefined || !world.valid(object)) return null;
            if (!composed) { world.ensureTransformsComposed(); composed = true; }
            let found = placed.get(object);
            if (!found) { found = surfacesUnder(world, object); placed.set(object, found); }
            return found;
        };
        for (const rig of rigsNow) {
            if (!world.valid(rig)) continue;
            const data = comps.has(rig) ? world.get(rig, GripPose) as GripPoseData : null;
            const ask = wanted.get(rig);
            const rightHandPath = data?.rightHand || ask?.rightHand || '', leftHandPath = data?.leftHand || ask?.leftHand || '';
            const handOf = (side: 'right' | 'left'): { key: string; def: GripPoseDef | null; weight: number; trigger: number; wrap?: Entity } => {
                const held = ask?.[side];
                if (held) return { key: held.key, def: held.pose, weight: held.weight, trigger: data ? (side === 'right' ? data.rightTrigger : data.leftTrigger) : 0, wrap: held.wrap };
                if (data) {
                    const name = side === 'right' ? data.rightPose : data.leftPose;
                    return { key: name, def: poses.get(name) ?? null, weight: side === 'right' ? data.rightWeight : data.leftWeight, trigger: side === 'right' ? data.rightTrigger : data.leftTrigger };
                }
                return { key: '', def: null, weight: 0, trigger: 0 };
            };
            const hands = { right: handOf('right'), left: handOf('left') };
            if (!hands.right.key && !hands.left.key && !known.has(rig)) continue;
            let state = known.get(rig);
            if (!state || state.rightHand !== rightHandPath || state.leftHand !== leftHandPath) {
                if (state) { letGo(world, state.right); letGo(world, state.left); }
                state = { right: null, left: null, rightHand: rightHandPath, leftHand: leftHandPath, tried: { right: false, left: false }, byComponent: !!data, blend: 0.15 };
                known.set(rig, state);
            }
            state.byComponent = !!data;
            // Asked for, the holder's; on the rig's own, its; fading out once neither speaks, the last there was.
            const blend = ask ? ask.blendSeconds : data ? data.blendSeconds : state.blend;
            state.blend = blend;
            const moved = hasClipOn(world, rig);
            for (const side of ['right', 'left'] as const) {
                const poseName = hands[side].key;
                if (!state[side] && poseName && !state.tried[side]) {
                    state.tried[side] = true;
                    const path = side === 'right' ? rightHandPath : leftHandPath;
                    const hand = path ? resolveChildEntity(world, rig, path) : findHand(world, rig, side);
                    state[side] = hand === null ? null : buildHand(world, hand, side);
                    if (!state[side]) log.warn('animation', `a GripPose found no ${side} hand with fingers on "${nameOf(world, rig)}"${path ? ` at "${path}"` : ''}: name its joint in ${side}Hand`);
                    else if (state[side]!.missing.length) log.warn('animation', `the ${side} hand of "${nameOf(world, rig)}" has no bones for its ${state[side]!.missing.join(', ')}: a pose does without them`);
                }
                const hand = state[side];
                if (hand) holdHand(world, hand, poseName, hands[side].def, hands[side].weight, hands[side].trigger, blend, time.delta, moved, surfacesOf(hands[side].wrap));
            }
            // Hands no one asks for any more, faded all the way out: nothing is left to hold.
            if (!data && !ask && (!state.right || state.right.weight === 0) && (!state.left || state.left.weight === 0)) known.delete(rig);
        }
        wanted.clear();
    }, { name: 'GripPoseSystem' }), { runAfter: [SystemLabel.Animator], runIf: fxPreviewOrPlayMode });
}