@adatechnology/game-player 0.0.0-stage → 0.2.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/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @adatechnology/game-player
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The player's body for games, pure and seeded: vitals from an attribute sheet, stamina, wounds and bleeding, the bandage, being grabbed and breaking
+free (six pushes or the knife), knock-downs, vaulting a low wall, footstep noise, panic, the shove and the melee blow against any crowd, and an
+optional individual infection. No three.js, no audio, no game content: it emits events (`noise`, `sound`, `message`...) and the game plays and shows them.
+
+It is a literal port of the team game's player (`jogo.js` G 68427-68640: `player`, `playerUpdate`, `frontZombies`, `shove`, `knife`, with `FICHA`,
+`DERIV`, `INFEC` and `FERIDA`). Every number is in `src/data/defaults.json` with its source line, and the golden `game-player.json` (18 scripted runs of
+the game code in `node:vm`, recorded by `tools/characters-catalog`) is replayed frame by frame by the tests.
+
+- **The normal world comes first.** The infection is off by default: wounds bleed, a bite hurts, nothing turns. `infection: true` turns on the game
+  rule (scratch 6%, laceration 22%, bite 100%; fever at 30 s, delirium at 70 s, death at 120 s, the body turns 8 s later).
+- **The sheet** (`attributes`): strength, vigor, agility, perception, intellect, presence (5 each by default). The derived values (`maxHealth`,
+  `maxStamina`, `runSpeed`, `walkSpeed`, `footstepNoise`, `composure`) are linear formulas given as data (`derived`).
+- **The world** is a set of callbacks (`cellKind`, `solidAt`, `blocked`, `inWater`, `busy`, `canVault`, `afterMove`); the default is an open dry field.
+- **The crowd** is the `PlayerCrowd` interface (read by index, written by `hold`, `stun`, `chase`, `damage`); `game-crowd` implements it, and any game
+  with its own agents writes a small adapter.
+- **Every draw is in the game's order** on the stream you pass (`random`), so a game that shares one stream keeps its sequence.
+
+## Install
+
+```sh
+pnpm add @adatechnology/game-player
+```
+
+Browser without a bundler (the global is `GamePlayer`):
+
+```html
+<script src="https://unpkg.com/@adatechnology/game-player/dist/index.global.js"></script>
+```
+
+## Usage
+
+```ts
+import { createPlayer, playerTextOf } from '@adatechnology/game-player'
+
+const player = createPlayer({ seed: 7, attributes: { agility: 7 }, world: { solidAt: grid.solidAt, cellKind: grid.cellKind, inWater, crowd } })
+player.on('noise', ({ x, z, radius }) => crowd.emitNoise(x, z, radius))
+player.on('sound', (request) => audio.play(request)) // { sound: 'step' | 'flesh', volume, position }
+player.on('message', ({ id, seconds }) => hud.show(playerTextOf(id, locale), seconds))
+player.on('died', ({ cause }) => endScreen(cause))
+
+// every frame: held keys as booleans, the keys pressed this frame under `pressed`
+player.update(dt, { forward: 1, right: 0, run: shift, aim, yaw: camera.yaw, bandage: keyB, pressed: { crouch, push, knife, vault, throw: t } })
+player.state.health // also stamina, bleeding, wounds, grabbedBy, panic...
+player.spreadFactor() // panic x fever x moving, for the weapon's spread
+
+player.hurt(12) // a hit: draws the wound kind
+player.grab(agentIndex) // 3 s to break free
+player.knock(1.5)
+```
+
+## Test area
+
+`createPlayerTestModule()` (`player_area`, only the generic contracts) makes the room's camera the player body and puts the vitals on the bench;
+`examples/player-test-area` loads it into the shared test room (`PlayerArea.loadInto(room)`, `sala-jogador.html`), and `examples/interactables-test-area`
+carries it too.

package/dist/index.d.ts

@@ -0,0 +1,419 @@
+import { TestableModule } from '@adatechnology/game-contracts';
+
+var numbers = {
+	hurtFlash: 0.4,
+	hurtVolume: 0.8,
+	biteDamage: 25,
+	biteFlash: 0.8,
+	biteVolume: 1.2,
+	burnPerSecond: 3,
+	bleedPerSecond: 0.15,
+	grabSeconds: 3,
+	grabVolume: 1,
+	grabFollow: 12,
+	grabOffset: 0.55,
+	grabPushCost: 6,
+	grabPushMinStamina: 5,
+	grabPushVolume: 1.5,
+	grabPushes: 6,
+	grabPushStun: 1.2,
+	grabPushSpeed: 3,
+	grabKnifeChance: 0.7,
+	grabKnifeRegion: 0,
+	grabKnifeDamage: 22,
+	grabKnifeDistance: 0.5,
+	grabKnifeCut: 0.7,
+	drownDamage: 30,
+	drownFlash: 0.8,
+	noJawDamage: 8,
+	grabAttackCooldown: 2,
+	vaultSeconds: 0.7,
+	vaultCost: 15,
+	vaultHeight: 1.9,
+	vaultScanFrom: 0.3,
+	vaultScanTo: 1,
+	vaultScanStep: 0.1,
+	vaultLandFrom: 0.4,
+	vaultLandTo: 1.4,
+	vaultClearance: 0.3,
+	vaultCheckHeight: 0.4,
+	vaultNoise: 6,
+	vaultStartVolume: 0.8,
+	vaultLandVolume: 1,
+	crouchSpeed: 1,
+	walkFactor: 1.35,
+	aimSpeedCap: 1.4,
+	waterSpeed: 0.55,
+	runMinStamina: 1,
+	runDrain: 12,
+	regenMoving: 4,
+	regenStill: 8,
+	acceleration: 10,
+	radius: 0.3,
+	blockHeight: 0.4,
+	pushApartRadius: 0.55,
+	pushApartHeight: 1.2,
+	hipFollow: 10,
+	hipMinSpeed: 0.3,
+	hipLimit: 0.9,
+	backwardsBelow: -0.1,
+	cadenceBase: 0.5,
+	cadencePerSpeed: 0.3,
+	cadenceMinSpeed: 0.05,
+	turnFollow: 12,
+	stepEvery: 0.75,
+	stepMinSpeed: 0.3,
+	stepNoiseRun: 8,
+	stepNoiseWalk: 3,
+	stepNoiseCrouch: 1,
+	stepNoiseWater: 2,
+	stepVolumeRun: 0.6,
+	stepVolumeWalk: 0.3,
+	shoveCost: 10,
+	shoveVolume: 1.2,
+	shoveRange: 1.6,
+	shoveCone: 0.3,
+	shoveStun: 0.9,
+	shoveSpeed: 2.5,
+	meleeMinStamina: 5,
+	meleeCostLight: 5,
+	meleeCostHeavy: 12,
+	meleeHeavyKg: 1.5,
+	meleeVolume: 0.6,
+	meleeRangeBase: 0.9,
+	meleeCone: 0.5,
+	meleeHeadChance: 0.35,
+	meleeArmChance: 0.5,
+	meleeStrengthPerPoint: 0.06,
+	meleeStrengthBase: 5,
+	meleeCritToCut: 60,
+	panicGain: 1.2,
+	panicDecay: 3,
+	panicMax: 100,
+	panicSpreadAt: 0.6,
+	panicSpread: 1.4,
+	moveSpread: 0.4
+};
+var defaults = {
+	numbers: numbers};
+
+type AttributeId = 'strength' | 'vigor' | 'agility' | 'perception' | 'intellect' | 'presence';
+type Attributes = Readonly<Record<AttributeId, number>>;
+/** `(base + Σ coefficient × attribute) / divide`, summed left to right in the order given (the game's own order, so the floats match). */
+type LinearFormula = {
+    readonly base: number;
+    readonly terms: readonly (readonly [AttributeId, number])[];
+    readonly divide?: number;
+};
+type DerivedId = 'maxHealth' | 'maxStamina' | 'runSpeed' | 'walkSpeed' | 'footstepNoise' | 'composure';
+type DerivedFormulas = Readonly<Record<DerivedId, LinearFormula>>;
+type Derived = Readonly<Record<DerivedId, number>>;
+/** A wound kind: its share of the hits (drawn in the listed order, the last one takes the rest), its infection chance and whether it bleeds. */
+type WoundRule = {
+    readonly share: number;
+    readonly infectionChance: number;
+    readonly bleeds: boolean;
+};
+type WoundTable = Readonly<Record<string, WoundRule>>;
+/** An individual infection that runs on its own clock and kills at `deathSeconds`. Off by default: a normal world has none. */
+type InfectionRule = {
+    readonly feverSeconds: number;
+    readonly deliriumSeconds: number;
+    readonly deathSeconds: number;
+    /** Seconds after death the body turns (`turned` event). */
+    readonly reanimateSeconds: number;
+    /** With fever, every this many seconds there is a `feverNoiseChance` of a cough: noise of `feverNoiseRadius` m. */
+    readonly feverNoiseEvery: number;
+    readonly feverNoiseChance: number;
+    readonly feverNoiseRadius: number;
+    readonly feverNoiseVolume: number;
+    readonly feverSpeed: number;
+    readonly feverSpread: number;
+    /** Infection chance per wound kind; a kind left out uses the wound table's `infectionChance`. */
+    readonly chances?: Readonly<Record<string, number>>;
+};
+type PlayerNumbers = typeof defaults.numbers;
+/** What is in the hand for melee (the fist when absent): damage, critical (0..60 turns into a cut), reach in metres, noise radius, mass. */
+type MeleeItem = {
+    readonly damage: number;
+    readonly crit?: number;
+    readonly reach?: number;
+    readonly noise?: number;
+    readonly kg?: number;
+};
+/** One frame of input. Held keys are booleans; the `pressed` ones are true only on the frame the key went down. */
+type PlayerInput = {
+    /** -1 back, 0, 1 forward. */
+    readonly forward?: number;
+    /** -1 left, 0, 1 right. */
+    readonly right?: number;
+    readonly run?: boolean;
+    /** Aiming down the sights: speed is capped and the body turns with the view at once. */
+    readonly aim?: boolean;
+    /** The trigger is held or the weapon is cooling: the body turns with the view at once. */
+    readonly firing?: boolean;
+    /** Where the view looks (radians, the camera's yaw: forward is `(-sin, -cos)`). */
+    readonly yaw?: number;
+    /** Held: dress the bleeding wound. */
+    readonly bandage?: boolean;
+    readonly pressed?: Readonly<Partial<Record<PlayerAction, boolean>>>;
+    /** The melee item in hand. */
+    readonly melee?: MeleeItem;
+};
+type PlayerAction = 'crouch' | 'push' | 'knife' | 'vault' | 'throw';
+/**
+ * The crowd the player touches (a horde, any crowd): read by index, written through a few verbs. `game-crowd` implements it; a game with its own
+ * agents writes a small adapter. Only agents that are `active` (close and simulated every frame) are pushed, counted for panic or hit.
+ */
+interface PlayerCrowd {
+    count(): number;
+    active(i: number): boolean;
+    x(i: number): number;
+    z(i: number): number;
+    y(i: number): number;
+    floor(i: number): number;
+    chasing(i: number): boolean;
+    /** On the ground: crawling or stunned. A melee blow on it always goes to the head. */
+    down(i: number): boolean;
+    /** How much it adds to panic (default 1). */
+    panicWeight?(i: number): number;
+    /** The grabbing agent is glued to the player's body: move by `k` of the way to (x, z), stop, and face (lookX, lookZ). */
+    hold(i: number, x: number, z: number, k: number, lookX: number, lookZ: number): void;
+    stun(i: number, seconds: number, vx: number, vz: number): void;
+    /** Back to chasing, with the attack cooling for `cooldown` seconds. */
+    chase(i: number, cooldown: number): void;
+    damage(i: number, hit: {
+        region: number;
+        amount: number;
+        distance: number;
+        cut: number;
+    }): void;
+}
+/** What the player asks of the world. Everything is optional: the default is an open, dry field. */
+interface PlayerWorld {
+    /** Occupancy code of the cell at (x, z): -1 outside, 0 free, 1 solid, 2 low wall that can be vaulted, 3 open door, others solid. */
+    cellKind?(x: number, z: number): number;
+    solidAt?(x: number, z: number, y: number): boolean;
+    /** Blocks the player's body at (x, z). Default `solidAt(x, z, blockHeight)` (a roof or a floor plan passes its own). */
+    blocked?(x: number, z: number): boolean;
+    inWater?(x: number, z: number): boolean;
+    /** Something else drives the player this frame (a car seat, a chair, a ladder): skip moving. */
+    busy?(dt: number): boolean;
+    /** Low walls can be vaulted here (the game says no on a roof or an upper floor). Default: only on the ground floor. */
+    canVault?(): boolean;
+    /** After the move (stairs change the floor and the height). */
+    afterMove?(player: PlayerState): void;
+    crowd?: PlayerCrowd;
+}
+type PlayerState = {
+    x: number;
+    z: number;
+    y: number;
+    vx: number;
+    vz: number;
+    /** The body's yaw (the view's yaw + π, smoothed). */
+    yaw: number;
+    floor: number;
+    alive: boolean;
+    turned: boolean;
+    health: number;
+    stamina: number;
+    crouch: boolean;
+    running: boolean;
+    stepTimer: number;
+    phase: number;
+    hip: number;
+    grabbedBy: number;
+    grabTimer: number;
+    grabPushes: number;
+    grabNoJaw: boolean;
+    grabDrown: boolean;
+    infected: boolean;
+    infectionTime: number;
+    infectionSource: string;
+    wounds: string[];
+    bleeding: number;
+    blind: number;
+    screamBoost: number;
+    panic: number;
+    hurtFlash: number;
+    deathTime: number;
+    cause: string;
+    downTimer: number;
+    burnTimer: number;
+    scentTimer: number;
+    vaultTimer: number;
+    vault: [number, number, number, number] | null;
+};
+type PlayerSoundId = 'step' | 'flesh';
+type PlayerMessageId = 'grabbed' | 'grabbed_drown' | 'bitten' | 'bandaged' | 'knife_head' | 'knife_miss' | 'pushed_off' | 'drowning' | 'no_jaw' | 'stood_up';
+type KnownDeathCause = 'infected' | 'killed' | 'bitten_to_death' | 'infection' | 'bled_out' | 'hunger_thirst' | 'drowned' | 'burned';
+/** Why the player died: the rule's own causes, or any id the host passes to `die`. */
+type DeathCause = KnownDeathCause | (string & {});
+type PlayerEventMap = {
+    noise: {
+        x: number;
+        z: number;
+        radius: number;
+    };
+    sound: {
+        sound: PlayerSoundId;
+        volume: number;
+        position: [number, number, number];
+    };
+    step: {
+        x: number;
+        z: number;
+        yaw: number;
+    };
+    message: {
+        id: PlayerMessageId | DeathCause;
+        seconds: number;
+    };
+    hurt: {
+        amount: number;
+        wound: string;
+    };
+    infected: {
+        source: string;
+    };
+    stage: {
+        stage: 'fever' | 'delirium';
+    };
+    died: {
+        cause: DeathCause;
+    };
+    turned: {
+        x: number;
+        z: number;
+        floor: number;
+    };
+    grabbed: {
+        by: number;
+        noJaw: boolean;
+        drown: boolean;
+    };
+    released: {
+        by: number;
+        how: 'push' | 'knife' | 'bite' | 'scratch' | 'free';
+    };
+    vault: {
+        from: [number, number];
+        to: [number, number];
+    };
+    shove: {
+        targets: number[];
+    };
+    melee: {
+        target: number;
+        region: number;
+        damage: number;
+        distance: number;
+        cut: number;
+    };
+    throw: Record<string, never>;
+};
+type PlayerEventName = keyof PlayerEventMap;
+type PlayerEvent<K extends PlayerEventName = PlayerEventName> = PlayerEventMap[K];
+type PlayerSave = {
+    readonly state: PlayerState;
+    readonly attributes: Attributes;
+};
+
+declare const PLAYER_DEFAULTS: {
+    readonly sources: Readonly<Record<string, string>>;
+    readonly attributes: Attributes;
+    readonly derived: DerivedFormulas;
+    readonly wounds: WoundTable;
+    readonly infection: InfectionRule;
+    readonly numbers: PlayerNumbers;
+    readonly fist: MeleeItem;
+};
+type PlayerOptions = {
+    /** The random stream (the game passes its single stream). Default `createRng(seed)`. */
+    readonly random?: () => number;
+    readonly seed?: number;
+    /** The sheet: every attribute 5 by default. */
+    readonly attributes?: Partial<Attributes>;
+    readonly derived?: Partial<DerivedFormulas>;
+    readonly wounds?: WoundTable;
+    /** An individual infection (`true` uses the defaults; an object patches them). Off by default: the normal world comes first. */
+    readonly infection?: boolean | Partial<InfectionRule>;
+    readonly numbers?: Partial<PlayerNumbers>;
+    readonly fist?: MeleeItem;
+    readonly position?: {
+        readonly x?: number;
+        readonly z?: number;
+        readonly yaw?: number;
+    };
+    readonly world?: PlayerWorld;
+};
+type Player = {
+    readonly state: PlayerState;
+    readonly attributes: Attributes;
+    readonly derived: Derived;
+    readonly numbers: PlayerNumbers;
+    readonly infection: InfectionRule | null;
+    update(dt: number, input?: PlayerInput, world?: PlayerWorld): void;
+    /** A hit that opens a wound (drawn from the wound table) and may infect. `by` is the agent that hit, if any. */
+    hurt(amount: number, by?: number): void;
+    /** A bite: damage, bleeding, a bite wound and (with an infection rule) the infection. */
+    bite(by?: number): void;
+    grab(by: number, noJaw?: boolean, drown?: boolean): void;
+    release(): void;
+    knock(seconds: number): void;
+    infect(source: string): void;
+    /** Kills the player with a cause (the host's deaths: a fall, a fire). */
+    die(cause: DeathCause): void;
+    /** Infection stage: `none`, `malaise`, `fever`, `delirium`. */
+    stage(): 'none' | 'malaise' | 'fever' | 'delirium';
+    /** Seconds the infection has left, or null. */
+    timeLeft(): number | null;
+    /** What the player's state does to aim spread (panic, fever, moving); the weapon multiplies its own spread by it. */
+    spreadFactor(): number;
+    /** The agents in front (nearest first) within `range` m and a cone of `cosMin`, as `[distance, index]`. */
+    front(range: number, cosMin: number, yaw: number, crowd?: PlayerCrowd): [number, number][];
+    on<K extends PlayerEventName>(event: K, listener: (event: PlayerEventMap[K]) => void): () => void;
+    save(): PlayerSave;
+    load(save: PlayerSave): void;
+    /** The world `update` uses when it is given none. */
+    setWorld(world: PlayerWorld): void;
+};
+/** The derived values of a sheet (the game's `DERIV`). */
+declare const deriveVitals: (attributes: Attributes, formulas?: DerivedFormulas) => Derived;
+/** Which wound a hit opens: one draw, the kinds in the listed order, the last one takes the rest (the game's `FERIDA` draw). */
+declare const drawWound: (wounds: WoundTable, random: () => number) => string;
+/**
+ * The player body: a literal port of the team game's `player` and `playerUpdate` (G 68427-68640) with the world, the crowd and the input as
+ * arguments instead of globals. The draws on `random` happen in the game's order (wound kind, infection, the fever cough, the knife when grabbed,
+ * the melee region), so a game that passes its own stream keeps its sequence.
+ */
+declare function createPlayer(options?: PlayerOptions): Player;
+
+/** Deterministic mulberry32 generator; returns floats in [0, 1). */
+declare function createRng(seed: number): () => number;
+
+type PlayerText = Readonly<Record<PlayerMessageId | KnownDeathCause, string>>;
+declare const PLAYER_TEXT: Readonly<Record<'en' | 'pt-BR', PlayerText>>;
+/** The text of a message or death cause id in a locale (`pt-BR` or `en`, the language part is enough); unknown ids come back as they are. */
+declare const playerTextOf: (id: string, locale?: string) => string;
+
+type PlayerTestModuleOptions = PlayerOptions & {
+    readonly locale?: string;
+};
+/** What the scenarios use of the context the test room passes. */
+interface PlayerScenarioLike {
+    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
+}
+type PlayerTestModule = TestableModule<PlayerScenarioLike> & {
+    /** The player in use (replaced when the bench changes the sheet, the seed or the infection). */
+    readonly player: Player;
+};
+/**
+ * The player area of a test room, against the generic contracts only. The room's camera is the player: where it walks, the player walks; its speed
+ * decides walking or running, so stamina, footsteps and their noise follow the viewer. The bench hurts, bites, grabs and knocks the player down,
+ * switches the individual infection (off by default: a normal world) and sets the sheet. Footsteps and flesh sounds go to `host.audio`.
+ */
+declare function createPlayerTestModule(options?: PlayerTestModuleOptions): PlayerTestModule;
+
+export { type AttributeId, type Attributes, type DeathCause, type Derived, type DerivedFormulas, type DerivedId, type InfectionRule, type KnownDeathCause, type LinearFormula, type MeleeItem, PLAYER_DEFAULTS, PLAYER_TEXT, type Player, type PlayerAction, type PlayerCrowd, type PlayerEvent, type PlayerEventMap, type PlayerEventName, type PlayerInput, type PlayerMessageId, type PlayerNumbers, type PlayerOptions, type PlayerSave, type PlayerSoundId, type PlayerState, type PlayerTestModule, type PlayerTestModuleOptions, type PlayerText, type PlayerWorld, type WoundRule, type WoundTable, createPlayer, createPlayerTestModule, createRng, deriveVitals, drawWound, playerTextOf };