@adatechnology/game-characters-three 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -287,6 +287,8 @@ type RichRig = {
     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: {
@@ -1026,6 +1028,26 @@ declare const UNDEAD_VOICE_GROUP = "undead_voice";
 declare const CHARACTER_SOUNDS: readonly SoundRecipe[];
 declare const CHARACTER_SOUND_BANK: SoundBank;
 
+/**
+ * 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. */
@@ -1045,6 +1067,10 @@ type PlayerAvatarOptions = {
      * 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;
@@ -1053,6 +1079,8 @@ 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`). */
@@ -1076,6 +1104,21 @@ type AvatarUpdate = {
         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;
@@ -1098,11 +1141,26 @@ type PlayerAvatar = {
     /** 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;
 };
@@ -1138,6 +1196,17 @@ type FirstPersonRig = {
     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;
+    /**
+     * The elbow bend (radians, 0 straight) an arm keeps when its shoulder comes forward to a far hand, right then left: the shoulder stops short of a straight arm, so the
+     * elbow and the wrist read on screen. Leave it out to stretch the arm to its full length first.
+     */
+    reachBend?: readonly [number, number];
+    /**
+     * Holding a tool, the way from the wrist to the elbow (camera space, right arm then left; x right, y up, -z ahead): the elbow is put there, kept inside the view, and the shoulder
+     * behind it out of the view, so the bend of the arm shows on screen (a trigger elbow out to the side, a support elbow out under the forend). Leave it out to keep the
+     * shoulders fixed and bend the elbows toward `elbowPole`; null for one arm keeps that arm so (a support hand cups a handguard from below, its elbow under the view).
+     */
+    elbowView?: readonly [Triple | null, Triple | null];
     /** 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. */
@@ -1258,23 +1327,27 @@ type RoomAvatarLike = {
             readonly phase: 'grip' | 'push' | 'strain';
             readonly progress: number;
         } | null;
+        door?: {
+            readonly phase: 'reach' | 'swing' | 'release' | 'rattle';
+            readonly progress: number;
+            readonly height: number;
+            readonly pull: boolean;
+        } | null;
         holding?: boolean;
         itemUse?: AvatarItemUsePose | null;
+        seat?: {
+            readonly pose: 'sit' | 'lie';
+            readonly hip: number;
+        } | null;
     }): 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;
-    };
+    shoulder(side: 'R' | 'L'): THREE_NS.Object3D;
+    /** Where the body's eyes are after its pose (`RoomAvatar.eye`): the room draws the body in both views and puts the first-person camera there. */
+    eye(out?: THREE_NS.Vector3): THREE_NS.Vector3;
+    /** Hides the head and neck from `camera` in first person (`RoomAvatar.setView`). */
+    setView(mode: AvatarViewMode, camera: THREE_NS.Object3D | null): void;
+    /** Brings the body's hands to the tool in them, in both views; `view` keeps them in the first-person view (`RoomAvatar.reach`). */
+    reach(targets: HandTargets | null, view?: ReachView | 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';
@@ -1282,11 +1355,11 @@ type RoomAvatarLike = {
     }): 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')`). */
+    /** Separate first-person arms, only when `toRoomAvatar` was asked for them (`firstPerson`); the room draws the body in both views and does not use them. */
     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`). */
+    /** Separate first-person arms (the options of `createFirstPersonArms`, merged over the colours of the body and `firstPersonClips`); default none: the body is the first-person view. */
     firstPerson?: false | FirstPersonArmsOptions;
     /** The third-person strike clips `strike` finds by id. Default `ATTACK_CLIPS` of game-characters-people. */
     strikeClips?: readonly PoseClip[];
@@ -1301,8 +1374,8 @@ type ToRoomAvatarOptions = {
 };
 /**
  * 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
+ * counts a look up as positive, the team game's `view.pitch` (what `AvatarUpdate.pitch` reads) counts a look down as positive. The same body is the first-person view (`eye`, `setView`;
+ * separate arms only with `firstPerson`), and `strike(clipId)` plays the strike on the body (the attack clips) and answers the seconds to its
  * impact, which are the same in both views. A kick with the left leg (`leg: 'left'`) or a punch with the left hand (`hand: 'left'`) plays the mirror of the clip written for the right.
  * After a punch the body holds the guard (`guardClip`) for `guardHold` seconds while it stands, so the next punch leaves from the guard.
  */
@@ -1380,4 +1453,4 @@ type TwoBone = {
  */
 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 AvatarItemUsePose, 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, personSpecOf, registerBodyMaterial, ringWound, solveTwoBone, starGeometry, stepPendulum, toRoomAvatar, woundBodyOf, woundDecal };
+export { AVATAR_AREA_ID, type AreaContext, type AvatarEvent, type AvatarItemUsePose, type AvatarTestOptions, type AvatarUpdate, type AvatarViewMode, 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 ReachView, 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, personSpecOf, registerBodyMaterial, ringWound, solveTwoBone, starGeometry, stepPendulum, toRoomAvatar, woundBodyOf, woundDecal };