@adatechnology/game-characters 0.1.6 → 0.2.1

package/README.md

@@ -17,3 +17,31 @@ person.lastHit // { points, killed, headshot, through, exitEnergy }
 ```
 
 Plain script: `dist/index.global.js` exposes the `GameCharacters` global.
+
+## Pose clips
+
+Keyframed poses over the joint names of the rich body (`lean`, `twist`, `side`, `drop`, `headX/Y/Z`, `armR/L`, `elbR/L`, `armRz/Lz`, `legL/R`, `kneeL/R`). `samplePoseClip(clip, t)` is
+the Bestiário's `sample` (find the segment, clamp, smoothstep, `lerpPose`); `clipEventsBetween(clip, t0, t1)` gives the events crossed in `(t0, t1]` (`impact` for "the blow lands
+now", `phase` with a locale key). `channels` says what a clip drives: `full`, `upper` (the legs keep walking) or `lower`. `POSE_CLIPS` has the two clips of the "grab and bite"
+scene (`grabbed_bitten_human`, `grab_bite_zombie`, with `x` and `run` as extra channels), texts in `POSE_CLIP_LOCALES` (`pt-BR`, `en`). A game adds or replaces clips with
+`createPoseClipRegistry(POSE_CLIPS).register(clip)`.
+
+```ts
+import { POSE_CLIPS, createPoseClipRegistry, samplePoseClip } from '@adatechnology/game-characters'
+
+const clips = createPoseClipRegistry(POSE_CLIPS)
+samplePoseClip(clips.get('grabbed_bitten_human')!, 2.5) // { lean, headY, armL, ... }
+```
+
+**Clip format (JSON).** A team can add clips, attacks included, as data and register them; the core has no clip of its own beyond the two Bestiário ones.
+
+```json
+{
+  "id": "my_clip", "duration": 1.2, "loop": false, "channels": "upper",
+  "keys": [{ "t": 0, "pose": { "armR": -0.1 } }, { "t": 0.4, "pose": { "armR": -1.6, "lean": 0.3 } }, { "t": 1.2, "pose": { "armR": -0.1 } }],
+  "events": [{ "t": 0.4, "type": "impact", "data": { "kind": "blow" } }]
+}
+```
+
+Event types: `impact` is the moment the blow, bite or hit lands (the game applies the damage when it fires); `phase` carries `data.label`, a locale key. Any other type is the game's.
+`clipEventsBetween` returns an event once, for the interval it falls in `(t0, t1]`.

package/dist/index.d.ts

@@ -139,6 +139,8 @@ type BlastRules = {
     readonly headDestroyPoints: number;
     /** A blast this strong on a segment destroys it when it reaches 0. */
     readonly bigPoints: number;
+    /** Most points a segment takes in the injury zone of a blast with a `lethalRadius` (between the lethal radius and `radius`); default 15, which leaves a person just past the lethal radius badly hurt and one at the middle of the zone with about a third of the vitality gone. */
+    readonly injuryPoints?: number;
 };
 type DeathRule = 'vitality-or-head' | 'head-only';
 type SegmentRuleId = 'kit' | 'arsenal' | 'elenco';
@@ -1102,4 +1104,101 @@ type ProtectParams = {
 /** A stopped projectile does the layer's `blunt` share; one that goes through, `pass` (default `blunt`). Non-projectiles ignore ballistic layers. */
 declare const protect: ({ layers, projectile, model }: ProtectParams) => ProtectionOutcome;
 
-export { ARSENAL_RULES, type AgeGroup, type AnimateProfileParams, palette as AppearancePalette, type AppearanceParams, type AppearanceTraits, BLOOD_LITERS_PER_DROP, BLOOD_SEED_OFFSET, BODY_MATERIAL, BODY_REGIONS, type BallisticClass, type BlastRules, type Bleeder, type BodyHit, type BodyMultipliers, type BodySpec, type BodyVariance, type BuildClass, CASCADE, CRAWL_TILT_RATE, type CaliberEntry, type CascadeJoint, type Character, type CharacterKit, type CharacterPack, type CharacterPreset, type CharacterSpec, type CharactersOptions, type ConditionOptions, type ConditionPhase, type ConditionSample, type ConditionTimeline, type CorpseEntry, type CorpseLedger, type CorpseOptions, type CrawlPose, type CreateRigParams, DAMAGE_PRESETS, DEAD_TILT_RATE, DEFAULT_CORPSES, DEFAULT_DAMAGE_RULES, type DamageCharacter, type DamageOptions, type DamageRules, type DeadPose, type DeathRule, type Detail, type DrawnAppearance, ELENCO_RULES, GAME_BONES, GUIDE, type GaitProfile, type GaitSample, type HairStyle, type HitReport, type HumanArm, type HumanPose, type HumanPoseParams, INSTANCE_POSES, type InstancePose, JOINT_IDS, JOINT_PARENTS, type JointAngles, type JointId, LAYERED_PROTECTION_CAP, LIMB_REGIONS, LIMP, type LegAngles, type LimbRegion, type LineHit, type LineResult, type LineShot, type LineTarget, MOVES, MOVE_BLEND_RATE, type MoveBlend, type MoveId, type OutfitLook, PENETRATION_MODELS, PERSON_PRESET, PHYSICAL_PENETRATION, PROTECTION_PRESETS, type PenetrateLineParams, type PenetrationModel, type ProjectileInfo, type ProtectionLayer, type ProtectionOutcome, REGION_HIT_POINTS, REGION_SEGMENTS, type ResolvedCharacterSpec, type RestPose, type Rig, SEGMENT_IDS, SEGMENT_NUMBERS, SEGMENT_TREE, type SegmentId, type SegmentNode, type SegmentNumbers, type SegmentRuleId, type SegmentSide, type SegmentState, type SegmentStatus, type SeverityRules, type Stride, type StrideParams, TEAM_GAME, TEAM_GAME_CALIBERS, TEAM_GAME_CALIBER_KEYS, TEAM_GAME_PENETRATION, TORSO_RESISTANCE, type VarianceScale, animateProfile, applyPatches, applyPreset, bleedRateAt, blendMoves, crawlPose, createBloodStream, createBodySpec, createCharacters, createConditionTimeline, createCorpseLedger, createRig, createRng, cutOf, deadPose, decodePoseHeight, describeBody, drawAppearance, drawBodyVariance, emptySample, encodePoseHeight, energyKept, humanPose, isBodyRegion, isSegmentId, layeredProtection, layersOn, lerpPose, mergeById, moveBlendOf, penetrateLine, penetrationForce, pointsFromEnergy, projectileOf, protect, removeIds, resolveDamageRules, resolvePoints, segmentNode, segmentResistance, segmentsBelow, spreadPoints, stepCascade, strideFor, teamGameCost, teamGameFalloff, variantCountFor, variantDecay, variantSeed, walkCadence, walkGait };
+/** One key of a clip: the time in seconds and the joint targets by name (the names of the rich body's `setPose`; a clip may add channels of its own, such as `x` or `run`). */
+type PoseKey = {
+    t: number;
+    pose: Record<string, number>;
+};
+/** What a clip says happens at a time: `impact` ("the blow lands now"), `phase` (a label for the screen), or any type a game defines. */
+type PoseClipEvent = {
+    t: number;
+    type: string;
+    data?: Record<string, unknown>;
+};
+/** Which joints a clip drives: `upper` leaves the legs to the gait, `lower` leaves the trunk, head and arms, `full` sets everything. */
+type PoseClipChannels = 'full' | 'upper' | 'lower';
+type PoseClip = {
+    id: string;
+    duration: number;
+    loop?: boolean;
+    keys: PoseKey[];
+    events?: PoseClipEvent[];
+    channels?: PoseClipChannels;
+    /** Where the clip was ported from (file and variable), for the diff against the team page. */
+    source?: Record<string, unknown>;
+};
+/**
+ * The Bestiário's `sample(K, t)`: finds the segment of two keys, clamps the fraction to [0, 1], eases it with smoothstep `k·k·(3 − 2k)` and
+ * blends the two poses by joint name (`lerpPose`). Before the first key it holds the first segment's start, after the last it holds the end.
+ */
+declare const samplePoseClip: (clip: Pick<PoseClip, "keys">, time: number) => Record<string, number>;
+/** The events a clip fires while the clock goes from `from` (excluded) to `to` (included), in time order. */
+declare const clipEventsBetween: (clip: Pick<PoseClip, "events">, from: number, to: number) => PoseClipEvent[];
+/** The names of the joints a channel set drives, from the names `PoseTargets` of the rich animator knows. */
+declare const POSE_CHANNEL_JOINTS: Readonly<Record<PoseClipChannels, readonly string[] | undefined>>;
+/** Keeps from a sampled pose only the joints of the channel set (`full` keeps everything, including extra channels such as `x`). */
+declare const filterPoseChannels: (pose: Record<string, number>, channels?: PoseClipChannels) => Record<string, number>;
+/** The clip as seen in a mirror: left and right swap and the sideways channels change sign; the times, the events and the duration stay, so the impact falls at the same second. */
+declare const mirrorPoseClip: (clip: PoseClip, id: string) => PoseClip;
+
+type PoseClipRegistry = {
+    /** Adds a clip, or replaces the one with the same id. Returns the registry. */
+    register(clip: PoseClip): PoseClipRegistry;
+    get(id: string): PoseClip | undefined;
+    list(): PoseClip[];
+    remove(id: string): boolean;
+};
+/** A registry of clips by id: games add or replace clips without touching the core. */
+declare const createPoseClipRegistry: (initial?: readonly PoseClip[]) => PoseClipRegistry;
+/** The clips ported from the Bestiário "grab and bite" scene (human and zombie). Phase labels are locale keys, see `POSE_CLIP_LOCALES`. */
+declare const POSE_CLIPS: readonly PoseClip[];
+/** Texts of the phase labels by locale (`pt-BR` is the team's text). */
+declare const POSE_CLIP_LOCALES: Readonly<Record<string, Readonly<Record<string, string>>>>;
+
+type Triple = [number, number, number];
+/**
+ * A hand or a foot in the camera's space (x to the right, y up, the view looks down -z), in metres and radians. `p` is the middle of the palm (the ankle for a foot) and `r` the Euler angles
+ * (order XYZ) of its frame: x from the wrist to the knuckles (from the heel to the toes), y the back of the hand (the top of the foot), z the rest of the right-handed frame; a left hand is the
+ * mirror image of a right one, so the same numbers describe the same grip.
+ */
+type FirstPersonPoseKey = {
+    p: Triple;
+    r: Triple;
+    /** How closed the fingers are, 0 open to 1 closed; left out, the fingers keep what the stance has. */
+    grip?: number;
+    /** How much of the clip replaces what the hand is doing otherwise (holding a weapon, the stance), 0 none to 1 all. Default 1. */
+    w?: number;
+};
+/** One key: at `t` seconds the right hand (`R`), the left hand (`L`, or `'mirror'` for the mirror image of the right) and the right foot (`F`) are where the entries say. A side without an entry here is not driven by this key. */
+type FirstPersonKey = {
+    t: number;
+    R?: FirstPersonPoseKey;
+    L?: FirstPersonPoseKey | 'mirror';
+    F?: FirstPersonPoseKey;
+};
+/** A first-person animation of the hands and the foot: the counterpart of a third-person `PoseClip`, with the same events. */
+type FirstPersonClip = {
+    id: string;
+    duration: number;
+    keys: FirstPersonKey[];
+    events?: PoseClipEvent[];
+    /** Where the clip was ported from, or who authored it. */
+    source?: Record<string, unknown>;
+};
+/** What a channel does at a time. `mirror` says the numbers are the right hand's and the left hand is their mirror image. */
+type FirstPersonSampleChannel = {
+    p: Triple;
+    r: Triple;
+    grip: number | undefined;
+    w: number;
+    mirror: boolean;
+};
+type FirstPersonSample = {
+    R?: FirstPersonSampleChannel;
+    L?: FirstPersonSampleChannel;
+    F?: FirstPersonSampleChannel;
+};
+/** Where each driven channel is at `time`: between two keys of a channel the numbers are blended with the smoothstep of `samplePoseClip`; before its first key and after its last it holds them. */
+declare const sampleFirstPersonClip: (clip: Pick<FirstPersonClip, "keys">, time: number) => FirstPersonSample;
+
+export { ARSENAL_RULES, type AgeGroup, type AnimateProfileParams, palette as AppearancePalette, type AppearanceParams, type AppearanceTraits, BLOOD_LITERS_PER_DROP, BLOOD_SEED_OFFSET, BODY_MATERIAL, BODY_REGIONS, type BallisticClass, type BlastRules, type Bleeder, type BodyHit, type BodyMultipliers, type BodySpec, type BodyVariance, type BuildClass, CASCADE, CRAWL_TILT_RATE, type CaliberEntry, type CascadeJoint, type Character, type CharacterKit, type CharacterPack, type CharacterPreset, type CharacterSpec, type CharactersOptions, type ConditionOptions, type ConditionPhase, type ConditionSample, type ConditionTimeline, type CorpseEntry, type CorpseLedger, type CorpseOptions, type CrawlPose, type CreateRigParams, DAMAGE_PRESETS, DEAD_TILT_RATE, DEFAULT_CORPSES, DEFAULT_DAMAGE_RULES, type DamageCharacter, type DamageOptions, type DamageRules, type DeadPose, type DeathRule, type Detail, type DrawnAppearance, ELENCO_RULES, type FirstPersonClip, type FirstPersonKey, type FirstPersonPoseKey, type FirstPersonSample, type FirstPersonSampleChannel, GAME_BONES, GUIDE, type GaitProfile, type GaitSample, type HairStyle, type HitReport, type HumanArm, type HumanPose, type HumanPoseParams, INSTANCE_POSES, type InstancePose, JOINT_IDS, JOINT_PARENTS, type JointAngles, type JointId, LAYERED_PROTECTION_CAP, LIMB_REGIONS, LIMP, type LegAngles, type LimbRegion, type LineHit, type LineResult, type LineShot, type LineTarget, MOVES, MOVE_BLEND_RATE, type MoveBlend, type MoveId, type OutfitLook, PENETRATION_MODELS, PERSON_PRESET, PHYSICAL_PENETRATION, POSE_CHANNEL_JOINTS, POSE_CLIPS, POSE_CLIP_LOCALES, PROTECTION_PRESETS, type PenetrateLineParams, type PenetrationModel, type PoseClip, type PoseClipChannels, type PoseClipEvent, type PoseClipRegistry, type PoseKey, type ProjectileInfo, type ProtectionLayer, type ProtectionOutcome, REGION_HIT_POINTS, REGION_SEGMENTS, type ResolvedCharacterSpec, type RestPose, type Rig, SEGMENT_IDS, SEGMENT_NUMBERS, SEGMENT_TREE, type SegmentId, type SegmentNode, type SegmentNumbers, type SegmentRuleId, type SegmentSide, type SegmentState, type SegmentStatus, type SeverityRules, type Stride, type StrideParams, TEAM_GAME, TEAM_GAME_CALIBERS, TEAM_GAME_CALIBER_KEYS, TEAM_GAME_PENETRATION, TORSO_RESISTANCE, type VarianceScale, animateProfile, applyPatches, applyPreset, bleedRateAt, blendMoves, clipEventsBetween, crawlPose, createBloodStream, createBodySpec, createCharacters, createConditionTimeline, createCorpseLedger, createPoseClipRegistry, createRig, createRng, cutOf, deadPose, decodePoseHeight, describeBody, drawAppearance, drawBodyVariance, emptySample, encodePoseHeight, energyKept, filterPoseChannels, humanPose, isBodyRegion, isSegmentId, layeredProtection, layersOn, lerpPose, mergeById, mirrorPoseClip, moveBlendOf, penetrateLine, penetrationForce, pointsFromEnergy, projectileOf, protect, removeIds, resolveDamageRules, resolvePoints, sampleFirstPersonClip, samplePoseClip, segmentNode, segmentResistance, segmentsBelow, spreadPoints, stepCascade, strideFor, teamGameCost, teamGameFalloff, variantCountFor, variantDecay, variantSeed, walkCadence, walkGait };