@adatechnology/game-characters-three 0.7.0 → 0.7.1

package/README.md

@@ -48,7 +48,7 @@ down turns the body about the hip (`±1.5` rad, face up or down by the phase) wi
 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). `strike(clip, { leg: 'left' })` kicks with the left leg and `strike(clip, { hand: 'left' })` punches with the left hand: the mirror of the clip on the body (`mirrorPoseClip`, id `<clip>_left`) and on the arms. After a punch (an `impact` of kind `punch`) the body holds the guard (`guardClip`, default `'fight_guard'`, `false` for none) for
+`toRoomAvatar` also gives the room `strike(clipId)`, which plays the attack clip on the body (the only source of a strike, first and third person) and answers the seconds to the impact read from that clip (the same in both views). `strike(clip, { leg: 'left' })` kicks with the left leg and `strike(clip, { hand: 'left' })` punches with the left hand: the mirror of the clip on the body (`mirrorPoseClip`, id `<clip>_left`). After a punch (an `impact` of kind `punch`) the body holds the guard (`guardClip`, default `'fight_guard'`, `false` for none) for
 `guardHold` seconds (default 1.2) while it stands still, so a combo goes guard, punch, guard; the punch blends in over `punchBlend` (default 0.05 s). Walking, running, a weapon or a held item drop the guard.
 
 **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 and `arms.play('punch_right', { hand: 'left' })` punches with the left hand (the hands of the clip in a mirror). Hand frame: x wrist to knuckles, y back of the hand, z little-finger side; a left hand is the right one mirrored.

package/dist/index.d.ts

@@ -1170,6 +1170,104 @@ type PlayerAvatar = {
  */
 declare const createPlayerAvatar: (THREE: Three, options?: PlayerAvatarOptions) => PlayerAvatar;
 
+/** 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;
+        push?: {
+            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;
+    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 (the only source of it, in both views) and answers the seconds to its impact (`RoomAvatar.strike`). */
+    strike(clipId: string, options?: {
+        leg?: 'left' | 'right';
+        hand?: 'left' | 'right';
+    }): number | null;
+    /** The avatar it wraps. */
+    readonly avatar: PlayerAvatar;
+};
+type ToRoomAvatarOptions = {
+    /** The third-person strike clips `strike` finds by id. Default `ATTACK_CLIPS` of game-characters-people. */
+    strikeClips?: readonly PoseClip[];
+    /** The looping clip the body holds between punches (a clip of `strikeClips`), so a combo goes guard, punch, guard instead of dropping the hands each time; `false` for none. Default `'fight_guard'`. */
+    guardClip?: string | false;
+    /** Seconds the guard stays up after a punch ends. Default 1.2. */
+    guardHold?: number;
+    /** Seconds a punch takes to blend in over the walk (or the guard it comes from). Default 0.05: the fist leaves at once. */
+    punchBlend?: number;
+};
+/**
+ * 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. The same body is the first-person view (`eye`, `setView`), 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.
+ */
+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;
+    };
+};
+
 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:
@@ -1313,111 +1411,6 @@ type FirstPersonArms = {
     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;
-        push?: {
-            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;
-    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';
-        hand?: 'left' | 'right';
-    }): number | null;
-    /** The avatar it wraps. */
-    readonly avatar: PlayerAvatar;
-    /** 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 = {
-    /** 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[];
-    /** The first-person clips the arms play. Default `FIRST_PERSON_CLIPS` of game-characters-people. */
-    firstPersonClips?: readonly FirstPersonClip[];
-    /** The looping clip the body holds between punches (a clip of `strikeClips`), so a combo goes guard, punch, guard instead of dropping the hands each time; `false` for none. Default `'fight_guard'`. */
-    guardClip?: string | false;
-    /** Seconds the guard stays up after a punch ends. Default 1.2. */
-    guardHold?: number;
-    /** Seconds a punch takes to blend in over the walk (or the guard it comes from). Default 0.05: the fist leaves at once. */
-    punchBlend?: number;
-};
-/**
- * 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. 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.
- */
-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. */