@adatechnology/game-animals-three 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,251 @@
+import { AnimalSpecies, QuadrupedSpec, TextureMarker, AnimalVisualState } from '@adatechnology/game-animals';
+import { NodeSkin } from '@adatechnology/game-props3d';
+import * as THREE_NS from 'three';
+import { TestableModule } from '@adatechnology/game-contracts';
+
+/** What the animation needs each frame. */
+type AnimateParams = {
+    /** Seconds since the start. */
+    readonly time: number;
+    /** Seconds since the last frame. */
+    readonly delta: number;
+    /** `idle`, `walk` or `run`; any other value stands in the walk pose without advancing the cycle, as the page does. */
+    readonly clip: string;
+    /** Snakes only: spread the body segments apart (the split view). */
+    readonly split?: boolean;
+};
+
+type Three = typeof THREE_NS;
+/** The slice of a canvas the texture painter uses; a stub works in tests. */
+type CanvasLike = {
+    width: number;
+    height: number;
+    getContext(kind: '2d'): unknown;
+};
+/** The slice of `document` that creates canvases. */
+type DocumentLike = {
+    createElement(tag: 'canvas'): CanvasLike;
+};
+type AnimalsThreeOptions = {
+    /** Where canvases for the coat textures (cat stripes, jaguar rosettes) come from; default `globalThis.document`. */
+    readonly document?: DocumentLike;
+    /** A stream of numbers in [0, 1) for the start phase of each step cycle; default a seeded stream of `seed`. */
+    readonly random?: () => number;
+    /** Seed of the default stream (the page uses 7). */
+    readonly seed?: number;
+};
+type AnimalPivot = {
+    readonly group: THREE_NS.Group;
+    readonly rest: THREE_NS.Vector3;
+    readonly offset: THREE_NS.Vector3;
+};
+type AnimalLeg = {
+    readonly hip: THREE_NS.Group;
+    readonly knee: THREE_NS.Group;
+    readonly foot: THREE_NS.Group;
+    readonly isFront: boolean;
+    readonly angle1: number;
+    readonly angle2: number;
+    readonly side: number;
+};
+type AnimalWing = {
+    readonly shoulder: THREE_NS.Group;
+    readonly elbow: THREE_NS.Group;
+    readonly side: number;
+};
+/** One animal: the tree to put in a scene (`root`) and the parts the animation drives. */
+type AnimalRig = {
+    readonly species: AnimalSpecies;
+    readonly root: THREE_NS.Group;
+    readonly trunk: THREE_NS.Group;
+    readonly materials: THREE_NS.MeshStandardMaterial[];
+    readonly joints: THREE_NS.Mesh[];
+    readonly pivots: AnimalPivot[];
+    readonly legs: AnimalLeg[];
+    readonly tail: THREE_NS.Group[];
+    readonly ears: THREE_NS.Group[];
+    /** Parts that show only while infected (wounds, ribs). */
+    readonly infectionParts: THREE_NS.Object3D[];
+    readonly eyes: THREE_NS.Mesh[];
+    readonly wings: AnimalWing[];
+    readonly segments: {
+        readonly group: THREE_NS.Group;
+        readonly radius: number;
+    }[];
+    phase: number;
+    size: number;
+    segmentLength: number;
+    segmentCount: number;
+    home: THREE_NS.Vector3;
+    infected: boolean;
+    dead: boolean;
+    pool?: THREE_NS.Mesh;
+    eyeMaterial?: THREE_NS.MeshStandardMaterial;
+    woundMaterial?: THREE_NS.MeshStandardMaterial;
+    main?: THREE_NS.MeshStandardMaterial;
+    dark?: THREE_NS.MeshStandardMaterial;
+    bodyGroup?: THREE_NS.Group;
+    /** The mesh of a quadruped's trunk (it moves with the animation of the body, so a node skin keeps it as a node). */
+    body?: THREE_NS.Mesh;
+    neck?: THREE_NS.Group;
+    head?: THREE_NS.Group;
+    jaw?: THREE_NS.Group;
+    tailRoot?: THREE_NS.Group;
+    neckAngle: number;
+    headAngle: number;
+    tongue?: THREE_NS.Mesh;
+    /** Triangles of the whole tree. */
+    triangles: number;
+};
+
+type MaterialExtras = Partial<THREE_NS.MeshStandardMaterialParameters>;
+/** The part builders of the page's `Animal` (`M`, `ball`, `limb`, `joint`, `pivot`), bound to one rig. */
+type RigTools = {
+    material(color: number, extras?: MaterialExtras): THREE_NS.MeshStandardMaterial;
+    ball(parent: THREE_NS.Object3D, radius: number, material: THREE_NS.Material, x?: number, y?: number, z?: number, sx?: number, sy?: number, sz?: number): THREE_NS.Mesh;
+    /** A cylinder hanging from the origin; `radius1` is the one the page calls the top, but the geometry takes it as the bottom (kept as the page has it). */
+    limb(parent: THREE_NS.Object3D, radius1: number, radius2: number, length: number, material: THREE_NS.Material): THREE_NS.Mesh;
+    joint(parent: THREE_NS.Object3D, radius: number, material: THREE_NS.Material, x?: number, y?: number, z?: number): THREE_NS.Mesh;
+    pivot(parent: THREE_NS.Object3D, x: number, y: number, z: number, offset?: THREE_NS.Vector3): THREE_NS.Group;
+    eyes(head: THREE_NS.Object3D, radius: number, x: number, y: number, z: number): void;
+};
+
+type HeadSpecOf = QuadrupedSpec['head'];
+type NeckSpecOf = QuadrupedSpec['neck'];
+
+type ExtraContext = {
+    readonly THREE: Three;
+    readonly rig: AnimalRig;
+    readonly tools: RigTools;
+};
+type QuadrupedParts = {
+    readonly bodyGroup: THREE_NS.Group;
+    readonly head: THREE_NS.Group;
+    readonly neck: THREE_NS.Group;
+    readonly main: THREE_NS.MeshStandardMaterial;
+    readonly belly: THREE_NS.MeshStandardMaterial;
+    readonly dark: THREE_NS.MeshStandardMaterial;
+    readonly L: number;
+    readonly Rb: number;
+    readonly bodyY: number;
+    readonly hd: HeadSpecOf;
+    readonly nk: NeckSpecOf;
+};
+type BirdParts = {
+    readonly bodyGroup: THREE_NS.Group;
+    readonly head: THREE_NS.Group;
+    readonly neck: THREE_NS.Group;
+    readonly main: THREE_NS.MeshStandardMaterial;
+    readonly dark: THREE_NS.MeshStandardMaterial;
+};
+type QuadrupedExtra = (context: ExtraContext, parts: QuadrupedParts) => void;
+type BirdExtra = (context: ExtraContext, parts: BirdParts) => void;
+/** The parts the page builds with code for five species (the page's `extra` closures), by species id. */
+declare const QUADRUPED_EXTRAS: Readonly<Record<string, QuadrupedExtra>>;
+declare const BIRD_EXTRAS: Readonly<Record<string, BirdExtra>>;
+
+type LineUpOptions = {
+    /** X where the row starts (page: -19). */
+    readonly start?: number;
+    /** Gap between animals (page: 0.85). */
+    readonly gap?: number;
+    /** Heading of the animals, radians (page: 1.1; snakes 2.2). */
+    readonly yaw?: number;
+    readonly snakeYaw?: number;
+};
+/** Puts the animals in a row on the x axis, each given room by its length, the row centred on the origin, and keeps each place as `home` (page: the line-up). */
+declare const lineUpAnimals: (rigs: readonly AnimalRig[], options?: LineUpOptions) => void;
+
+/** A body of revolution whose radius follows `profile` along the length, rear to front, closed by a point at each end. */
+declare const profileGeometry: (THREE: Three, length: number, profile: readonly number[], segments?: number) => THREE_NS.LatheGeometry;
+
+/** The coat texture a species spec asks for (cat stripes, jaguar rosettes), painted on a canvas. */
+declare const createCoatTexture: (THREE: Three, document: DocumentLike, marker: TextureMarker) => THREE_NS.CanvasTexture;
+
+/**
+ * Applies a visual state (page: `setInfected`, with the dead look for every species): infected greys the coat, glows the eyes, shows the wounds and hides
+ * the first ear; dead lets the animation lay the body down and shows a blood pool at `home`. The pool goes under `rig.root.parent`; with no parent yet,
+ * it is created hidden from the scene and `rig.pool` is for the caller to add.
+ */
+declare const applyVisualState: (THREE: Three, rig: AnimalRig, state: AnimalVisualState) => void;
+
+/** The "joints" view (page: `setJoint`): the coat turns see-through and every joint ball shows in `jointMaterial`. */
+declare const setJointView: (rig: AnimalRig, on: boolean, jointMaterial: THREE_NS.Material) => void;
+/** The "split" view (page: `setSplit`): sets where each pivot should go, the rest position or the rest plus its offset; `updateSplit` moves it there. */
+declare const setSplit: (rig: AnimalRig, on: boolean) => void;
+/** Moves each pivot toward its split target (the page does it in the frame loop: a lerp of 5 per second). */
+declare const updateSplit: (rig: AnimalRig, delta: number) => void;
+
+/** The part of the outbreak rule the area uses (`createAnimalOutbreak` of game-characters-undead has all of it). */
+type OutbreakLike = {
+    enabled: boolean;
+    bite(speciesId: string, random: () => number, now: number): {
+        readonly speciesId: string;
+        readonly outcome: 'turns' | 'dies';
+        readonly bittenAt: number;
+        readonly dueAt: number;
+    } | undefined;
+    stateOf(fate: {
+        readonly speciesId: string;
+        readonly outcome: 'turns' | 'dies';
+        readonly bittenAt: number;
+        readonly dueAt: number;
+    }, now: number): 'incubating' | 'turned' | 'dead';
+    carcass(speciesId: string, position: readonly [number, number, number], now: number): {
+        readonly lureRadiusMetres: number;
+    } | undefined;
+    lures(carcass: {
+        readonly lureRadiusMetres: number;
+    }, distance: number, now: number): boolean;
+};
+type AnimalsTestOptions = {
+    /** `en` or `pt-BR` (default). */
+    readonly locale?: string;
+    /** The species to lay out (the 13 of `@adatechnology/game-animals-species`). */
+    readonly species?: readonly AnimalSpecies[];
+    /** Builds the outbreak rule for the bench (`createAnimalOutbreak` from game-characters-undead): called again when the clock changes. Without it the bite actions do nothing. */
+    readonly createOutbreak?: (options: {
+        readonly species: readonly AnimalSpecies[];
+        readonly enabled: boolean;
+        readonly timeScale: number;
+    }) => OutbreakLike;
+    readonly document?: DocumentLike;
+    /** Seed of the draws of the area (default 7, the page's). */
+    readonly seed?: number;
+};
+
+/** What a scenario needs of the room: the pass/fail line and time. The test room's `ScenarioContext` has both. */
+type AnimalsContext = {
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+    step(seconds: number): void;
+};
+
+declare const ANIMALS_AREA_ID = "animals_area";
+declare const ANIMAL_ITEM_PREFIX = "animal_";
+/**
+ * The animals test area as a `TestableModule`: the species of the pack in a row, each drawn by the Bichos do Vale builders, with the alive / infected / dead looks, the gait,
+ * the joints and split views, the rings for how far its sound carries and how far a carcass lures, the outbreak rule with an accelerated bite clock, and a field of 40 animals
+ * drawn as node skins. The species and the outbreak rule come in by option, so this package knows no game.
+ */
+declare function createAnimalsTestModule(options?: AnimalsTestOptions): TestableModule<AnimalsContext> & {
+    readonly placed: ReadonlyMap<string, unknown>;
+};
+
+type AnimalsThree = {
+    /** Builds one animal from its species; consumes one number of the stream for the start phase unless `phase` is given. */
+    build(species: AnimalSpecies, buildOptions?: {
+        readonly phase?: number;
+    }): AnimalRig;
+    /** Advances the animation of one animal (steps, flight, wings, head, tail, a dead one lying down). */
+    animate(rig: AnimalRig, params: AnimateParams): void;
+    setVisualState(rig: AnimalRig, state: AnimalVisualState): void;
+    setJointView(rig: AnimalRig, on: boolean): void;
+    setSplit(rig: AnimalRig, on: boolean): void;
+    updateSplit(rig: AnimalRig, delta: number): void;
+    /** One mesh that stands for the whole tree, for crowds: call `skin.update()` each frame after `animate`. */
+    createSkin(rig: AnimalRig): NodeSkin;
+    readonly jointMaterial: THREE_NS.MeshStandardMaterial;
+};
+declare const createAnimalsThree: (THREE: Three, options?: AnimalsThreeOptions) => AnimalsThree;
+
+export { ANIMALS_AREA_ID, ANIMAL_ITEM_PREFIX, type AnimalLeg, type AnimalPivot, type AnimalRig, type AnimalWing, type AnimalsContext, type AnimalsTestOptions, type AnimalsThree, type AnimalsThreeOptions, type AnimateParams, BIRD_EXTRAS, type BirdExtra, type BirdParts, type CanvasLike, type DocumentLike, type ExtraContext, type LineUpOptions, type OutbreakLike, QUADRUPED_EXTRAS, type QuadrupedExtra, type QuadrupedParts, type Three, applyVisualState, createAnimalsTestModule, createAnimalsThree, createCoatTexture, lineUpAnimals, profileGeometry, setJointView, setSplit, updateSplit };