@adatechnology/game-characters-three 0.2.1 → 0.3.0

package/README.md

@@ -27,3 +27,34 @@ time.value += dt
 
 - `createCharacterSound(host.audio, { style? })`: `voice(typeId, 'idle' | 'alert' | 'special', position)` for the 13 undead types (`UNDEAD_VOICES`: the game's groans and scream, the art scene's `voice` groan, scream and leap, with the class rule of the page for the types it does not have), `body(event, position)` (wound = flesh, cut = sever, burst or split = gore), `player('grab' | 'bite' | 'hurt')`. The 16 recipes (`CHARACTER_SOUND_BANK`) leave the same trace as the team code.
 - `createFluidsBridge({ sink, film })` and `bloodLookOfAge(age)`: a `body` event throws drops of blood into the film, in the fresh and dry colours of the infection age (`ages.json`), `old_blood` for the thin ones.
+
+**Player avatar.** `createPlayerAvatar(THREE, options?)` is the team game's player body: the rich human of the Bestiário/Elenco built from `presets/player-avatar.json`
+(`{ type: 'Lento', human: true, seed: 4242, skin, hs: 'short', hair }`, shirt `0x3d5a73`), overridable with `{ spec, shirtColor, clips, blend, fallSeconds }`.
+
+```ts
+const player = createPlayerAvatar(THREE)
+scene.add(player.root)
+player.update(dt, { speed, crouch, down, armed, pitch, hip }) // the gait is tied to the ground speed (cadence and swing from `walkCadence`/`walkGait`)
+player.hand('R').add(weaponMesh) // a socket at the weapon hand
+player.play('grabbed_bitten_human', { onEvent: (event) => event.type === 'impact' && applyBlow() }) // or player.play(myClip); player.on('event', fn); player.stop()
+```
+
+Crouch, down and the aimed arms are derived literally from the game's GPU pose code (`BODY_CHUNK`, lines quoted in `src/player/avatar.ts`): crouch is thigh `-0.95`, knee `1.9`, trunk `+0.25`, hip `-0.35`;
+down turns the body about the hip (`±1.5` rad, face up or down by the phase) with the limbs of pose 2; `armed` follows `(pitch + 1) / 3`. `play` overlays a `PoseClip` of `@adatechnology/game-characters`
+(`channels: 'upper'` leaves the legs to the gait) with a 0.12 s blend, and fires its events (`impact`, `phase`) once through `onEvent` and `on('event')`. `hand('R')` is the weapon hand (the puppet's right, at -x).
+
+**In the test room.** `room.setAvatar(toRoomAvatar(player))` shows the body at the player's feet (`toRoomAvatar` only flips the pitch: the room counts a look up as positive, the team game a look down) and V switches between the first and the third person of
+`@adatechnology/game-test-room`. `createAvatarTestModule({ avatar, camera, state })` is the module of the area `avatar_area` (`AVATAR_AREA_ID`): bench buttons for the view (1st/3rd person), crouch, stand, fall, get up, armed on/off,
+one button per registered clip (`Tocar: grabbed_bitten_human`, `grab_bite_zombie`, and with `clips: [...POSE_CLIPS, ...ATTACK_CLIPS]` the punch, shove, kick and the recoils; `clipLocales` gives the phase texts) and stop; metrics for the camera, the clip playing, the last clip event and the joints. Every action is a JSON line in the room log (`{"type":"avatar","action":"play_clip","clip":...}`), clip events included, and an `impact` event also gets its own `{"action":"impact","clip":...,"t":...}` line.
+The module takes the body, the view (`camera: { mode, set }`) and the state (`state: { set }`) by option and imports only `@adatechnology/game-contracts`.
+
+`toRoomAvatar` also gives the room the first-person arms (`firstPerson: false` for none) and `strike(clipId)`, which plays the attack clip on the body and the first-person clip of the same id on the arms and answers the seconds to the impact (the same in both views).
+
+**First-person arms.** `createFirstPersonArms(THREE, { colors?, rig?, stances?, clips?, blend?, bob? })` builds sleeves (upper arm, forearm, elbow, cuff) and hands of skin (palm, four fingers of three segments, a thumb that close on a grip) drawn in the camera's space, plus the right leg that only shows during a kick. `arms.update(dt, { camera, targets, stance, speed, running, crouch, contact? })`: the `relaxed` and `fists` stances are rest poses (`FIRST_PERSON_STANCES`, from `presets/first-person-arms.json`), `hold` follows the `HandTargets` of `game-contracts` (world space) with a two-bone IK from fixed shoulders, the elbow bending down and out; a target out of reach is clamped (the shoulder moves `reachShift` toward it first). `arms.play('punch_right' | 'shove_two_hands' | 'front_kick')` overlays a `FirstPersonClip` (`FIRST_PERSON_CLIPS` of `game-characters-people`, same durations and impact seconds as the attack clips); `arms.on('event', fn)` gives its `impact`; `arms.handPose(side)` reads where a hand is drawn. `contact(origin, direction, maxDistance)` (optional; distance to the first surface or null) makes the hands and the kick foot stop a few millimetres before a surface along the camera forward (the elbow bends); `arms.play('front_kick', { leg: 'left' })` kicks with the left leg. Hand frame: x wrist to knuckles, y back of the hand, z little-finger side; a left hand is the right one mirrored.
+
+## Geometry
+
+The builders (`createPersonBuilder`, `createBestBuilder`, `bakeBody`, `buildInstancedBody`, `createFlyingLimbs`, `createEye`) draw with
+`shapeGeometries(host)` of [`game-shapes-three`](../game-shapes-three): boxes, cylinders, cones, spheres, circles, rings, lathes and tori come
+from game-shapes with the same bytes; dodecahedron, shape and capsule geometries are three's. `tests/exact-golden.test.ts` holds every bit as
+the old path made them.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as THREE_NS from 'three';
-import { BodySpec, CascadeJoint, RestPose, StrideParams, GaitSample, lerpPose, GaitProfile, SegmentId, CharacterKit, CharacterPack, CharacterSpec, DamageCharacter, BodyHit } from '@adatechnology/game-characters';
-import { Vec3 as Vec3$1, DestructionEvent, SoundRequest, TestableModule } from '@adatechnology/game-contracts';
+import { BodySpec, CascadeJoint, RestPose as RestPose$1, StrideParams, GaitSample, lerpPose, GaitProfile, SegmentId, CharacterKit, CharacterPack, CharacterSpec, DamageCharacter, BodyHit, PoseClipEvent, PoseClip, PoseClipRegistry, FirstPersonClip } from '@adatechnology/game-characters';
+import { Vec3 as Vec3$1, DestructionEvent, SoundRequest, TestableModule, HandTargets } from '@adatechnology/game-contracts';
 import { SoundRecipe, SoundBank } from '@adatechnology/game-audio';
 
 /** The three.js namespace the host passes in: the package never imports three itself, so one script tag works. */
@@ -49,7 +49,7 @@ type BuildInstancedBodyParams = {
  * The crowd body as one merged geometry, torso, head, hair, jaw, eyes, arms and legs tagged with the bone, pivot and material the shader reads
  * (G 65367 `buildBody`). The joints come from the spec, so a different `body` moves the limbs; the parts' own sizes follow the segment lengths.
  */
-declare const buildInstancedBody: (three: Three, { segments, body }: BuildInstancedBodyParams) => Geometry;
+declare const buildInstancedBody: (host: Three, { segments, body }: BuildInstancedBodyParams) => Geometry;
 
 type BodyMaterialParams = {
     /** The depth material for shadows (true) or the lit body (false). */
@@ -161,7 +161,7 @@ type BakedBody = {
  * Bakes a rich body into one indexable geometry, each vertex with its bone, pivot, parent pivot and colour, so the instanced shader can animate it
  * (G 66019 `bakeBody`). Blood stays a vivid wine red at any decay; eyes are enlarged far away so they read.
  */
-declare const bakeBody: (three: Three, builders: BakeBuilders, spec: BakeSpec, lod: number) => BakedBody;
+declare const bakeBody: (host: Three, builders: BakeBuilders, spec: BakeSpec, lod: number) => BakedBody;
 
 type VariantType = {
     readonly id: string;
@@ -250,7 +250,7 @@ type FlyingLimbs = {
     update(dt: number): void;
 };
 /** Torn-off pieces that fly, bounce and stay on the ground, as one instanced mesh of capsules (G 67953 `fxLimb`, 68040 update). */
-declare const createFlyingLimbs: (three: Three, { max, random, effects }: FlyingLimbsOptions) => FlyingLimbs;
+declare const createFlyingLimbs: (host: Three, { max, random, effects }: FlyingLimbsOptions) => FlyingLimbs;
 
 type Euler3 = {
     x: number;
@@ -314,7 +314,7 @@ type RigAnimatorOptions = {
 };
 type RigAnimator = {
     /** The pose the gait swings around (legs `lost` stay out of the swing). */
-    restOf(rig: RichRig): RestPose;
+    restOf(rig: RichRig): RestPose$1;
     /** The Bestiário's `animate0`: sets the joint rotations of one gait at `time`. `stride` ties cadence and swing to the ground speed. */
     animate0(root: THREE_NS.Object3D, time: number, stride?: StrideParams): GaitSample | undefined;
     /** `animate0` plus the bits that hang loose: the dangling forearm and the flaps of torn flesh. */
@@ -349,7 +349,7 @@ type BestBuilder = {
     /** The shirt material of the last body built (the bake marks it as material 1). */
     topM(): any;
 };
-declare const createBestBuilder: (THREE: Three, { types, random }: BestBuilderOptions) => BestBuilder;
+declare const createBestBuilder: (host: Three, { types, random }: BestBuilderOptions) => BestBuilder;
 
 type PersonBuilderOptions = {
     /** The stream for stains and phases. The page shared one `rng(77)` across the cast, built in order; default the same. */
@@ -371,7 +371,7 @@ type PersonBuilder = {
         chars: any[];
     };
 };
-declare const createPersonBuilder: (THREE: Three, options?: PersonBuilderOptions) => PersonBuilder;
+declare const createPersonBuilder: (host: Three, options?: PersonBuilderOptions) => PersonBuilder;
 
 type ExtraContext = {
     THREE: any;
@@ -471,7 +471,7 @@ type EyeOptions = {
     readonly texture?: THREE_NS.Texture | null;
 };
 /** One glowing eye: an unlit ball (emissive by itself) and an additive sprite on top. Add it to the head group at the socket. */
-declare const createEye: (three: Three, { color, radius, glow, glowOpacity, texture }: EyeOptions) => THREE_NS.Group;
+declare const createEye: (host: Three, { color, radius, glow, glowOpacity, texture }: EyeOptions) => THREE_NS.Group;
 type Eyes = {
     /** The eyeballs: the meshes the builder marked `userData.eye`. They are what a test layer can ask for with `isolate`. */
     readonly markable: readonly THREE_NS.Mesh[];
@@ -1023,4 +1023,322 @@ declare const UNDEAD_VOICE_GROUP = "undead_voice";
 declare const CHARACTER_SOUNDS: readonly SoundRecipe[];
 declare const CHARACTER_SOUND_BANK: SoundBank;
 
-export { type AreaContext, BAKE_NEUTRAL_POSE, BODY_CHUNK, BODY_MATERIAL_DEF, BODY_SOUNDS, type BakeBuilders, type BakeSpec, type BakedBody, type BestBuilder, type BestBuilderOptions, type BestTypeCard, type BloodAge, type BloodLook, type BloodLookOptions, type BloodSink, type BodyBatch, type BodyBatchOptions, type BodyChunkOptions, type BodyInstance, type BodyJoints, type BodyMaterialParams, type BodySoundRule, type BodyVariant, type BuildInstancedBodyParams, CHARACTERS_AREA_ID, CHARACTER_SOUNDS, CHARACTER_SOUND_BANK, type CharacterSound, type CharacterSoundOptions, type CharacterSoundSink, type CharacterSoundStyle, type CharactersTestOptions, EXTRAS, type EyeOptions, type Eyes, FACE_FEATURES, type FilmSink, type FluidsBridge, type FluidsBridgeOptions, type FlyingLimb, type FlyingLimbs, type FlyingLimbsOptions, type FlyingPiece, type FlyingPieces, type FlyingPiecesOptions, HAND_ITEMS, HATS, HIT_PRESETS, type HitPreset, LOD_BAKE, LOD_BATCH_CAPACITY, LOD_CASTS_SHADOW, LOD_DISTANCES, LOD_SEGMENTS, type LimbEffects, type LimbLaunch, PENDULUM, PERSON_ITEM_PREFIX, PLAYER_SOUNDS, type Pendulum, type PersonBuilder, type PersonBuilderOptions, type PoseTargets, type ProfessionCard, type RichRig, type RigAnimator, type RigAnimatorOptions, type Three, UNDEAD_VOICES, UNDEAD_VOICE_GROUP, UNDEAD_VOICE_SOURCES, type UndeadCard, type UndeadLike, type UndeadVoice, type VariantType, type VoiceMoment, type VoiceStep, type WoundBody, type WoundMaterials, type WoundNode, type WoundSpray, type Wounds, type WoundsOptions, ZOMBIE_ITEM_PREFIX, bakeBody, bakeVariants, blobGeometry, blobRadii, bloodLookOfAge, buildInstancedBody, createBestBuilder, createBodyBatch, createBodyChunk, createBodyMaterial, createCharacterSound, createCharactersTestModule, createEye, createFluidsBridge, createFlyingLimbs, createFlyingPieces, createGlowTexture, createPendulum, createPersonBuilder, createRigAnimator, createVariantBatches, createWoundMaterials, createWounds, exitWound, explodeChunks, findEyes, gouge, jointsOf, lodAt, makeCut, makeStump, registerBodyMaterial, ringWound, starGeometry, stepPendulum, woundBodyOf, woundDecal };
+type PlayerAvatarSpec = Record<string, unknown>;
+type PlayerAvatarOptions = {
+    /** The body spec for the rich builder (`createBestBuilder.build`). Default: the team game's player (`player-avatar.json`). Merged over the default. */
+    readonly spec?: PlayerAvatarSpec;
+    /** Shirt colour, 0xRRGGBB. Default the team game's `PLAYER_COR`. */
+    readonly shirtColor?: number;
+    /** The clips `play(id)` finds. Default: a registry with `POSE_CLIPS`. */
+    readonly clips?: PoseClipRegistry;
+    /** Seconds to blend a clip in and out. Default 0.12. */
+    readonly blend?: number;
+    /** Seconds the body takes to go down (the shader's `fk` smoothstep). 0 is instant. Default 0.3. */
+    readonly fallSeconds?: number;
+    /** Smooth the joints with the Bestiário cascade (default true). */
+    readonly cascade?: boolean;
+};
+type AvatarEvent = PoseClipEvent & {
+    clip: string;
+};
+type AvatarUpdate = {
+    /** Ground speed, m/s. Ties cadence and swing to the ground (the game's `walkCad` and `walkGait`). */
+    speed?: number;
+    /** Accepted for the game's state; the gait depends on the speed alone, as in the team game. */
+    running?: boolean;
+    crouch?: boolean;
+    down?: boolean;
+    /** Weapon in hand: both arms follow the aim (the game's arm code). Default false. */
+    armed?: boolean;
+    /** The camera pitch the game's `playerArmCode()` reads (`view.pitch`). */
+    pitch?: number;
+    /** Leg yaw toward the step while armed (the game's `P.hip`, radians). */
+    hip?: number;
+};
+type PlayPoseOptions = {
+    onEvent?: (event: AvatarEvent) => void;
+    /** Overrides the avatar's blend for this clip. */
+    blend?: number;
+};
+/** The colours the body was drawn with, for whatever has to match it (the first-person arms): skin, shirt, trousers and shoes as 0xRRGGBB, and whether the sleeves cover the forearms. */
+type PlayerAvatarColors = {
+    skin: number;
+    shirt: number;
+    trousers: number;
+    shoes: number;
+    longSleeves: boolean;
+};
+type PlayerAvatar = {
+    root: THREE_NS.Object3D;
+    rig: RichRig;
+    /** What the body wears, read from the body itself. */
+    readonly colors: PlayerAvatarColors;
+    /** The three.js namespace the body was made with, so what is made to fit it (the first-person arms) uses the same one. */
+    readonly three: Three;
+    update(dt: number, state?: AvatarUpdate): void;
+    play(clip: string | PoseClip, options?: PlayPoseOptions): void;
+    stop(): void;
+    readonly playing: string | null;
+    /** A socket at the hand: 'R' is the weapon hand (the puppet's right, at -x), 'L' the other one. */
+    hand(side: 'R' | 'L'): THREE_NS.Object3D;
+    on(type: 'event', listener: (event: AvatarEvent) => void): () => void;
+    dispose(): void;
+};
+/**
+ * The player's body: the rich human of the Bestiário/Elenco, built with the team game's player spec (data, overridable), walking with the engine's gait tied
+ * to the ground speed, with the crouch and the knock-down of the game's GPU pose code (`BODY_CHUNK`) and a pose-clip overlay (`play`).
+ */
+declare const createPlayerAvatar: (THREE: Three, options?: PlayerAvatarOptions) => PlayerAvatar;
+
+type Triple = [number, number, number];
+/**
+ * A hand (or the foot) at rest, in the camera's space: x to the right, y up, the view looks down -z. `p` is the middle of the palm, `r` the Euler angles `[roll, yaw, pitch]` in the order YZX:
+ * with all three at 0 the fingers point to the right (+x) and the back of the hand up; a yaw of pi/2 turns the fingers to the front (-z), the pitch tilts them up (+) or down (-) and the roll turns
+ * the hand about its fingers. The hand-local frame is the one of `HandPose` in `game-contracts`: x to the knuckles, y the back of the hand, z the little-finger side of a right hand.
+ */
+type RestPose = {
+    p: Triple;
+    r: Triple;
+    grip?: number;
+};
+/** Where the hands are while the stance is held. `follow` takes the hands from the targets (a hand without one goes to the `fallback` stance); a left hand of `'mirror'` is the mirror image of the right. */
+type StanceDef = {
+    R?: RestPose;
+    L?: RestPose | 'mirror';
+    follow?: boolean;
+    fallback?: string;
+};
+/** The body of the arms, in metres in the camera's space. */
+type FirstPersonRig = {
+    /** Right shoulder; the left one is its mirror image. */
+    shoulder: Triple;
+    upper: number;
+    fore: number;
+    /** How far (m) a shoulder may move toward a hand it cannot reach, so long tools stay in the hands. 0 keeps the shoulders where they are. */
+    reachShift: number;
+    /** From the wrist (where the sleeve ends) to the middle of the palm. */
+    wrist: number;
+    /** The way the elbow bends, for the right arm; mirrored for the left. */
+    elbowPole: Triple;
+    /** The left shoulder and the way its elbow bends, when they are not the mirror image of the right's: the support hand cups a handguard from below, so its shoulder sits nearer the middle and the elbow hangs under the forearm. */
+    shoulderLeft?: Triple;
+    elbowPoleLeft?: Triple;
+    radius: {
+        shoulder: number;
+        elbow: number;
+        wrist: number;
+        cuff: number;
+    };
+    /** The right hip, the bones of the leg, the way the knee bends, and where the foot waits below the view. */
+    hip: Triple;
+    thigh: number;
+    shin: number;
+    kneePole: Triple;
+    foot: RestPose;
+};
+type FirstPersonBob = {
+    /** Radians of the bob per metre walked. */
+    frequency: number;
+    /** Metres of sway to the side and of rise and fall at a full walk. */
+    x: number;
+    y: number;
+    /** The bob of running against walking. */
+    run: number;
+    /** Speed (m/s) at which the bob is full. */
+    fullSpeed: number;
+    /** Metres the arms sink when crouched. */
+    crouch: number;
+};
+type FirstPersonColors = {
+    /** 0xRRGGBB. Defaults come from the player's preset (`player-avatar.json`) and, with `createPlayerAvatar`, from the body itself. */
+    skin: number;
+    sleeve: number;
+    cuff: number;
+    trouser: number;
+    shoe: number;
+};
+type FirstPersonArmsOptions = {
+    colors?: Partial<FirstPersonColors>;
+    rig?: Partial<Omit<FirstPersonRig, 'radius' | 'foot'>> & {
+        radius?: Partial<FirstPersonRig['radius']>;
+        foot?: RestPose;
+    };
+    /** Stances by id, merged over `relaxed`, `fists` and `hold`. */
+    stances?: Readonly<Record<string, StanceDef>>;
+    /** The clips `play(id)` finds, such as `FIRST_PERSON_CLIPS` of game-characters-people. Default none. */
+    clips?: readonly FirstPersonClip[];
+    /** Seconds to move from one stance (or from a held tool to the rest) to the next. Default 0.18. */
+    blend?: number;
+    bob?: Partial<FirstPersonBob>;
+};
+type FirstPersonArmsState = {
+    /** The player's eye. The arms are drawn in its space, so they cannot leave the view. */
+    camera: THREE_NS.Object3D;
+    /** Where the tool in the hands asks them to be (world space), as `ModuleHost.setHandTargets` lends it. */
+    targets?: HandTargets | null;
+    /** `hold` follows the targets; any other stance is a rest pose. Default `relaxed`. */
+    stance?: string;
+    /** Where the world is: the distance along a ray (world space) to the first surface, or null for none within `maxDistance`. The hands and the foot stop at the surface (the elbow bends) instead of going into it. */
+    contact?(origin: [number, number, number], direction: [number, number, number], maxDistance: number): number | null;
+    /** Ground speed, m/s. */
+    speed?: number;
+    running?: boolean;
+    crouch?: boolean;
+};
+type FirstPersonEvent = PoseClipEvent & {
+    clip: string;
+};
+type FirstPersonArms = {
+    /** Add it to the scene: it follows the camera by itself. */
+    root: THREE_NS.Group;
+    /** Starts a clip; false when no registered clip has that id. The previous clip is dropped. */
+    /** `leg: 'left'` plays the foot of the clip (the right foot) as the left one, in a mirror. */
+    play(clip: string, options?: {
+        leg?: 'left' | 'right';
+    }): boolean;
+    stop(): void;
+    /** The clip being played, or null. */
+    readonly playing: string | null;
+    /** The stance of the last update. */
+    readonly stance: string;
+    update(dt: number, state: FirstPersonArmsState): void;
+    /** The clip's events (`impact` included), at the moment the clock reaches them. Returns the unsubscribe function. */
+    on(type: 'event', listener: (event: FirstPersonEvent) => void): () => void;
+    /** The camera-space pose the hand is drawn at (for tests and for hosts that attach things to it). */
+    handPose(side: 'R' | 'L'): {
+        position: THREE_NS.Vector3;
+        quaternion: THREE_NS.Quaternion;
+        grip: number;
+    };
+    /** Where the arm is drawn, in the camera's space: the shoulder, the elbow and the wrist (for tests of the way an arm reaches a hand). */
+    joints(side: 'R' | 'L'): {
+        shoulder: THREE_NS.Vector3;
+        elbow: THREE_NS.Vector3;
+        wrist: THREE_NS.Vector3;
+    };
+    dispose(): void;
+};
+
+/** What `@adatechnology/game-test-room` calls a `RoomAvatar`, restated here so this package does not depend on the room. */
+type RoomAvatarLike = {
+    root: THREE_NS.Object3D;
+    update(dt: number, state: {
+        speed: number;
+        running: boolean;
+        crouch: boolean;
+        down: boolean;
+        armed: boolean;
+        pitch: number;
+    }): void;
+    hand(side: 'R' | 'L'): THREE_NS.Object3D;
+    /** The arms of the first-person view (`RoomAvatar.firstPerson`); absent when `toRoomAvatar` was told to make none. */
+    firstPerson?: {
+        root: THREE_NS.Object3D;
+        update(dt: number, state: {
+            camera: THREE_NS.Object3D;
+            targets: HandTargets | null;
+            stance: string;
+            speed: number;
+            running: boolean;
+            crouch: boolean;
+            contact?(origin: [number, number, number], direction: [number, number, number], maxDistance: number): number | null;
+        }): void;
+    };
+    /** Plays a strike on the body and the arms and answers the seconds to its impact (`RoomAvatar.strike`). */
+    strike(clipId: string, options?: {
+        leg?: 'left' | 'right';
+    }): number | null;
+    /** The avatar it wraps. */
+    readonly avatar: PlayerAvatar;
+    /** The first-person arms, for whoever wants more of them than the room asks (`play`, `on('event')`). */
+    readonly arms: FirstPersonArms | null;
+};
+type ToRoomAvatarOptions = {
+    /** The first-person arms: `false` for none, else the options of `createFirstPersonArms` (merged over the colours of the body and `firstPersonClips`). */
+    firstPerson?: false | FirstPersonArmsOptions;
+    /** The third-person strike clips `strike` finds by id. Default `ATTACK_CLIPS` of game-characters-people. */
+    strikeClips?: readonly PoseClip[];
+    /** The first-person clips the arms play. Default `FIRST_PERSON_CLIPS` of game-characters-people. */
+    firstPersonClips?: readonly FirstPersonClip[];
+};
+/**
+ * Fits the player's body to the test room's `RoomAvatar` (`room.setAvatar(toRoomAvatar(createPlayerAvatar(THREE)))`). It changes the sign of the pitch: the room
+ * counts a look up as positive, the team game's `view.pitch` (what `AvatarUpdate.pitch` reads) counts a look down as positive. It also gives the room the first-person arms, dressed in the
+ * colours of the body (`firstPerson: false` for none), and `strike(clipId)`: the strike plays on the body (the attack clips) and on the arms (the first-person clips), and answers the seconds to its
+ * impact, which are the same in both views.
+ */
+declare const toRoomAvatar: (avatar: PlayerAvatar, options?: ToRoomAvatarOptions) => RoomAvatarLike;
+
+declare const AVATAR_AREA_ID = "avatar_area";
+type AvatarTestOptions = {
+    /** The body under test (the example makes it with `createPlayerAvatar(THREE)` and gives the same one to the room). */
+    avatar: PlayerAvatar;
+    /** The text language when the host does not ask for one. Default `pt-BR`. */
+    locale?: string;
+    /** The clips offered as buttons. Default `POSE_CLIPS` (the two of the Bestiário); a game adds its strikes, such as `ATTACK_CLIPS` of game-characters-people. */
+    clips?: readonly PoseClip[];
+    /** Texts of the `phase` labels of `clips` by locale, merged over `POSE_CLIP_LOCALES` (for example `ATTACK_CLIP_LOCALES`). */
+    clipLocales?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /** The room's view: `mode()` reads it, `set` changes it (`room.cameraMode` and `room.setCameraMode`). Without it the camera buttons only log. */
+    camera?: {
+        mode(): 'first' | 'third';
+        set(mode: 'first' | 'third'): void;
+    };
+    /** The room's avatar state (`room.setAvatarState`): the module drives crouch, down and the armed arms through it. */
+    state?: {
+        set(state: {
+            crouch?: boolean;
+            down?: boolean;
+            armed?: boolean | null;
+        }): void;
+    };
+};
+/**
+ * The player's body as a `TestableModule` for the area `avatar_area`: bench buttons for the view (1st and 3rd person), crouch, fall and get up, the armed arms and every registered
+ * pose clip (grab, bite), and metrics for the camera, the clip, its last event and the joints. Every action goes to the room's
+ * log as JSON. It uses only the contracts: the body, the camera and the state come in by option, so the module knows no room.
+ */
+declare function createAvatarTestModule(options: AvatarTestOptions): TestableModule & {
+    readonly state: {
+        crouch: boolean;
+        down: boolean;
+        armed: boolean | null;
+    };
+};
+
+/** The stances of the preset: `relaxed` and `fists` are rest poses, `hold` follows the targets of the tool in the hands. */
+declare const FIRST_PERSON_STANCES: Readonly<Record<string, StanceDef>>;
+/** The rig of the preset: shoulders, bones, elbow pole, hips and the leg of the kick. */
+declare const FIRST_PERSON_RIG: FirstPersonRig;
+declare const FIRST_PERSON_BOB: FirstPersonBob;
+/** The colours of the player's preset: the skin and the shirt of the team game's player, trousers and shoes of a plain outfit. */
+declare const FIRST_PERSON_COLORS: FirstPersonColors;
+/**
+ * The player's arms in first person, drawn in the space of the camera so they cannot leave the view. Each arm is a sleeve (upper arm and forearm, an elbow and a cuff) and a hand of skin (a palm,
+ * four fingers of three segments and a thumb that close on a grip); the right leg (trouser and shoe) appears only while a kick holds it. The hands go where the stance puts them (`relaxed`, `fists`) or,
+ * in the `hold` stance, where the tool in the hands asks (`HandTargets` of game-contracts, world space); a two-bone IK from fixed shoulders brings the sleeves to them, the elbow bending down and out. A
+ * clip (`play`) moves the hands and the foot over that, by a weight that is 0 at its start and end.
+ *
+ * Hand frame (both hands, as `HandPose`): x from the wrist to the knuckles, y the back of the hand, z the little-finger side of a right hand; a left hand is the right one mirrored.
+ */
+declare function createFirstPersonArms(THREE: Three, options?: FirstPersonArmsOptions): FirstPersonArms;
+
+type TwoBone = {
+    /** The middle joint (elbow, knee). */
+    joint: THREE_NS.Vector3;
+    /** The end of the second bone: the target when it is within reach, else the point on the way to it at full stretch. */
+    end: THREE_NS.Vector3;
+    /** The target was out of reach and `end` is short of it. */
+    clamped: boolean;
+    /** Scratch vectors the solver works in. */
+    line: THREE_NS.Vector3;
+    side: THREE_NS.Vector3;
+};
+/**
+ * Two-bone analytic IK. The first bone (`upper`) starts at `root`, the second (`lower`) ends at `end`; the middle joint bends toward `pole` (a direction, not a point: the part of it
+ * across the root-to-target line decides which way the elbow goes). A target nearer than the bones can fold, or farther than they can stretch, is clamped to the nearest reachable point on
+ * the same line. All vectors are in one space; `out` (made by `createTwoBone`) is filled and returned, so a frame allocates nothing.
+ */
+declare const solveTwoBone: (root: THREE_NS.Vector3, target: THREE_NS.Vector3, upper: number, lower: number, pole: THREE_NS.Vector3, out: TwoBone) => TwoBone;
+
+export { AVATAR_AREA_ID, type AreaContext, type AvatarEvent, type AvatarTestOptions, type AvatarUpdate, BAKE_NEUTRAL_POSE, BODY_CHUNK, BODY_MATERIAL_DEF, BODY_SOUNDS, type BakeBuilders, type BakeSpec, type BakedBody, type BestBuilder, type BestBuilderOptions, type BestTypeCard, type BloodAge, type BloodLook, type BloodLookOptions, type BloodSink, type BodyBatch, type BodyBatchOptions, type BodyChunkOptions, type BodyInstance, type BodyJoints, type BodyMaterialParams, type BodySoundRule, type BodyVariant, type BuildInstancedBodyParams, CHARACTERS_AREA_ID, CHARACTER_SOUNDS, CHARACTER_SOUND_BANK, type CharacterSound, type CharacterSoundOptions, type CharacterSoundSink, type CharacterSoundStyle, type CharactersTestOptions, EXTRAS, type EyeOptions, type Eyes, FACE_FEATURES, FIRST_PERSON_BOB, FIRST_PERSON_COLORS, FIRST_PERSON_RIG, FIRST_PERSON_STANCES, type FilmSink, type FirstPersonArms, type FirstPersonArmsOptions, type FirstPersonArmsState, type FirstPersonBob, type FirstPersonColors, type FirstPersonEvent, type FirstPersonRig, type FluidsBridge, type FluidsBridgeOptions, type FlyingLimb, type FlyingLimbs, type FlyingLimbsOptions, type FlyingPiece, type FlyingPieces, type FlyingPiecesOptions, HAND_ITEMS, HATS, HIT_PRESETS, type HitPreset, LOD_BAKE, LOD_BATCH_CAPACITY, LOD_CASTS_SHADOW, LOD_DISTANCES, LOD_SEGMENTS, type LimbEffects, type LimbLaunch, PENDULUM, PERSON_ITEM_PREFIX, PLAYER_SOUNDS, type Pendulum, type PersonBuilder, type PersonBuilderOptions, type PlayPoseOptions, type PlayerAvatar, type PlayerAvatarColors, type PlayerAvatarOptions, type PlayerAvatarSpec, type PoseTargets, type ProfessionCard, type RestPose, type RichRig, type RigAnimator, type RigAnimatorOptions, type RoomAvatarLike, type StanceDef, type Three, type ToRoomAvatarOptions, type TwoBone, UNDEAD_VOICES, UNDEAD_VOICE_GROUP, UNDEAD_VOICE_SOURCES, type UndeadCard, type UndeadLike, type UndeadVoice, type VariantType, type VoiceMoment, type VoiceStep, type WoundBody, type WoundMaterials, type WoundNode, type WoundSpray, type Wounds, type WoundsOptions, ZOMBIE_ITEM_PREFIX, bakeBody, bakeVariants, blobGeometry, blobRadii, bloodLookOfAge, buildInstancedBody, createAvatarTestModule, createBestBuilder, createBodyBatch, createBodyChunk, createBodyMaterial, createCharacterSound, createCharactersTestModule, createEye, createFirstPersonArms, createFluidsBridge, createFlyingLimbs, createFlyingPieces, createGlowTexture, createPendulum, createPersonBuilder, createPlayerAvatar, createRigAnimator, createVariantBatches, createWoundMaterials, createWounds, exitWound, explodeChunks, findEyes, gouge, jointsOf, lodAt, makeCut, makeStump, registerBodyMaterial, ringWound, solveTwoBone, starGeometry, stepPendulum, toRoomAvatar, woundBodyOf, woundDecal };