@adatechnology/game-characters-three 0.1.3 → 0.2.0

package/README.md

@@ -22,3 +22,8 @@ batch.push({ a: [x, z, yaw, phase], b: [1.8, 1, stride, 0], c: [missingMask, inf
 batch.end()
 time.value += dt
 ```
+
+**Sound and blood of the bodies** (on `@adatechnology/game-audio` and the running film of `@adatechnology/game-fluids-three`):
+
+- `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.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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, TestableModule } from '@adatechnology/game-contracts';
+import { Vec3 as Vec3$1, DestructionEvent, SoundRequest, TestableModule } 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. */
 type Three = typeof THREE_NS;
@@ -614,6 +615,86 @@ declare const gouge: (three: Three, materials: WoundMaterials, random: () => num
 /** Arsenal `explodeSeg`: 14 chunks the size of the part, thrown from its centre along the blow. */
 declare const explodeChunks: (three: Three, materials: WoundMaterials, random: () => number, box: THREE_NS.Box3, direction: THREE_NS.Vector3, fling: (chunk: THREE_NS.Object3D, velocity: THREE_NS.Vector3, spin: THREE_NS.Vector3) => void) => THREE_NS.Vector3;
 
+/** 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$1, liters: number, velocity?: Vec3$1): 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$1;
+        direction?: Vec3$1;
+        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$1, look?: BloodLook, direction?: Vec3$1): 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$1, look?: BloodLook, direction?: Vec3$1): number;
+    /** Blood from the engine's own bleeders: `litersPerSecond` over `dt` seconds at `point`. */
+    bleed(point: Vec3$1, litersPerSecond: number, dt: number, direction?: Vec3$1, 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;
+
 /** The group that stands for one segment of the engine's tree on a drawn body, with what the wounds need to cut it off. */
 type WoundNode = {
     /** The group that leaves (its children go with it). */
@@ -633,6 +714,8 @@ type WoundBody = {
     readonly root: THREE_NS.Object3D;
     readonly rig: RichRig;
     readonly nodes: Partial<Record<SegmentId, WoundNode>>;
+    /** The colours this body bleeds in (the infection age of a zombie). Without it the bridge's liquid and the liquid's own colours. */
+    blood?: BloodLook;
 };
 /**
  * Maps the rich body the best builder makes onto the engine's segments. The left side is +x, as the engine has it. The drawn body has no hand or foot
@@ -640,30 +723,82 @@ type WoundBody = {
  */
 declare const woundBodyOf: (root: THREE_NS.Object3D) => WoundBody | undefined;
 
-/** 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$1, liters: number, velocity?: Vec3$1): void;
+/** One sound of a voice: the recipe and, for a sequence, the seconds after the first. */
+type VoiceStep = {
+    readonly sound: string;
+    readonly delay?: number;
 };
-type FluidsBridgeOptions = {
-    readonly sink: BloodSink;
-    /** 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;
+/**
+ * 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[];
 };
-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. */
-    burst(change: 'severed' | 'destroyed' | 'split', point: Vec3$1): void;
-    /** Blood from the engine's own bleeders: `litersPerSecond` over `dt` seconds at `point`. */
-    bleed(point: Vec3$1, litersPerSecond: number, dt: number, direction?: Vec3$1, pressurized?: boolean): void;
+/** 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$1, 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$1, 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;
 };
 /**
- * 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.
+ * 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 const createFluidsBridge: ({ sink, liquid, spurtSpeed }: FluidsBridgeOptions) => FluidsBridge;
+declare function createCharacterSound(sink: CharacterSoundSink, options?: CharacterSoundOptions): CharacterSound;
 
 type WoundsOptions = {
     readonly random: () => number;
@@ -672,6 +807,8 @@ type WoundsOptions = {
     readonly groundAt?: (x: number, z: number) => number;
     /** The fluids bridge, when the game has the fluids packages. Without it the wounds draw no blood on the ground. */
     readonly bridge?: FluidsBridge;
+    /** The sounds of the bodies (`createCharacterSound`): a wound, a cut and a burst sound where the segment was. Without it the wounds are silent. */
+    readonly sound?: CharacterSound;
     readonly materials?: WoundMaterials;
     /** Pieces alive at once. Default 40. */
     readonly maxPieces?: number;
@@ -767,6 +904,7 @@ type UndeadLike = {
     }): DamageCharacter;
     traitsOf(character: DamageCharacter): {
         readonly type: string;
+        readonly age?: string;
         readonly speeds: Readonly<Record<string, number>>;
     } | undefined;
     speedFor(traits: {
@@ -800,6 +938,12 @@ type CharactersTestOptions = {
     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). */
@@ -873,4 +1017,10 @@ declare const registerBodyMaterial: (world: {
     readonly materials: Map<string, unknown>;
 }) => void;
 
-export { type AreaContext, BAKE_NEUTRAL_POSE, BODY_CHUNK, BODY_MATERIAL_DEF, type BakeBuilders, type BakeSpec, type BakedBody, type BestBuilder, type BestBuilderOptions, type BestTypeCard, type BloodSink, type BodyBatch, type BodyBatchOptions, type BodyChunkOptions, type BodyInstance, type BodyJoints, type BodyMaterialParams, type BodyVariant, type BuildInstancedBodyParams, CHARACTERS_AREA_ID, type CharactersTestOptions, EXTRAS, type EyeOptions, type Eyes, FACE_FEATURES, 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, type Pendulum, type PersonBuilder, type PersonBuilderOptions, type PoseTargets, type ProfessionCard, type RichRig, type RigAnimator, type RigAnimatorOptions, type Three, type UndeadCard, type UndeadLike, type VariantType, type WoundBody, type WoundMaterials, type WoundNode, type Wounds, type WoundsOptions, ZOMBIE_ITEM_PREFIX, bakeBody, bakeVariants, blobGeometry, blobRadii, buildInstancedBody, createBestBuilder, createBodyBatch, createBodyChunk, createBodyMaterial, 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 };
+/** The voice limiter group of the undead (`undead_voice`: five at once, one every 0.25 s, nearer than 40 m). */
+declare const UNDEAD_VOICE_GROUP = "undead_voice";
+/** The sounds of the game and of the art scene for the bodies, in one bank. */
+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 };