@adatechnology/game-contracts 0.4.0 → 0.6.0

package/README.md

@@ -118,7 +118,8 @@ metrics: () => [{ id: 'particles', name: 'Particles', max: 400, read: () => fx.p
 ```
 
 Tool events are named after a tool's cycle, not a firearm: `mode`, `fault`, `clear` (start / end) and `safety`, and `shot` carries `rounds`
-(cartridges spent) next to `shots` (projectiles) and the `mode`. `HostTool` may report `mode`, `fault`, `safety` and `heat` (0..1).
+(cartridges spent) next to `shots` (projectiles, always 1 or more) and the `mode`; a dud round is its own `misfire` event, not a `shot` of zero. `HostTool` may report `mode`, `fault`, `safety` and `heat` (0..1).
+`host.configureTool(settings)` takes a `Record<string, string>` keyed by the id of the module's own control; the test room applies `condition` and `ammo_quality` and ignores other ids.
 
 ## API
 

package/dist/index.d.ts

@@ -37,6 +37,16 @@ type PartShape = {
     radius: number;
 };
 type FluidKind = 'water' | 'fuel' | 'oil' | 'gas' | 'sap' | 'acid' | 'blood' | string;
+/** Seconds from a trigger to the blast: fixed, or `[min, max]` drawn from the world seed. */
+type ChainDelay = number | readonly [number, number];
+/** How an explosive part is set off by what happens around it. See `PartSpec.explodes`. */
+interface ExplosionChain {
+    shot?: ChainDelay;
+    fire?: ChainDelay;
+    explosion?: ChainDelay;
+    /** Fraction of the part's hit points a shot must have taken off before it sets the part off (default 0: any hit). */
+    shotDamageFraction?: number;
+}
 interface PartSpec {
     /** Unique inside the object. */
     id: string;
@@ -67,6 +77,12 @@ interface PartSpec {
         energy: number;
         radius: number;
         atC?: number;
+        /**
+         * Chain reaction: what sets the part off before it is destroyed and the seconds from that to the blast (a number, or `[min, max]` drawn
+         * from the world seed). `shot`: a bullet hit; `fire`: the part gets to `atC` (default 300 °C) or burns; `explosion`: a blast reaches it.
+         * Each part goes off once. Without `chain`, it explodes only when destroyed (or at `atC`).
+         */
+        chain?: ExplosionChain;
     };
     /** Fixed to the world (a wall-mounted cabinet, a tree trunk in the ground). Groups that keep an anchored part stay in place. */
     anchored?: boolean;
@@ -360,6 +376,14 @@ type DestructionEvent = (EventBase & {
     energy: number;
     radius: number;
 })
+/** An explosive part was set off by a bullet, fire or a nearby blast and will explode `delay` seconds from now (`explodes.chain`). */
+ | (EventBase & {
+    type: 'primed';
+    part: string;
+    point: Vec3;
+    trigger: 'shot' | 'fire' | 'explosion';
+    delay: number;
+})
 /** A structural part is overloaded (`stress` > 1); throttled to once per 0.5 s per part. Brittle parts also `crack` at stress > 0.8. */
  | (EventBase & {
     type: 'stress';
@@ -532,6 +556,53 @@ type Use = {
         radius: number;
         seconds: number;
     };
+    /** Explosive id (`m67`, `molotov`, `pg7v`...): the host looks the numbers up in the arsenal. Absent on a plain thrown object. */
+    explosive?: string;
+    /** What sets it off: `timer` after `fuse` seconds, `impact` on the first hit once armed. */
+    trigger?: 'timer' | 'impact';
+    /** Metres the projectile must fly before an impact sets it off; closer, it hits without exploding (rocket launchers). */
+    armDistance?: number;
+    /** Radius in metres of the wounding area (`radius` is the lethal one). */
+    injuryRadius?: number;
+    /** Seconds the blast stuns whoever is inside the injury radius (flashbang). */
+    stunSeconds?: number;
+    /** Seconds the thrower held it after pulling the pin: `fuse` is what was left of the full fuse when it left the hand. */
+    cooked?: number;
+    /** Went off in the thrower's hand (held past the fuse): no velocity, `fuse` is 0 and the blast is at `origin`. */
+    inHand?: boolean;
+}
+/** An explosive set down where the trigger is pulled (mine, C4, charge): it waits for its trigger instead of flying. */
+ | {
+    kind: 'place';
+    explosive: string;
+    /** `wire`: something trips it; `remote`: the player fires it; `timer`: after `fuse` seconds. */
+    triggers: readonly ('timer' | 'wire' | 'remote')[];
+    energy: number;
+    /** Lethal radius in metres. */
+    radius: number;
+    injuryRadius: number;
+    /** Cone the blast goes through, in front of `direction` (mine); absent for a blast in every direction. */
+    cone?: {
+        halfAngleDeg: number;
+        length: number;
+    };
+    /** The wire a `wire` charge stretches from where it is set down: metres out, degrees from its facing (counter-clockwise from above) and metres above it. */
+    tripwire?: {
+        length: number;
+        angleDeg: number;
+        height: number;
+    };
+    fuse?: number;
+    origin: Vec3;
+    direction: Vec3;
+}
+/** The blast behind a rocket launcher: dangerous inside `radius` metres, in the cone around `direction` (pointing away from the target). */
+ | {
+    kind: 'backblast';
+    radius: number;
+    halfAngleDeg: number;
+    origin: Vec3;
+    direction: Vec3;
 } | {
     kind: 'tool';
     tool: string;
@@ -817,9 +888,12 @@ interface ModuleArea {
  * What the player did with the tool in hand, as the host reports it. Hosts emit what they support; modules ignore what they do not need. The
  * names are of a tool's cycle, not of a firearm: a nail gun, a chainsaw or a hose has modes, faults and a safety too.
  */
-type HostEvent = {
+type HostEvent = 
+/** The tool is put in hand; `duration` is the seconds the rule takes to ready it (absent: no draw time). */
+{
     type: 'tool';
     weapon: string;
+    duration?: number;
 }
 /** `shots` are projectiles (a shotgun shell is many), `rounds` the cartridges spent (a burst is several). */
  | {
@@ -829,10 +903,20 @@ type HostEvent = {
     recoil: [number, number];
     rounds?: number;
     mode?: string;
-} | {
+    suppressed?: boolean;
+}
+/** The trigger was pulled, the round was spent and nothing left the tool (a dud cartridge): no projectile, no recoil. */
+ | {
+    type: 'misfire';
+    weapon: string;
+}
+/** `kind` is how the rule reloads (`tactical`, `empty`, `one_by_one`); `duration` the seconds of the whole reload, on `start`. */
+ | {
     type: 'reload';
     weapon: string;
     phase: 'start' | 'end';
+    kind?: string;
+    duration?: number;
 } | {
     type: 'empty';
     weapon: string;
@@ -849,10 +933,79 @@ type HostEvent = {
     weapon: string;
     fault: string;
     phase: 'start' | 'end';
+    duration?: number;
 } | {
     type: 'safety';
     weapon: string;
     on: boolean;
+}
+/** The action works between shots (a pump, a bolt); `duration` is the seconds of the cycle, on `start`. */
+ | {
+    type: 'cycle';
+    weapon: string;
+    phase: 'start' | 'end';
+    duration?: number;
+}
+/** A step of a longer phase (a reload's magazine out, magazine in, charge), at the moment the rule reaches it. */
+ | {
+    type: 'stage';
+    weapon: string;
+    stage: string;
+}
+/** One more round went into the tool while it loads round by round. */
+ | {
+    type: 'feed';
+    weapon: string;
+}
+/**
+ * A throwable with a timer fuse is cooked: the trigger pulls the pin (`start`, `fuse` is the whole fuse), releasing throws it with what is left of
+ * the fuse (`throw`), and holding past the fuse sets it off in the hand (`burst`, `fuse` 0).
+ */
+ | {
+    type: 'cook';
+    weapon: string;
+    phase: 'start' | 'throw' | 'burst';
+    fuse: number;
+}
+/** An accessory went on (`fit`), came off (`remove`) or broke (`break`) at `mount`; `duration` is the seconds the work takes, on `fit` and `remove`. */
+ | {
+    type: 'attachment';
+    weapon: string;
+    action: 'fit' | 'remove' | 'break';
+    attachment: string;
+    mount: string;
+    duration?: number;
+}
+/** A light or a laser was turned on or off. */
+ | {
+    type: 'toggle';
+    weapon: string;
+    attachment: string;
+    on: boolean;
+}
+/** The stock was folded or slid in (`collapsed`) or opened (`extended`); `kind` is how it moves (`fold`, `retract`), `duration` the seconds it takes. */
+ | {
+    type: 'stock';
+    weapon: string;
+    state: 'collapsed' | 'extended';
+    kind?: string;
+    duration?: number;
+}
+/** The weapon in hand changed between the main weapon and the one under its barrel (`on`: the under-barrel one is in use); `duration` is the seconds of the switch. */
+ | {
+    type: 'underbarrel';
+    weapon: string;
+    on: boolean;
+    duration?: number;
+}
+/** Something blew up: a thrown or launched explosive, a charge, or a part of the world (a fuel barrel); `source` is the weapon or the object, `cause` what set it off. */
+ | {
+    type: 'explosion';
+    source: string;
+    point: Vec3;
+    energy: number;
+    radius: number;
+    cause: string;
 };
 /** The tool in hand as the host sees it. */
 interface HostTool {
@@ -868,6 +1021,52 @@ interface HostTool {
     safety?: boolean;
     /** 0..1 */
     heat?: number;
+    /** What is on the tool (factory parts included): the accessory, where it sits, and whether a light or laser is on. */
+    attachments?: readonly HostToolAttachment[];
+    /** Where the stock is, for a tool with one that folds or slides. */
+    stock?: 'collapsed' | 'extended';
+    /** True while a suppressor is on: the shot sound is the muffled one. */
+    suppressed?: boolean;
+    /** True while the trigger and the reload go to the launcher under the barrel. */
+    underbarrelActive?: boolean;
+    /** Kg: the tool with what is on it. */
+    mass?: number;
+    /** Seconds to bring the tool to the sights, with what is on it. */
+    aimSeconds?: number;
+}
+interface HostToolAttachment {
+    readonly id: string;
+    readonly mount: string;
+    readonly integral?: boolean;
+    readonly on?: boolean;
+}
+/** What a module asks of the tool in hand (accessories, stock, the launcher under the barrel, how it is held). The work takes the seconds the rule gives it and shows as host events. */
+type ToolCommand = {
+    readonly type: 'fit';
+    readonly attachment: string;
+    readonly mount?: string;
+} | {
+    readonly type: 'remove';
+    readonly attachment: string;
+} | {
+    readonly type: 'toggle';
+    readonly attachment: string;
+} | {
+    readonly type: 'stock';
+    readonly state: 'collapsed' | 'extended';
+} | {
+    readonly type: 'underbarrel';
+    readonly on: boolean;
+} | {
+    readonly type: 'stance';
+    readonly aiming?: boolean;
+    readonly supported?: boolean;
+};
+/** `ok`, or why nothing happened (the rule's refusal: `no_mount`, `interface`, `occupied`, `busy`...); `seconds` is how long the work takes. */
+interface ToolCommandResult {
+    readonly ok: boolean;
+    readonly reason?: string;
+    readonly seconds?: number;
 }
 /**
  * What the host lends a module that brings its own presentation (a weapon in the hands, sounds, ejected casings). `THREE`, `scene` and `camera`
@@ -887,6 +1086,13 @@ interface ModuleHost {
     onFrame(update: (dt: number) => void): () => void;
     /** Write a line to the host's behaviour log. */
     log(text: string, data?: Record<string, unknown>): void;
+    /**
+     * Sets what the host lets a module tune on its tools, keyed by the id of the module's own control (`ModuleControl.id`) with the id of the option as the value; the tool in hand changes at once and the
+     * ones taken later start that way. A host applies the ids it knows and ignores the rest. The test room knows `condition` (how worn the tools are) and `ammo_quality` (how good what they load is).
+     */
+    configureTool?(settings: Readonly<Record<string, string>>): void;
+    /** Asks the tool in hand to do something (see `ToolCommand`). A host without accessories leaves it out. */
+    command?(command: ToolCommand): ToolCommandResult;
     /** Lent only to a module that declares controls, layers or metrics. */
     bench?: ModuleBench;
 }
@@ -909,4 +1115,90 @@ interface TestableModule<Context = unknown> {
     attach?(host: ModuleHost): () => void;
 }
 
-export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type BenchChange, type BenchDeclaration, type BenchReport, type BooleanControl, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ContainerSpec, type ControlPatch, type ControlValue, type Crack, type DamageType, type DebrisKind, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type FluidKind, type FractureStyle, type Fragment, type Hit, type HitResult, type Hole, type HostEvent, type HostTool, IMPACT_CONTRACT, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, type LiquidId, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartShape, type PartSpec, type PartState, type PartStatus, type Quat, type RayHit, type Shot, type SpecReport, type StructureRole, type TestableItem, type TestableModule, type ToolKind, type Use, type Vec3, checkAnimation, checkBench, checkDestructible, checkHit, checkSpec, shotToHit };
+/** Clips a tool can bring, one per move of its cycle. A tool brings the ones it has; a missing clip is simply not played. */
+declare const TOOL_CLIP: {
+    readonly DRAW: "draw";
+    readonly SHOT: "shot";
+    readonly MISFIRE: "misfire";
+    readonly EMPTY: "empty";
+    readonly CYCLE: "cycle";
+    readonly RELOAD: "reload";
+    readonly FEED: "feed";
+    readonly FAULT: "fault";
+    readonly CLEAR: "clear";
+    readonly SAFETY_ON: "safety_on";
+    readonly SAFETY_OFF: "safety_off";
+    readonly MODE: "mode";
+    /** A throwable with the pin out, held until it is thrown. */
+    readonly COOK: "cook";
+    /** The stock folds, unfolds, slides in or out (variants `fold`, `unfold`, `collapse`, `extend`). */
+    readonly STOCK: "stock";
+    /** A light or a laser is switched (variants `on`, `off`). */
+    readonly TOGGLE: "toggle";
+};
+type ToolClipId = (typeof TOOL_CLIP)[keyof typeof TOOL_CLIP];
+/** What a renderer does when a rule event arrives. `variant` picks `<clip>_<variant>` when the tool has it, else `<clip>`. */
+type ToolAnimationStep = {
+    readonly type: 'play';
+    readonly clip: ToolClipId;
+    readonly variant?: string;
+    readonly duration?: number;
+    readonly repeat?: number;
+}
+/** Move the clip that is playing to the marker (a clip event `stage` with `data.stage`) the rule just reached. */
+ | {
+    readonly type: 'sync';
+    readonly stage: string;
+}
+/** The rule says the phase is over: the clip jumps to its end if it is still running. */
+ | {
+    readonly type: 'finish';
+    readonly clip: ToolClipId;
+};
+/** The move a host event asks of the tool in hand, or null when it has no motion. */
+declare const toolAnimationStep: (event: HostEvent) => ToolAnimationStep | null;
+/** Where a renderer puts the poses: every part of the tool by id (the ids the clips move), and the whole tool. Poses are offsets from rest. */
+interface ToolRig {
+    setPartPose(partId: string, pose: AnimationPose): void;
+    setRootPose?(pose: AnimationPose): void;
+}
+/** Clips by id, with the variants as `<clip>_<variant>`. */
+type ToolClipSet = Readonly<Record<string, AnimationClipSpec>>;
+/** A renderer's tool animator: feed it the host events and the frame time. */
+interface ToolAnimator {
+    handle(event: HostEvent): void;
+    update(dt: number): void;
+    /** Ids of the clips playing now. */
+    readonly playing: readonly string[];
+    dispose(): void;
+}
+declare const STAGE_EVENT = "stage";
+/** The clip with its times (keys and events) scaled so that it lasts `duration` seconds. */
+declare const scaleClip: (clip: AnimationClipSpec, duration: number) => AnimationClipSpec;
+/** Pose of the whole tool (`partId` undefined) or of one part at `time`, linear between keys; a key that does not name it means rest. */
+declare const sampleClip: (clip: AnimationClipSpec, partId: string | undefined, time: number) => {
+    position: [number, number, number];
+    rotation: [number, number, number];
+};
+/** Problems with a clip set (empty when valid): each key is the clip id (or `<clip>_<variant>`), every clip passes `checkAnimation`, and a `stage` event names its stage. */
+declare const checkToolClips: (clips: ToolClipSet, partIds: Iterable<string>) => {
+    ok: boolean;
+    problems: string[];
+};
+interface ToolClipPlayerOptions {
+    clips: ToolClipSet;
+    rig: ToolRig;
+    /** Called for each clip event as its time passes (`eject_casing`, `drop_magazine`, `stage`...). */
+    onEvent?(event: AnimationEventSpec, clip: string): void;
+    /** Seconds between the rounds of a `repeat` (a burst): default 0.1. */
+    repeatInterval?(): number;
+}
+/** The default player of a tool's clips: runs the steps of `toolAnimationStep` against a rig, scaled to the duration the rule gives. */
+interface ToolClipPlayer {
+    apply(step: ToolAnimationStep): void;
+    update(dt: number): void;
+    readonly playing: readonly string[];
+}
+declare const createToolClipPlayer: (options: ToolClipPlayerOptions) => ToolClipPlayer;
+
+export { type ActionControl, type AnimationClipSpec, type AnimationEventSpec, type AnimationKey, type AnimationPose, type AreaPlacement, type BenchChange, type BenchDeclaration, type BenchReport, type BooleanControl, type ChainDelay, type CheckOptions, type CheckSpecOptions, type ChoiceControl, type ChoiceOption, type ContainerSpec, type ControlPatch, type ControlValue, type Crack, type DamageType, type DebrisKind, type Dent, type DestructibleImpl, type DestructibleSpec, type DestructionEvent, type DestructionEventType, type ExplosionChain, type FluidKind, type FractureStyle, type Fragment, type Hit, type HitResult, type Hole, type HostEvent, type HostTool, type HostToolAttachment, IMPACT_CONTRACT, type ImpactContract, type ItemAnimationContract, type ItemUseDef, type JointKind, type JointSpec, type JointState, type LiquidId, type MaterialId, type ModuleArea, type ModuleBench, type ModuleControl, type ModuleHost, type ModuleItemFluid, type ModuleLayer, type ModuleMetric, type ModuleScenario, type NumberControl, type ObjectState, type PartShape, type PartSpec, type PartState, type PartStatus, type Quat, type RayHit, STAGE_EVENT, type Shot, type SpecReport, type StructureRole, TOOL_CLIP, type TestableItem, type TestableModule, type ToolAnimationStep, type ToolAnimator, type ToolClipId, type ToolClipPlayer, type ToolClipPlayerOptions, type ToolClipSet, type ToolCommand, type ToolCommandResult, type ToolKind, type ToolRig, type Use, type Vec3, checkAnimation, checkBench, checkDestructible, checkHit, checkSpec, checkToolClips, createToolClipPlayer, sampleClip, scaleClip, shotToHit, toolAnimationStep };

package/dist/index.global.js

@@ -22,12 +22,19 @@ var GameContracts = (() => {
   var index_exports = {};
   __export(index_exports, {
     IMPACT_CONTRACT: () => IMPACT_CONTRACT,
+    STAGE_EVENT: () => STAGE_EVENT,
+    TOOL_CLIP: () => TOOL_CLIP,
     checkAnimation: () => checkAnimation,
     checkBench: () => checkBench,
     checkDestructible: () => checkDestructible,
     checkHit: () => checkHit,
     checkSpec: () => checkSpec,
-    shotToHit: () => shotToHit
+    checkToolClips: () => checkToolClips,
+    createToolClipPlayer: () => createToolClipPlayer,
+    sampleClip: () => sampleClip,
+    scaleClip: () => scaleClip,
+    shotToHit: () => shotToHit,
+    toolAnimationStep: () => toolAnimationStep
   });
 
   // src/impact.ts
@@ -274,6 +281,184 @@ var GameContracts = (() => {
     return { ok: problems.length === 0, problems };
   };
 
+  // src/tool-animation.ts
+  var TOOL_CLIP = {
+    DRAW: "draw",
+    SHOT: "shot",
+    MISFIRE: "misfire",
+    EMPTY: "empty",
+    CYCLE: "cycle",
+    RELOAD: "reload",
+    FEED: "feed",
+    FAULT: "fault",
+    CLEAR: "clear",
+    SAFETY_ON: "safety_on",
+    SAFETY_OFF: "safety_off",
+    MODE: "mode",
+    /** A throwable with the pin out, held until it is thrown. */
+    COOK: "cook",
+    /** The stock folds, unfolds, slides in or out (variants `fold`, `unfold`, `collapse`, `extend`). */
+    STOCK: "stock",
+    /** A light or a laser is switched (variants `on`, `off`). */
+    TOGGLE: "toggle"
+  };
+  var stockVariant = (event) => {
+    const isFolding = event.kind === void 0 ? false : event.kind.includes("fold");
+    if (event.state === "collapsed") return isFolding ? "fold" : "collapse";
+    return isFolding ? "unfold" : "extend";
+  };
+  var toolAnimationStep = (event) => {
+    switch (event.type) {
+      case "tool":
+        return { type: "play", clip: TOOL_CLIP.DRAW, ...event.duration === void 0 ? {} : { duration: event.duration } };
+      case "shot":
+        return { type: "play", clip: TOOL_CLIP.SHOT, repeat: Math.max(1, event.rounds ?? 1) };
+      case "misfire":
+        return { type: "play", clip: TOOL_CLIP.MISFIRE };
+      case "empty":
+        return { type: "play", clip: TOOL_CLIP.EMPTY };
+      case "mode":
+        return { type: "play", clip: TOOL_CLIP.MODE, variant: event.mode };
+      case "fault":
+        return { type: "play", clip: TOOL_CLIP.FAULT, variant: event.fault };
+      case "clear":
+        if (event.phase === "end") return { type: "finish", clip: TOOL_CLIP.CLEAR };
+        return { type: "play", clip: TOOL_CLIP.CLEAR, variant: event.fault, ...event.duration === void 0 ? {} : { duration: event.duration } };
+      case "safety":
+        return { type: "play", clip: event.on ? TOOL_CLIP.SAFETY_ON : TOOL_CLIP.SAFETY_OFF };
+      case "cycle":
+        if (event.phase === "end") return { type: "finish", clip: TOOL_CLIP.CYCLE };
+        return { type: "play", clip: TOOL_CLIP.CYCLE, ...event.duration === void 0 ? {} : { duration: event.duration } };
+      case "reload":
+        if (event.phase === "end") return { type: "finish", clip: TOOL_CLIP.RELOAD };
+        return { type: "play", clip: TOOL_CLIP.RELOAD, ...event.kind === void 0 ? {} : { variant: event.kind }, ...event.duration === void 0 ? {} : { duration: event.duration } };
+      case "stage":
+        return { type: "sync", stage: event.stage };
+      case "feed":
+        return { type: "play", clip: TOOL_CLIP.FEED };
+      case "cook":
+        if (event.phase === "start") return { type: "play", clip: TOOL_CLIP.COOK, duration: event.fuse };
+        return { type: "finish", clip: TOOL_CLIP.COOK };
+      case "stock":
+        return { type: "play", clip: TOOL_CLIP.STOCK, variant: stockVariant(event), ...event.duration === void 0 ? {} : { duration: event.duration } };
+      case "toggle":
+        return { type: "play", clip: TOOL_CLIP.TOGGLE, variant: event.on ? "on" : "off" };
+      default:
+        return null;
+    }
+  };
+  var STAGE_EVENT = "stage";
+  var scaleClip = (clip, duration) => {
+    const factor = clip.duration > 0 ? duration / clip.duration : 1;
+    return {
+      ...clip,
+      duration,
+      keys: clip.keys.map((key) => ({ ...key, t: key.t * factor })),
+      ...clip.events ? { events: clip.events.map((event) => ({ ...event, t: event.t * factor })) } : {}
+    };
+  };
+  var ZERO = [0, 0, 0];
+  var mix = (from, to, fraction) => [
+    (from[0] ?? 0) + ((to[0] ?? 0) - (from[0] ?? 0)) * fraction,
+    (from[1] ?? 0) + ((to[1] ?? 0) - (from[1] ?? 0)) * fraction,
+    (from[2] ?? 0) + ((to[2] ?? 0) - (from[2] ?? 0)) * fraction
+  ];
+  var sampleClip = (clip, partId, time) => {
+    const points = clip.keys.map((key) => {
+      const pose = partId === void 0 ? key : key.parts?.[partId];
+      return { t: key.t, position: pose?.position ?? ZERO, rotation: pose?.rotation ?? ZERO };
+    });
+    const first = points[0];
+    if (!first || first.t > 0) points.unshift({ t: 0, position: ZERO, rotation: ZERO });
+    const last = points[points.length - 1];
+    if (!last) return { position: ZERO, rotation: ZERO };
+    if (time >= last.t) return { position: mix(last.position, last.position, 0), rotation: mix(last.rotation, last.rotation, 0) };
+    const index = Math.max(0, points.findIndex((point, i) => time >= point.t && time < (points[i + 1]?.t ?? Infinity)));
+    const from = points[index];
+    const to = points[index + 1];
+    if (!from || !to) return { position: ZERO, rotation: ZERO };
+    const fraction = to.t > from.t ? (time - from.t) / (to.t - from.t) : 0;
+    return { position: mix(from.position, to.position, fraction), rotation: mix(from.rotation, to.rotation, fraction) };
+  };
+  var checkToolClips = (clips, partIds) => {
+    const parts = [...partIds];
+    const problems = [];
+    for (const [key, clip] of Object.entries(clips)) {
+      if (clip.id !== key) problems.push(`clip "${key}" has the id "${clip.id}"`);
+      if (!(clip.duration > 0)) problems.push(`clip "${key}" has no duration`);
+      problems.push(...checkAnimation(clip, parts).problems);
+      for (const event of clip.events ?? []) if (event.type === STAGE_EVENT && typeof event.data?.stage !== "string") problems.push(`clip "${key}" has a stage event without data.stage`);
+    }
+    return { ok: problems.length === 0, problems };
+  };
+  var createToolClipPlayer = (options) => {
+    const { clips, rig, onEvent } = options;
+    let instances = [];
+    const find = (clip, variant) => {
+      const name = variant !== void 0 && clips[`${clip}_${variant}`] ? `${clip}_${variant}` : clip;
+      const found = clips[name];
+      return found ? { name, clip: found } : void 0;
+    };
+    const render = (instance) => {
+      const time = Math.min(instance.time, instance.clip.duration);
+      const root = sampleClip(instance.clip, void 0, time);
+      if (instance.clip.keys.some((key) => key.position || key.rotation)) rig.setRootPose?.(root);
+      const touched = new Set(instance.clip.keys.flatMap((key) => Object.keys(key.parts ?? {})));
+      for (const id of touched) rig.setPartPose(id, sampleClip(instance.clip, id, time));
+    };
+    const fireEvents = (instance, upTo) => {
+      const events = instance.clip.events ?? [];
+      while (instance.fired < events.length && (events[instance.fired]?.t ?? Infinity) <= upTo + 1e-9) {
+        const event = events[instance.fired];
+        instance.fired += 1;
+        if (event) onEvent?.(event, instance.name);
+      }
+    };
+    return {
+      apply(step) {
+        if (step.type === "sync") {
+          for (const instance of instances) {
+            const marker = (instance.clip.events ?? []).find((event) => event.type === STAGE_EVENT && event.data?.stage === step.stage);
+            if (marker && instance.time < marker.t) instance.time = marker.t;
+          }
+          return;
+        }
+        if (step.type === "finish") {
+          for (const instance of instances) {
+            if (instance.name !== step.clip && !instance.name.startsWith(`${step.clip}_`)) continue;
+            fireEvents(instance, instance.clip.duration);
+            instance.time = instance.clip.duration;
+          }
+          return;
+        }
+        const found = find(step.clip, step.variant);
+        if (!found) return;
+        const clip = step.duration && step.duration > 0 ? scaleClip(found.clip, step.duration) : found.clip;
+        const interval = options.repeatInterval?.() ?? 0.1;
+        instances = instances.filter((existing) => existing.name !== found.name || existing.delay > 0);
+        for (let round = 0; round < (step.repeat ?? 1); round++) {
+          instances.push({ name: found.name, clip, time: 0, delay: round * interval, fired: 0 });
+        }
+      },
+      update(dt) {
+        for (const instance of instances) {
+          const carried = instance.delay > 0 ? dt - instance.delay : dt;
+          if (instance.delay > 0) {
+            instance.delay = Math.max(0, instance.delay - dt);
+            if (instance.delay > 0) continue;
+          }
+          instance.time += carried;
+          fireEvents(instance, instance.time);
+          render(instance);
+        }
+        instances = instances.filter((instance) => instance.delay > 0 || instance.time < instance.clip.duration);
+      },
+      get playing() {
+        return instances.map((instance) => instance.name);
+      }
+    };
+  };
+
   // src/bench.ts
   var SNAKE_CASE = /^[a-z][a-z0-9_]*$/;
   var finite2 = (n) => typeof n === "number" && Number.isFinite(n);