@adatechnology/game-characters-three 0.7.2 → 0.8.0

package/dist/testing-DyQw8dCw.d.ts

@@ -0,0 +1,606 @@
+import { Vec3, DestructionEvent, SoundRequest, TestableModule, HandTargets } from '@adatechnology/game-contracts';
+import * as THREE_NS from 'three';
+import { CascadeJoint, RestPose, StrideParams, GaitSample, lerpPose, GaitProfile, CharacterKit, CharacterPack, CharacterSpec, DamageCharacter, BodyHit, PoseClipEvent, PoseClip, PoseClipRegistry } from '@adatechnology/game-characters';
+
+/** The three.js namespace the host passes in: the package never imports three itself, so one script tag works. */
+type Three = typeof THREE_NS;
+
+type Euler3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+type Node3 = {
+    rotation: Euler3;
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/** A limb of the rich body, as the Bestiário builds it: the group at the joint, the one below it (elbow, knee) and the rest angles. */
+type RigArm = {
+    g: Node3;
+    el: Node3 & {
+        userData: Record<string, unknown>;
+    };
+    base: number;
+    eBase: number;
+};
+type RigLeg = {
+    g: Node3;
+    kn: Node3;
+    base: number;
+    kBase: number;
+    lost?: boolean;
+};
+/** What `RichBodyBuilder.build` leaves in `root.userData.rig` (the page's `rig`). */
+type RichRig = {
+    readonly type: string;
+    readonly fig: Node3;
+    readonly upper: Node3;
+    readonly headG: Node3;
+    /** The neck cylinder, taken by identity; absent when the head is cut off. */
+    readonly neck?: Node3;
+    readonly arms: RigArm[];
+    readonly legs: RigLeg[];
+    readonly dangles: {
+        g: Node3;
+        el: Node3;
+    }[];
+    readonly flaps: (Node3 & {
+        userData: Record<string, unknown>;
+    })[];
+    readonly ph: number;
+    readonly dropBase: number;
+    readonly leanBase: number;
+    readonly hxBase: number;
+    /** Cascade state, made on the first call of `cascade`. */
+    cur?: Map<readonly [Node3 | Euler3, string, CascadeJoint], number>;
+    jl?: (readonly [Node3 | Euler3, string, CascadeJoint])[];
+};
+/** The names a pose may set (the Bestiário's `setPose`). All are optional: a joint a pose does not name keeps what it had. */
+type PoseTargets = Partial<Record<'lean' | 'twist' | 'side' | 'drop' | 'headX' | 'headY' | 'headZ' | 'armR' | 'armL' | 'elbR' | 'elbL' | 'armRz' | 'armLz' | 'legL' | 'legR' | 'kneeL' | 'kneeR', number>>;
+type RigAnimatorOptions = {
+    /** Gait profile by the type name the rig carries (`rig.type`); a type that is not here walks like the first type of the Bestiário (the slow one). */
+    readonly gaits?: Readonly<Record<string, GaitProfile>>;
+    /** Cascade rates per joint. Default: the engine's `CASCADE`. */
+    readonly cascade?: Readonly<Record<CascadeJoint, number>>;
+};
+type RigAnimator = {
+    /** The pose the gait swings around (legs `lost` stay out of the swing). */
+    restOf(rig: RichRig): RestPose;
+    /** 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. */
+    animate(root: THREE_NS.Object3D, time: number, stride?: StrideParams): void;
+    /** Moves every joint a fraction toward the value the animation left on it, from the hips to the head (the Bestiário's `cascade`). */
+    cascade(rig: RichRig, dt: number): void;
+    setPose(rig: RichRig, targets: PoseTargets): void;
+    lerpPose: typeof lerpPose;
+};
+/**
+ * The rich body's animator: the Bestiário's `animate0`, `animate`, `cascade`, `setPose` and `lerpPose` over the rig the best builder leaves in
+ * `root.userData.rig`. The gait maths is the engine's (`animateProfile`, pure CPU); this only reads the rest pose off the rig and writes the result back.
+ */
+declare const createRigAnimator: (options?: RigAnimatorOptions) => RigAnimator;
+
+/** The part of a fluid world the bridge needs; `FluidWorld` from `@adatechnology/game-fluids` has it. The package does not import the fluids packages. */
+type BloodSink = {
+    splash(liquid: string, point: Vec3, liters: number, velocity?: Vec3): void;
+};
+/** Colours of one body's blood: the wet film and what it dries to (the infection age of a zombie: `ages.json`). */
+type BloodLook = {
+    /** Liquid of the blood in the fluid world and in the film (default: the bridge's `liquid`). An old body can bleed `old_blood`. */
+    readonly liquid?: string;
+    readonly tint?: {
+        readonly fresh: number;
+        readonly dry: number;
+    };
+    /** How much of the blood is left, 0 to 1 (the age's `blood` factor): it scales the drops thrown into the film, so a dried-out body throws none. Default 1. */
+    readonly amount?: number;
+};
+/** The part of an infection age the look needs (`UndeadAge` of `@adatechnology/game-characters-undead` has all of it). */
+type BloodAge = {
+    readonly id: string;
+    readonly blood: number;
+    readonly freshBloodColor: string;
+    readonly dryBloodColor: string;
+};
+type BloodLookOptions = {
+    /** Ages with a blood factor below this bleed `thinLiquid` (default 0.3: the old and the decrepit). */
+    readonly thinBelow?: number;
+    /** Liquid of the thin blood (default `old_blood`). */
+    readonly thinLiquid?: string;
+};
+/** The blood of an infection age: its fresh and dry colours (`ages.json`), its amount, and `old_blood` for the thin ones. */
+declare const bloodLookOfAge: (age: BloodAge, options?: BloodLookOptions) => BloodLook;
+/** A drop thrown into the running film of the liquids (`createFilmBridge(...)` of `@adatechnology/game-fluids-three` has it). The package does not import the fluids packages. */
+type FilmSink = {
+    splat(splat: {
+        fluid: string;
+        point: Vec3;
+        direction?: Vec3;
+        speed?: number;
+        radius?: number;
+        count?: number;
+        tint?: {
+            fresh: number;
+            dry: number;
+        };
+    }): number;
+};
+/** What a `wound` throws into the film: the drops, how fast and how big. Defaults 3 drops at 2.5 m/s of 3.2 mm. */
+type WoundSpray = {
+    readonly count?: number;
+    readonly speed?: number;
+    readonly radius?: number;
+};
+type FluidsBridgeOptions = {
+    readonly sink: BloodSink;
+    /** The running film: when given, a wound, a severed or destroyed segment and a split throw drops of blood into it, in the colours of the body's `BloodLook`. */
+    readonly film?: FilmSink;
+    /** Drops of a wound (`wound` change of a `body` event). */
+    readonly spray?: WoundSpray;
+    /** Drops thrown by a cut, a burst and a split (default 4, 7 and 10). */
+    readonly burstDrops?: Readonly<Record<'severed' | 'destroyed' | 'split', number>>;
+    /** Id of the blood in the fluid world. Default `blood`. */
+    readonly liquid?: string;
+    /** Metres per second a pressurised leak (a cut artery) throws its drops. Default 1.4. */
+    readonly spurtSpeed?: number;
+};
+type FluidsBridge = {
+    /** Reads a body's events: `leak` (bleeding) becomes blood on the surface below. Other events are ignored. */
+    handle(event: DestructionEvent): void;
+    /** The blood a cut, a burst or a split spills at once, at the world point the piece left from (and the drops it throws into the film, when there is one). */
+    burst(change: 'severed' | 'destroyed' | 'split', point: Vec3, look?: BloodLook, direction?: Vec3): void;
+    /** A wound that does not cut anything off (the `wound` change of the `body` event): drops of blood in the film, thrown along `direction` (default straight down). Returns how many found a grid. */
+    wound(point: Vec3, look?: BloodLook, direction?: Vec3): number;
+    /** Blood from the engine's own bleeders: `litersPerSecond` over `dt` seconds at `point`. */
+    bleed(point: Vec3, litersPerSecond: number, dt: number, direction?: Vec3, pressurized?: boolean): void;
+};
+/**
+ * Connects the wounds to the fluids packages, with the fluid world injected: the body keeps its own bleeders (rate, duration, spurt) and this turns them
+ * into blood, so the stains, pools and drying are the fluids' business and the character code draws none.
+ */
+declare const createFluidsBridge: ({ sink, film, spray, burstDrops, liquid, spurtSpeed }: FluidsBridgeOptions) => FluidsBridge;
+
+/** One sound of a voice: the recipe and, for a sequence, the seconds after the first. */
+type VoiceStep = {
+    readonly sound: string;
+    readonly delay?: number;
+};
+/**
+ * The voice of one undead type:
+ * - `origin` says where it comes from: `team` (the page has a sound for this very type), `rule` (the page's class rule applied to the type: the Brutamonte,
+ *   a chase speed above 3.4, or a walker) or `extra` (the nearest sound of the pages to the voice line of `types.json`, the kit's choice);
+ * - `groan` / `gameGroan` is the groan of the art scene and of the game;
+ * - `idle` (a body that wanders or chases) and `alert` (it noticed the player or woke up) default to the groan; `special` is what the type does at its
+ *   ability (the screamer's call, the leaper's jump), and `gameSpecial` its game version (the game has no leap sound, so the art scene's is kept).
+ */
+type UndeadVoice = {
+    readonly origin: 'team' | 'rule' | 'extra';
+    readonly groan: string;
+    readonly gameGroan: string;
+    readonly idle?: readonly VoiceStep[];
+    readonly alert?: readonly VoiceStep[];
+    readonly special?: readonly VoiceStep[];
+    readonly gameSpecial?: readonly VoiceStep[];
+};
+/** The voices of the 13 types of the Bestiario, by type id. */
+declare const UNDEAD_VOICES: Readonly<Record<string, UndeadVoice>>;
+declare const UNDEAD_VOICE_SOURCES: readonly string[];
+type VoiceMoment = 'idle' | 'alert' | 'special';
+type CharacterSoundStyle = 'art_scene' | 'game';
+/** What a change of a body sounds like, by the `change` of the `body` event. A head or a jaw hit is brighter (`flesh_head`). */
+type BodySoundRule = {
+    readonly sound: string;
+    readonly head?: string;
+};
+/** Art scene: bloodHit (cena L1084) is `flesh`, a cut is `sever` (L1127, L1143), a burst or an opened belly is `gore` (L1101, L1132). Game: the flesh class of `sfx`. */
+declare const BODY_SOUNDS: Readonly<Record<CharacterSoundStyle, Readonly<Record<string, BodySoundRule>>>>;
+/** What the player hears when a body grabs, bites or hurts him (cena L1350-L1352, at the listener). */
+declare const PLAYER_SOUNDS: {
+    readonly grab: "grab";
+    readonly bite: "bite";
+    readonly hurt: "hurt";
+};
+/** The part of the host's sound a body needs: `play`, and `register` to put the banks in its engine (`createAudioSink(...)` has both). */
+type CharacterSoundSink = {
+    play(request: SoundRequest): unknown;
+    register?(bank: unknown): void;
+};
+type CharacterSoundOptions = {
+    /** Which team answers (default `art_scene`, the kit mix). `game` plays the game's groans, scream and flesh, and the art scene for what the game lacks. */
+    readonly style?: CharacterSoundStyle;
+    /** Replaces a type's voice; `null` silences it. */
+    readonly voices?: Readonly<Record<string, UndeadVoice | null>>;
+    /** Replaces a `body` change's rule; `null` silences it. */
+    readonly body?: Readonly<Record<string, BodySoundRule | null>>;
+    /** The type used for an id that has no voice (default none: silent). */
+    readonly fallbackType?: string;
+};
+type CharacterSound = {
+    /** The steps a type plays at a moment. */
+    stepsOf(typeId: string, moment: VoiceMoment): readonly VoiceStep[];
+    /** Plays the voice of a type at a moment where the body is. Returns how many sounds were started or queued. */
+    voice(typeId: string, moment: VoiceMoment, position: Vec3, volume?: number): number;
+    /** Reads a `body` event of a body at `position`: a wound is flesh, a cut is `sever`, a burst or a split is `gore`. Other events are ignored. Returns true when a sound was asked for. */
+    body(event: DestructionEvent, position: Vec3, volume?: number): boolean;
+    /** The player is grabbed, bitten or hurt (heard at the listener). */
+    player(kind: keyof typeof PLAYER_SOUNDS, volume?: number): void;
+    /** Runs the sequences (the screamer's inhale, then the call): call it each frame. */
+    update(dt: number): void;
+    /** Sounds waiting for their time. */
+    readonly pending: () => number;
+    dispose(): void;
+};
+/**
+ * Plays the sounds of the bodies on the host's sound: the voices of the undead types (the Bestiario's 13), what a wound sounds like and what the player
+ * hears. The banks are registered in the host's engine, the sounds are positional, and the groans go through the engine's `undead_voice` limiter
+ * (five at once, one every 0.25 s, nearer than 40 m). The team sounds are the recipes of `./recipes`; the table of who says what is data.
+ */
+declare function createCharacterSound(sink: CharacterSoundSink, options?: CharacterSoundOptions): CharacterSound;
+
+/** A crowd on the instanced path: variants baked on demand from the rich builder, one batch per variant and level of detail, members walking a field. */
+type Crowd = {
+    readonly group: THREE_NS.Group;
+    spawn(count: number): void;
+    clear(): void;
+    update(dt: number, camera: THREE_NS.Camera): void;
+    readonly count: number;
+    readonly bakeMs: number;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    /** Triangles of one body at each level of detail (the budget the benchmark checks). */
+    trianglesPerLevel(typeId: string): readonly number[];
+};
+
+/** One undead type as the area needs it: the content pack's own record has all of these fields. */
+type UndeadCard = {
+    readonly id: string;
+    readonly name: Readonly<Record<string, string>>;
+    readonly eye: {
+        readonly color: string;
+    };
+    readonly gait: Readonly<Record<string, number | boolean>>;
+};
+/** A profession of the people pack (look, accessories, what it holds). */
+type ProfessionCard = {
+    readonly id: string;
+    readonly name: Readonly<Record<string, string>>;
+    readonly female?: boolean;
+    readonly look: {
+        readonly skin: string;
+        readonly hair: {
+            readonly style: string;
+            readonly color: string;
+        };
+        readonly hat?: {
+            readonly kind: string;
+            readonly color: string;
+        };
+        readonly face?: readonly string[];
+        readonly top: {
+            readonly color: string;
+            readonly sleeve: string;
+            readonly plaid?: string;
+        };
+        readonly pants: {
+            readonly color: string;
+        };
+        readonly shoes: string;
+    };
+    readonly accessories: readonly {
+        readonly id: string;
+        readonly color?: string;
+    }[];
+    readonly hand?: string;
+    readonly leftHand?: string;
+};
+/** The part of the undead engine the area uses (`createUndead(kit)` has all of it). */
+type UndeadLike = {
+    create(spec: Pick<CharacterSpec, 'seed'> & Partial<CharacterSpec>, options?: {
+        readonly type?: string;
+    }): DamageCharacter;
+    turn(person: DamageCharacter, options?: {
+        readonly type?: string;
+    }): DamageCharacter;
+    traitsOf(character: DamageCharacter): {
+        readonly type: string;
+        readonly age?: string;
+        readonly speeds: Readonly<Record<string, number>>;
+    } | undefined;
+    speedFor(traits: {
+        readonly type: string;
+        readonly speeds: Readonly<Record<string, number>>;
+    }, context: {
+        readonly moment: string;
+        readonly limp?: boolean;
+        readonly crawling?: boolean;
+    }): number;
+    onDeath?(character: DamageCharacter): readonly {
+        readonly kind: string;
+    }[];
+    infect?(wound: 'bite' | 'scratch' | 'laceration' | undefined, random: () => number): {
+        advance(seconds: number): unknown;
+        readonly reanimated: boolean;
+    } | undefined;
+};
+type CharactersTestOptions = {
+    /** `en` or `pt-BR` (default). */
+    readonly locale?: string;
+    /** Builds the kit the area uses; called again when the bench changes the penetration model or the death rule. Default `createCharacters` with `packs`. */
+    readonly createKit?: (options: {
+        readonly penetration: 'physical' | 'team-game';
+        readonly deathRule: 'vitality-or-head' | 'head-only';
+    }) => CharacterKit;
+    /** Packs for the default kit (people, uniformed, undead). */
+    readonly packs?: readonly CharacterPack[];
+    readonly undeadTypes?: readonly UndeadCard[];
+    readonly createUndead?: (kit: CharacterKit) => UndeadLike;
+    readonly professions?: readonly ProfessionCard[];
+    /** Where the blood of the wounds goes (the room's fluid world: `room.fluids`). Without it the wounds draw no blood on the ground. */
+    readonly fluids?: BloodSink;
+    /** The running film of the liquids (the room's `room.film`): wounds throw drops of blood into it, in the colours `bloodOf` gives. Without it only the fluid world gets blood. */
+    readonly film?: FilmSink;
+    /** The sounds of the bodies on the room's engine (`host.audio`): wounds, cuts and the voices of the bench. `false` leaves the area silent. */
+    readonly sound?: false | CharacterSoundOptions;
+    /** The blood of a body by its infection age (`bloodLookOfAge` over the content's ages). Bodies without an age, and games without this option, bleed the liquid's own colours. */
+    readonly bloodOf?: (age: string) => BloodLook | undefined;
+    /** Seed of the draws of the area (default 1). */
+    readonly seed?: number;
+    /** Crowd types to bake for the instanced field, by undead id (default walker and runner). */
+    readonly crowdTypes?: readonly string[];
+    /** Triangles a baked body may have at each level of detail (default 2500, 800, 250, the Bancada de Hordas budget). Given explicitly, every level is a hard check. */
+    readonly triangleBudget?: readonly number[];
+};
+
+/** What a scenario needs of the room: the pass/fail line and time. The test room's `ScenarioContext` has both. */
+type AreaContext = {
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+    step(seconds: number): void;
+};
+
+declare const CHARACTERS_AREA_ID = "characters_area";
+declare const ZOMBIE_ITEM_PREFIX = "zombie_";
+declare const PERSON_ITEM_PREFIX = "person_";
+/**
+ * The characters test area as a `TestableModule`: the undead types and the professions as bodies the room can shoot (each one a `DestructibleImpl` of the damage model, drawn with the
+ * rich builders, wounds, eyes and gait), a shooting lane, a crowd on the instanced path, and a bench with the damage rules, the hits, the protection, the moment and the layers.
+ * Everything comes in by option: the packs of content (people, undead) are the host page's, so this package knows no game.
+ */
+declare function createCharactersTestModule(options?: CharactersTestOptions): TestableModule<AreaContext> & {
+    readonly entries: ReadonlyMap<string, unknown>;
+    readonly crowd: Crowd | null;
+};
+
+/**
+ * What the "Hit" control of the bench does to the body: typical loads, in joules and millimetres, as the arsenal's calibre table gives them.
+ * `caliberId` is used only when the kit's table knows it (the `team-game` model).
+ */
+type HitPreset = {
+    readonly id: string;
+    readonly hit: Omit<BodyHit, 'point' | 'direction'>;
+    readonly range?: number;
+};
+declare const HIT_PRESETS: readonly HitPreset[];
+
+/**
+ * The material the parts of a living body carry (`BODY_MATERIAL` of the engine), as a destruction world needs it declared: pass it in the world's material list
+ * (`worldOptions.materials` of the test room) before loading the characters area. The body model owns the damage; the world only needs the density and thermal data
+ * to raycast, blast and burn a body like any other object. Numbers are those of soft tissue (about 1050 kg/m3).
+ */
+declare const BODY_MATERIAL_DEF: {
+    readonly id: "flesh";
+    readonly density: 1050;
+    readonly hpPerKg: 15;
+    readonly penetration: 1.2;
+    readonly ductility: 0.8;
+    readonly fracture: "tear";
+    readonly fragmentSize: readonly [0.03, 0.1];
+    readonly damageScale: {
+        readonly slash: 1.6;
+    };
+    readonly hitDebris: "drips";
+    readonly breakDebris: "drips";
+    readonly thermal: {
+        readonly ignitionC: 260;
+        readonly flameC: 700;
+        readonly fuelFraction: 0.25;
+        readonly burnRate: 0.004;
+        readonly conductivity: 0.5;
+        readonly heatCapacity: 3.5;
+        readonly smoke: "grey";
+    };
+    readonly tags: readonly ["organic", "body"];
+    readonly compressive: 1000;
+};
+/** Puts the body material in a destruction world that does not know it yet (`room.world`); a world that has it is left alone. Call it before `room.loadModule`. */
+declare const registerBodyMaterial: (world: {
+    readonly materials: Map<string, unknown>;
+}) => void;
+
+/** The person builder's spec for a profession of the people pack (look and gear as numbers; the builder draws the rest). */
+declare const personSpecOf: (profession: ProfessionCard) => Record<string, any>;
+
+/**
+ * The eye the hands are seen from, given per call to `apply` (null or none is the body seen from outside: nothing changes). `reachBend` keeps the elbow bent where a hand is out of reach, the hand stopping
+ * short instead of the arm locking; `keepOutside` pulls a hand back so it stays in front of the surface `contact` finds along the camera's forward.
+ */
+type ReachView = {
+    readonly camera: THREE_NS.Object3D;
+    /** The least interior bend of the elbow, radians, right then left. Default `ARM_REACH.viewBend`. */
+    readonly reachBend?: readonly [number, number];
+    readonly keepOutside?: {
+        /** The distance to the surface from `origin` along `direction` within `maxDistance`, or null. */
+        contact(origin: [number, number, number], direction: [number, number, number], maxDistance: number): number | null;
+        /** Default `ARM_REACH.contactMargin`. */
+        readonly margin?: number;
+        /** Default `ARM_REACH.contactNearest`. */
+        readonly nearest?: number;
+    };
+};
+
+type AvatarViewMode = 'first' | 'third';
+
+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;
+    /**
+     * How many times faster the cascade follows while a clip that does not loop plays: a strike is over in a third of a second, and at the walk's pace the joints would
+     * still be on their way when it ends (a punch that never reaches the shoulder). 1 keeps the walk's pace. Default 5.
+     */
+    readonly clipCascade?: number;
+    /** Where the eye sits against the builder's eye point, in the head's frame (so it follows the head's scale and turn). Default [0, -0.068, 0]: about 1.70 m standing. */
+    readonly eyeOffset?: readonly [number, number, number];
+    /** How much of the walking and running bob of the body reaches the eye: 0 none, 1 all of it. Default 0.5. */
+    readonly eyeBob?: number;
+};
+type AvatarEvent = PoseClipEvent & {
+    clip: string;
+};
+type AvatarItemUsePose = {
+    readonly id: string;
+    readonly position: readonly [number, number, number];
+    readonly rotation: readonly [number, number, number];
+    /** How closed the other hand is (0 open to 1 closed) when it works on the item, as a hand turning a cap off opens between strokes; the room brings it there with `reach`. */
+    readonly gripL?: number;
+};
+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;
+    /** Whether the player is carrying an item in the right hand. */
+    holding?: boolean;
+    /** Active scripted item use (`drink`, `sip`, `chug`, `pour`, `open`, `close`, `tilt`). */
+    itemUse?: AvatarItemUsePose | null;
+    /** Hands on a piece of furniture: `grip` closes on it with `progress`, `push` walks with it, `strain` strains against what does not give. */
+    push?: {
+        readonly phase: 'grip' | 'push' | 'strain';
+        readonly progress: number;
+    } | null;
+    /** On a seat: `sit` folds the legs under hips `hip` metres above the feet, `lie` lays the body face up with the pelvis there, the head behind the facing. */
+    seat?: {
+        readonly pose: 'sit' | 'lie';
+        readonly hip: number;
+    } | null;
+    /**
+     * A hand on a door, lid or drawer: `reach` to the handle, `swing` with it (`pull` toward the body or pushed away), `release` back, `rattle` on a locked one.
+     * `height` is the hand over the feet, metres (a fridge handle, a car door, a low drawer).
+     */
+    door?: {
+        readonly phase: 'reach' | 'swing' | 'release' | 'rattle';
+        readonly progress: number;
+        readonly height: number;
+        readonly pull: boolean;
+    } | null;
+};
+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;
+    /**
+     * The world position of the eyes, as `update` left them: sampled at its end, before any `reach()` (which turns the chest and would swing the head), and kept in the
+     * body's own frame so it stays right when the host moves `root` afterwards. With `out` it fills that vector instead of making one.
+     */
+    eye(out?: THREE_NS.Vector3): THREE_NS.Vector3;
+    /** In 'first' with a camera, the head and neck are not drawn for that camera only (shadows, mirrors and every other camera still see them); 'third' draws them. */
+    setView(mode: AvatarViewMode, camera: THREE_NS.Object3D | null): 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;
+    /** The joint of a shoulder ('R' the weapon side, at -x): where a long gun's stock rests, just inside it. */
+    shoulder(side: 'R' | 'L'): THREE_NS.Object3D;
+    /**
+     * Brings the hands to where the tool in them asks (`HandTargets`, world space) after `update`: shoulder, elbow and wrist each bend inside the human range, the chest turns and the shoulder
+     * blade slides toward a hand out of reach. Null, a strike playing or the body going down leave the arms as `update` posed them. Call it after the tool is placed and the root moved.
+     * `view` (given on each call, as the camera moves) is for the body seen from its own eyes: the elbows keep their bend and the hands stay out of walls; without it nothing changes.
+     */
+    reach(targets: HandTargets | null, view?: ReachView | null): void;
+    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;
+
+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;
+    };
+};
+
+export { createPlayerAvatar as $, type AvatarItemUsePose as A, type BloodLook as B, type CharacterSound as C, type PlayerAvatarSpec as D, type PoseTargets as E, type FluidsBridge as F, type ProfessionCard as G, HIT_PRESETS as H, type RigAnimator as I, type RigAnimatorOptions as J, UNDEAD_VOICE_SOURCES as K, type UndeadCard as L, type UndeadLike as M, type UndeadVoice as N, type VoiceStep as O, type PlayerAvatar as P, bloodLookOfAge as Q, type RichRig as R, createAvatarTestModule as S, type Three as T, UNDEAD_VOICES as U, type VoiceMoment as V, type WoundSpray as W, createCharacterSound as X, createCharactersTestModule as Y, ZOMBIE_ITEM_PREFIX as Z, createFluidsBridge as _, type AvatarViewMode as a, createRigAnimator as a0, personSpecOf as a1, registerBodyMaterial as a2, type ReachView as b, AVATAR_AREA_ID as c, type AreaContext as d, type AvatarEvent as e, type AvatarTestOptions as f, type AvatarUpdate as g, BODY_MATERIAL_DEF as h, BODY_SOUNDS as i, type BloodAge as j, type BloodLookOptions as k, type BloodSink as l, type BodySoundRule as m, CHARACTERS_AREA_ID as n, type CharacterSoundOptions as o, type CharacterSoundSink as p, type CharacterSoundStyle as q, type CharactersTestOptions as r, type FilmSink as s, type FluidsBridgeOptions as t, type HitPreset as u, PERSON_ITEM_PREFIX as v, PLAYER_SOUNDS as w, type PlayPoseOptions as x, type PlayerAvatarColors as y, type PlayerAvatarOptions as z };

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+export { c as AVATAR_AREA_ID, d as AreaContext, f as AvatarTestOptions, h as BODY_MATERIAL_DEF, n as CHARACTERS_AREA_ID, r as CharactersTestOptions, H as HIT_PRESETS, u as HitPreset, v as PERSON_ITEM_PREFIX, G as ProfessionCard, L as UndeadCard, M as UndeadLike, Z as ZOMBIE_ITEM_PREFIX, S as createAvatarTestModule, Y as createCharactersTestModule, a1 as personSpecOf, a2 as registerBodyMaterial } from './testing-DyQw8dCw.js';
+import '@adatechnology/game-contracts';
+import 'three';
+import '@adatechnology/game-characters';

package/dist/testing.js

@@ -0,0 +1,25 @@
+import {
+  AVATAR_AREA_ID,
+  BODY_MATERIAL_DEF,
+  CHARACTERS_AREA_ID,
+  HIT_PRESETS,
+  PERSON_ITEM_PREFIX,
+  ZOMBIE_ITEM_PREFIX,
+  createAvatarTestModule,
+  createCharactersTestModule,
+  personSpecOf,
+  registerBodyMaterial
+} from "./chunk-3CHBEUHW.js";
+export {
+  AVATAR_AREA_ID,
+  BODY_MATERIAL_DEF,
+  CHARACTERS_AREA_ID,
+  HIT_PRESETS,
+  PERSON_ITEM_PREFIX,
+  ZOMBIE_ITEM_PREFIX,
+  createAvatarTestModule,
+  createCharactersTestModule,
+  personSpecOf,
+  registerBodyMaterial
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}