@adatechnology/game-crowd 0.2.6 → 0.3.0

package/README.md

@@ -90,6 +90,47 @@ Civilians are a literal port of the game's survivors on the block (`jogo.js` G 6
 without the rig; the vultures of G 66700-66708 and the live map's ring of birds of the Bancada de Hordas (G 53609-53615). Two goldens replay them
 with the horde: `game-crowd-civilians.json` (3 scenes) and `game-crowd-herd.json`.
 
+## Physics: a dense horde and the chain of a blast
+
+`CrowdOptions.physics` is off by default and then the horde is the game's, bit for bit (the team goldens run with it off). `CROWD_PHYSICS_DEFAULTS` turns everything on:
+
+```ts
+const crowd = createCrowd({ pack, seed, physics: { ...CROWD_PHYSICS_DEFAULTS, playerPressure: { enabled: true, knockThreshold: 1500, crushDamagePerSecond: 6 } } })
+// fixed steps only: the same seed gives the same result at 30, 60 and 144 fps
+crowd.update(1 / 60, { target, bandCentre: [x, z] })
+crowd.blast({ point: [x, y, z], energy: 200000, radius: 15, lethalRadius: 5 }) // resolved at the start of the next step, in one pass over the agents
+crowd.stats.physics // falls by cause, fallsBeyondBlast, climbers, moundMax, thrownPeak, blastChecks...
+```
+
+- **Contact:** inelastic impulses between bodies (symmetric Gauss-Seidel, so a low index has no advantage) and a position correction by the mean of what each agent was asked to move; it never adds energy.
+- **Pressure:** a field apart from the contact that moves one hop per fixed step, so a file of N agents pushing on a wall gives its front `N` times the drive (`design-chain-horde.md` section 4.5).
+- **Balance:** standing, staggering, fallen, getting up and thrown, by pressure over a critical value of the body (`CrowdType.balance` and the personality), shoves, trips, landings and collapses.
+- **Mound:** lying bodies are a height per cell (integer millimetres) that others climb, trample and bring down when the base goes.
+- **Thrown bodies:** a pool of 32 simulated here (`crowd.thrown`) and only drawn by the renderer; `thrown.priority` is `'mixed'` (half the slots to the fastest, half to the nearest to the band centre), `'fastest'` or `'nearest'`.
+- **Personality:** speed, reaction, stability, trip, drive, cadence, aggression, gait and idle from the identity of each agent, never from the shared random stream.
+- **Far band (R1):** no pairs. Every 12th step a coarse grid of 2 m counts the standing walkers of band R1 per cell; above 4 bodies the wanted speed is `4 / bodies` and the field is `(bodies − 4) · 150` N, which the same balance rule reads (`physics.density`, needs `balance`). A body that falls there lies without entering the mound, and joins it when it comes into R0.
+- **Player pressure:** `playerPressure` reports the pressure of the horde on the target through `knock` and `hurt` (off in the package; a game turns it on).
+
+### The contact and the pressure in a worker
+
+`physics.worker` is `'off'` by default (the step runs where it always did). `'auto'` moves the contact and the pressure to a worker when one can be made and stays in the step when it cannot; `'on'` throws instead of staying.
+The worker is **one step behind**: it is handed the state at the end of step *k*, and step *k + 1* (`workerLatency: 1`, default) or *k + 2* (`workerLatency: 2`) adds what it computed as deltas of position, push and velocity and replaces the pressure field. With the same inputs per step the answer is the same whichever thread computed it: `inline` (the same kernel on the calling thread) is the reference, and the tests compare it with a worker byte for byte. Balance, mound, thrown bodies and blasts stay on the main thread.
+
+```ts
+const crowd = createCrowd({ pack, seed, physics: { ...CROWD_PHYSICS_DEFAULTS, worker: 'auto', workerLatency: 2 } })
+// ...
+crowd.dispose() // stops the worker
+```
+
+- `workerTransport: 'shared'` (default where `SharedArrayBuffer` is usable): frame in a `SharedArrayBuffer`, control word with `Atomics`. The main thread waits for the answer, so the run is reproducible. A browser needs the page **cross-origin isolated**: serve it with `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`), and every cross-origin sub-resource with `Cross-Origin-Resource-Policy` or CORS. `crossOriginIsolated` is then `true`. Node has `SharedArrayBuffer` always.
+- `workerTransport: 'transfer'`: without isolation; the frame goes by `postMessage` with its buffer transferred. The main thread cannot wait for an event, so it applies the answer when it has arrived and runs without it otherwise (the contact then lags more): it is not reproducible. `'auto'` picks it when the page is not isolated.
+- `workerFactory`: the default makes a module worker from `physics-worker.js`, which sits next to `index.js` in `dist`, with `new Worker(new URL('./physics-worker.js', import.meta.url), { type: 'module' })` (Vite, webpack 5 and esbuild resolve it); the `index.global.js` build has no `import.meta`, so there give a `workerFactory`. A host that bundles its own worker (or runs node `worker_threads`) gives the factory and calls `attachPhysicsWorker(port)` inside the worker; `tests/fixtures/node-physics-worker.mjs` is a node example.
+- The frame copies the grid occupancy every step (1 byte per cell, 2.4 MB for the default 768 m grid): a `NavGrid` no bigger than the playable area keeps that copy small.
+
+Measured with `bench/dense-update.mjs` (node, 2000 agents pressed against a wall, all in band R0, `WORKER=shared LATENCY=2`): `crowd.update` on the main thread goes from 3.0 to 3.8 ms to 1.6 to 2.1 ms mean (the machine was loaded); with one step of latency the main thread waits for the worker for a third of its step, so it gains little. See `specs/005-camadas-e-quadro/evidence.md`, row T4b.perf.
+
+`bench/dense-update.mjs` measures `crowd.update` with 1000 and 2000 agents pressed against a wall, with and without the physics.
+
 ## What is not here yet
 
 The drawing and the test area are in `@adatechnology/game-crowd-three`. The game's multi-floor houses (`ANDARES`) and the roof (`ROOF`) are not ported: the crowd walks one

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { CorpseLedger } from '@adatechnology/game-characters';
+import { BlastShoveOptions } from '@adatechnology/game-contracts';
 
 var numbers = {
 	capacity: 6000,
@@ -178,6 +179,202 @@ declare function createDoors(grid: NavGrid, options: {
     numbers?: Partial<DoorNumbers>;
 }): Doors;
 
+/**
+ * `shared`: one `SharedArrayBuffer` frame and a control word, the worker computes while the main thread runs the rest of the step; needs `crossOriginIsolated` in a browser.
+ * `transfer`: the frame goes by `postMessage` with its buffer transferred; no isolation needed, but the answer arrives whenever the event loop delivers it.
+ * `inline`: the same protocol and the same kernel on the calling thread, one step of latency as well; the reference the other two must match.
+ */
+type OffloadTransport = 'shared' | 'transfer' | 'inline';
+/** A worker as the runner sees it: browsers and node differ in how a message arrives, the factory hides that. */
+type PhysicsWorkerHandle = {
+    postMessage(message: unknown, transfer?: ArrayBuffer[]): void;
+    onMessage(listener: (data: unknown) => void): void;
+    terminate(): void;
+};
+type PhysicsWorkerFactory = () => PhysicsWorkerHandle;
+
+type CrowdContactOptions = {
+    /** Body radius over build (default 0.25 → 0.5 m between two average bodies; the separation keeps them at 0.78 m when it can). */
+    readonly radius?: number;
+    /** Iterations per fixed step in band R0 (default 2; 3 is the ceiling). */
+    readonly iterations?: 1 | 2 | 3;
+    /** Push velocity damping per second: push ← push·exp(−friction·h) (default 6 → λ = 0.905 at 60 Hz). */
+    readonly friction?: number;
+    /** Ceiling of the push velocity, m/s (default 3). */
+    readonly maxPush?: number;
+    /** Ceiling of the position correction of one agent in one iteration, m (default 0.1; the design started at 0.06). */
+    readonly maxCorrection?: number;
+    /** Jacobi relaxation of the position correction (default 1; the design started at 0.5, which left 0.25 m overlaps in a crush of 800). */
+    readonly relaxation?: number;
+    /** kg of a body of height 1 and build 1 (default 70). */
+    readonly baseMass?: number;
+    /** Ceiling of the separation term `|Σ sep · separationPush|`, m/s (default 1.5). */
+    readonly separationMax?: number;
+};
+type CrowdPressureOptions = {
+    /** Share kept per hop, τ (default 0.97). */
+    readonly transmission?: number;
+    /** Ceiling of the field per agent, N (default 6000). */
+    readonly cap?: number;
+    /** Cosine of the half angle that counts as "in front" (default 0.5 → 60°). */
+    readonly frontCone?: number;
+    /** Share of the will speed of a staggering agent (default 0.35); the field keeps the full drive. */
+    readonly staggerSpeed?: number;
+};
+type CrowdBalanceOptions = {
+    /** `P_crit = criticalFactor · m · g · stability` (default 2.0 → 1372 N for a walker). */
+    readonly criticalFactor?: number;
+    /** P/P_crit to start staggering (default 0.7). */
+    readonly staggerEnter?: number;
+    /** P/P_crit to stop, after `staggerMin` (default 0.4). */
+    readonly staggerLeave?: number;
+    /** Seconds (default 0.5). */
+    readonly staggerMin?: number;
+    /** 1/s, rate = fallRate·(P/P_crit − 1)² above 1 (default 1.5). */
+    readonly fallRate?: number;
+    /** |Δpush| in one step that staggers, m/s (default 1.2). */
+    readonly shoveStagger?: number;
+    /** |Δpush| that knocks down, m/s, times stability (default 2.5). */
+    readonly shoveFall?: number;
+    /** Seconds on the ground before trying to get up (default 1.5, plus reaction). */
+    readonly fallenMin?: number;
+    /** P/P_crit under which a fallen one may get up (default 0.3). */
+    readonly releaseFactor?: number;
+    /** Default 1.2. */
+    readonly getUpSeconds?: number;
+    /** Seconds of the exponential mean (default 0.3). */
+    readonly pressureTau?: number;
+    /** Ceiling of new falls per fixed step (default 8). */
+    readonly maxFallsPerStep?: number;
+    /** Ceiling of agents on the ground (default 300); above it a fall becomes a stagger. */
+    readonly maxFallen?: number;
+    /** Damage per second to a fallen body per 70 kg standing on it (default 6). */
+    readonly trampleDps?: number;
+};
+type CrowdMoundOptions = {
+    /** m per cell of a lying body, times build (default 0.28). */
+    readonly bodyThickness?: number;
+    /** Default 0.25. */
+    readonly corpseThickness?: number;
+    /** Ceiling of the mound per cell, m (default 1.6, about 5 or 6 bodies). */
+    readonly maxHeight?: number;
+    /** Corpses within this distance of the band centre count (default 35, band R0). */
+    readonly corpseRadius?: number;
+};
+type CrowdThrownOptions = {
+    /** Slots of the pool (default 32, at most 127). */
+    readonly pool?: number;
+    /** Only within this distance of the band centre (default 30 m). */
+    readonly radius?: number;
+    /** m around the landing point that is knocked (default 1.2: a body at 10 m/s knocks the ones within about two body widths; 0.7 left the chain beyond a grenade at 0 in 4 of 12 scenes). */
+    readonly landingRadius?: number;
+    /** Damage per m/s of landing speed above 6 m/s (default 8). */
+    readonly fallDamage?: number;
+    /** Who gets a slot when there are more candidates than slots: half the slots to the fastest and half to the nearest to the band centre (`'mixed'`, default), or only one criterion. */
+    readonly priority?: 'mixed' | 'fastest' | 'nearest';
+    /** Share of the slots that goes to the fastest in `'mixed'` (default 0.5). */
+    readonly mixedRatio?: number;
+};
+type CrowdBlastOptions = {
+    /** Damage at the centre per kJ before falloff (default 0.6 → m67 120 points). */
+    readonly pointsPerKilojoule?: number;
+    /** Shove speed from which a body flies, m/s (default 4). */
+    readonly throwSpeed?: number;
+    /** Blasts resolved in one fixed step; more wait for the next one, in order (default 8). */
+    readonly maxBlastsPerStep?: number;
+    /** `limb` effects per blast; the rest is summed into one blood effect (default 24). */
+    readonly limbEffectsPerBlast?: number;
+    /** `blood` effects per blast (default 32). */
+    readonly bloodEffectsPerBlast?: number;
+    /** The shove rule of `game-contracts`, the same numbers the host lends to the items and the furniture. */
+    readonly shove?: BlastShoveOptions;
+};
+type CrowdPersonalityOptions = {
+    /** Chase and wander factor (default [0.9, 1.1]). */
+    readonly speed?: readonly [number, number];
+    /** Seconds added to getting up and to the alert hop (default [0.05, 0.35]). */
+    readonly reaction?: readonly [number, number];
+    readonly stability?: readonly [number, number];
+    readonly trip?: readonly [number, number];
+    /** Pushing will (default [0.7, 1.3]). */
+    readonly drive?: readonly [number, number];
+    /** Walk cadence factor (default [0.85, 1.15]). */
+    readonly cadence?: readonly [number, number];
+    /** Attack will (default [0.8, 1.2]): divides `attackEvery`, multiplies the bite chance and decides who gets the last attack slots. */
+    readonly aggression?: readonly [number, number];
+    /** Weights of sway, shuffle, head twitch, still (default [3, 2, 2, 1]). */
+    readonly idle?: readonly number[];
+};
+/** Band R1, summarised (D10, `design-chain-horde.md` §9): no pairs, a coarse grid of bodies per cell. */
+type CrowdDensityOptions = {
+    /** Side of a coarse cell, m (default 2). */
+    readonly cell?: number;
+    /** Bodies per cell that walk freely (default 4, one per square metre); above it the speed is `capacity / bodies`. */
+    readonly capacity?: number;
+    /** N of pressure per body above `capacity` (default 150). */
+    readonly pressurePerBody?: number;
+};
+/** Pressure of the horde on the target (D13.2): above `knockThreshold` N it knocks the target down; the excess crushes at `crushDamagePerSecond`. */
+type CrowdPlayerPressureOptions = {
+    readonly enabled?: boolean;
+    readonly knockThreshold?: number;
+    readonly crushDamagePerSecond?: number;
+};
+type CrowdPhysicsOptions = {
+    readonly contact?: CrowdContactOptions | boolean;
+    /** Needs `contact`. */
+    readonly pressure?: CrowdPressureOptions | boolean;
+    /** Needs `contact`. */
+    readonly balance?: CrowdBalanceOptions | boolean;
+    /** Needs `balance`. */
+    readonly mound?: CrowdMoundOptions | boolean;
+    /** Needs `balance`. */
+    readonly thrown?: CrowdThrownOptions | boolean;
+    /** Needs `balance`. The far band without pairs: speed and pressure from the bodies per coarse cell. */
+    readonly density?: CrowdDensityOptions | boolean;
+    readonly blast?: CrowdBlastOptions;
+    readonly personality?: CrowdPersonalityOptions | boolean;
+    readonly door?: {
+        readonly pressureDamage?: number;
+    };
+    /** Needs `pressure`. Off in the package; a game turns it on. */
+    readonly playerPressure?: CrowdPlayerPressureOptions;
+    /** Flow budget in cells per step, `attackPose` in the simulation, positions kept for interpolation. */
+    readonly deterministic?: boolean;
+    /**
+     * Where the contact and the pressure run. `'off'` (default): in the step, exactly as before. `'on'`: in a worker, one step behind (the main thread applies what the worker
+     * computed from the previous step), and an error when no worker can be made. `'auto'`: the same when a worker can be made, `'off'` when it cannot. Needs `contact`.
+     */
+    readonly worker?: 'off' | 'auto' | 'on';
+    /** Makes the worker (default: a module worker that loads `physics-worker.js` next to the bundle). A host that bundles its own worker gives the factory and calls `attachPhysicsWorker` in it. */
+    readonly workerFactory?: PhysicsWorkerFactory;
+    /** `'shared'` (a `SharedArrayBuffer`, deterministic, needs `crossOriginIsolated`), `'transfer'` (`postMessage`, any host, the answer is as late as the event loop makes it), `'inline'` (no worker: the same protocol on the main thread, the reference). Default: `'shared'` when it is available, else `'transfer'`. */
+    readonly workerTransport?: OffloadTransport;
+    /** Steps between the state the worker is handed and the step that applies its answer (default 1). 2 gives the worker a whole step to finish in, so the main thread never waits for it, and costs one more step of lag in the contact. */
+    readonly workerLatency?: 1 | 2;
+};
+/** Everything on, deterministic, the numbers of the design (`design-chain-horde.md`); the player pressure stays off, a game turns it on. */
+declare const CROWD_PHYSICS_DEFAULTS: CrowdPhysicsOptions;
+type ResolvedPhysics = {
+    readonly contact: Required<CrowdContactOptions> | null;
+    readonly pressure: Required<CrowdPressureOptions> | null;
+    readonly balance: Required<CrowdBalanceOptions> | null;
+    readonly mound: Required<CrowdMoundOptions> | null;
+    readonly thrown: Required<CrowdThrownOptions> | null;
+    readonly density: Required<CrowdDensityOptions> | null;
+    readonly blast: Required<CrowdBlastOptions>;
+    readonly personality: Required<CrowdPersonalityOptions> | null;
+    readonly doorPressureDamage: number;
+    readonly playerPressure: Required<CrowdPlayerPressureOptions>;
+    readonly deterministic: boolean;
+    readonly worker: 'off' | 'auto' | 'on';
+    readonly workerFactory: PhysicsWorkerFactory | undefined;
+    readonly workerTransport: OffloadTransport | undefined;
+    readonly workerLatency: 1 | 2;
+};
+/** Reads `CrowdOptions.physics`: the defaults filled in, and a thrown error that lists every part whose dependency is missing. */
+declare function resolvePhysics(physics?: CrowdPhysicsOptions): ResolvedPhysics;
+
 /**
  * The agents as a struct of arrays (G 66717 `Z`, ZMAX 6000): one typed array per field, the same types as the game so the floats round the same way.
  * The names are the game's in English; `armHp` and `legHp` hold two values per agent (left, right).
@@ -240,10 +437,40 @@ declare const createStore: (capacity: number) => {
     variant: Uint8Array<ArrayBuffer>;
     attackPose: Uint8Array<ArrayBuffer>;
     arms: Float32Array<ArrayBuffer>;
+    stepDir: Int32Array<ArrayBuffer>;
+    pushX: Float32Array<ArrayBuffer>;
+    pushZ: Float32Array<ArrayBuffer>;
+    mass: Float32Array<ArrayBuffer>;
+    pressure: Float32Array<ArrayBuffer>;
+    field: Float32Array<ArrayBuffer>;
+    fieldPrev: Float32Array<ArrayBuffer>;
+    aimX: Float32Array<ArrayBuffer>;
+    aimZ: Float32Array<ArrayBuffer>;
+    directShove: Float32Array<ArrayBuffer>;
+    blastStep: Int32Array<ArrayBuffer>;
+    balance: Uint8Array<ArrayBuffer>;
+    balanceTimer: Float32Array<ArrayBuffer>;
+    fallCause: Uint8Array<ArrayBuffer>;
+    identity: Uint32Array<ArrayBuffer>;
+    stability: Float32Array<ArrayBuffer>;
+    tripFactor: Float32Array<ArrayBuffer>;
+    driveFactor: Float32Array<ArrayBuffer>;
+    reaction: Float32Array<ArrayBuffer>;
+    cadenceFactor: Float32Array<ArrayBuffer>;
+    aggression: Float32Array<ArrayBuffer>;
+    idle: Uint8Array<ArrayBuffer>;
+    gaitStyle: Uint8Array<ArrayBuffer>;
+    wounds: Uint16Array<ArrayBuffer>;
+    leanX: Float32Array<ArrayBuffer>;
+    leanZ: Float32Array<ArrayBuffer>;
+    thrown: Int8Array<ArrayBuffer>;
+    prevX: Float32Array<ArrayBuffer>;
+    prevZ: Float32Array<ArrayBuffer>;
+    prevY: Float32Array<ArrayBuffer>;
 };
 type CrowdStore = ReturnType<typeof createStore>;
 /** The one-per-agent fields (G 66733 `FIELDS`): what a removal copies from the last agent. */
-declare const AGENT_FIELDS: readonly ["x", "z", "vx", "vz", "yaw", "phase", "type", "age", "outfit", "height", "build", "chaseSpeed", "wanderSpeed", "hp", "hpMax", "headHp", "missing", "helmet", "state", "stateTimer", "lost", "attackTimer", "band", "next", "wx", "wz", "crawl", "limp", "color", "skin", "alertIn", "cooldown", "y", "floor", "floorLocked", "vy", "abilityTimer", "eaten", "stuck", "stepCell", "burn", "hunts", "named", "dvx", "dvz", "steering", "renderYaw", "renderSpeed", "pause", "lod", "variant", "attackPose", "arms"];
+declare const AGENT_FIELDS: readonly ["x", "z", "vx", "vz", "yaw", "phase", "type", "age", "outfit", "height", "build", "chaseSpeed", "wanderSpeed", "hp", "hpMax", "headHp", "missing", "helmet", "state", "stateTimer", "lost", "attackTimer", "band", "next", "wx", "wz", "crawl", "limp", "color", "skin", "alertIn", "cooldown", "y", "floor", "floorLocked", "vy", "abilityTimer", "eaten", "stuck", "stepCell", "burn", "hunts", "named", "dvx", "dvz", "steering", "renderYaw", "renderSpeed", "pause", "lod", "variant", "attackPose", "arms", "stepDir", "pushX", "pushZ", "mass", "pressure", "field", "fieldPrev", "aimX", "aimZ", "directShove", "blastStep", "balance", "balanceTimer", "fallCause", "identity", "stability", "tripFactor", "driveFactor", "reaction", "cadenceFactor", "aggression", "idle", "gaitStyle", "wounds", "leanX", "leanZ", "thrown", "prevX", "prevZ", "prevY"];
 
 /** What an agent is doing (G 66724 and 67180-67183): the store keeps the number. */
 declare const STATE: {
@@ -260,6 +487,24 @@ declare const STATE: {
     readonly PILE_STEP: 10;
     readonly SEEKING_SOUND: 12;
 };
+/** Balance of an agent (physics): a state machine of its own, apart from `STATE`, so the game's behaviour machine stays as it is. */
+declare const BALANCE: {
+    readonly STANDING: 0;
+    readonly STAGGERING: 1;
+    readonly FALLEN: 2;
+    readonly GETTING_UP: 3;
+    readonly THROWN: 4;
+};
+/** Why an agent went down (index `cause - 1` in `stats.physics.falls`). */
+declare const FALL_CAUSE: {
+    readonly NONE: 0;
+    readonly PRESSURE: 1;
+    readonly SHOVE: 2;
+    readonly TRIP: 3;
+    readonly LANDING: 4;
+    readonly COLLAPSE: 5;
+    readonly BLAST: 6;
+};
 /** Body regions of a hit (G 67012): 0 head, 1 torso, 2 left arm, 3 right arm, 4 left leg, 5 right leg. */
 type Region = 0 | 1 | 2 | 3 | 4 | 5;
 /**
@@ -436,6 +681,31 @@ type CrowdType = {
     readonly variants?: number;
     readonly eye?: number;
     readonly traits?: CrowdTraits;
+    /** How the body takes a push (physics only; a type without it uses the defaults). */
+    readonly balance?: CrowdBalanceTraits;
+};
+type CrowdBalanceTraits = {
+    /** Multiplies the critical pressure (default 1). */
+    readonly stability?: number;
+    /** Chance of tripping when entering a cell with a body (default 0.04). */
+    readonly trip?: number;
+    /** Force of its will against what is in front, in N (default 250). */
+    readonly driveForce?: number;
+    /** False: already on the ground (a crawler). */
+    readonly canFall?: boolean;
+};
+/** A blast as the crowd reads it. */
+type CrowdBlast = {
+    readonly point: readonly [number, number, number];
+    /** J. */
+    readonly energy: number;
+    /** m, how far it hurts. */
+    readonly radius: number;
+    /** m, everything inside dies. */
+    readonly lethalRadius?: number;
+    readonly source?: string;
+    /** Id of the chain this blast belongs to (game-destruction `chain`), for the counters. */
+    readonly chain?: string;
 };
 /** The age of a body (G IDADES): its share, and what it does to speed, health, limbs and senses. */
 type CrowdAge = {
@@ -570,20 +840,24 @@ type CrowdEventMap = {
         x: number;
         z: number;
     };
+    fall: {
+        agent: number;
+        cause: number;
+        x: number;
+        z: number;
+        identity: number;
+    };
+    blasted: {
+        point: [number, number, number];
+        radius: number;
+        reached: number;
+        killed: number;
+        thrown: number;
+        fallen: number;
+        chain?: string;
+    };
 };
 type CrowdEventName = keyof CrowdEventMap;
-
-type CrowdNumbers = typeof defaults.numbers;
-type CrowdBand = {
-    readonly max: number;
-    readonly dt: number;
-};
-/** The game's numbers; `bands[3].max` is `Infinity` (JSON keeps it as null). */
-declare const CROWD_DEFAULTS: {
-    readonly sources: Readonly<Record<string, string>>;
-    readonly bands: readonly CrowdBand[];
-    readonly numbers: CrowdNumbers;
-};
 /** A body on the ground (G 67062 `CP`). */
 type Corpse = {
     readonly x: number;
@@ -599,6 +873,116 @@ type Corpse = {
     readonly seed: number;
     readonly named: number;
 };
+
+/** Counters of the physics, all zero with it off (`crowd.stats.physics`). */
+type PhysicsStats = {
+    contacts: number;
+    maxOverlap: number;
+    meanOverlap: number;
+    /** Falls by cause: pressure, shove, trip, landing, collapse, blast. */
+    falls: [pressure: number, shove: number, trip: number, landing: number, collapse: number, blast: number];
+    /** Chain falls: shove, landing, collapse or trip within 240 steps of a blast, of an agent whose own direct shove from it was below `shoveStagger`. */
+    fallsBeyondBlast: number;
+    fallen: number;
+    staggering: number;
+    climbers: number;
+    moundMax: number;
+    thrownActive: number;
+    thrownPeak: number;
+    blastChecks: number;
+    chainLinks: number;
+    /** The highest field of the step, N: the front of a column, or the funnel of a door. */
+    fieldMax: number;
+    /** The pressure of the horde on the target, N (exponential mean). */
+    playerPressure: number;
+};
+
+type ContactParams = Required<CrowdContactOptions> & {
+    readonly h: number;
+};
+type ContactResult = {
+    contacts: number;
+    maxOverlap: number;
+    overlapSum: number;
+};
+type ContactWorkspace = {
+    readonly head: Int32Array;
+    readonly next: Int32Array;
+    readonly touched: Int32Array;
+    touchedCount: number;
+    readonly pairI: Int32Array;
+    readonly pairJ: Int32Array;
+    pairCount: number;
+    readonly deltaX: Float32Array;
+    readonly deltaZ: Float32Array;
+    readonly count: Uint8Array;
+    readonly pushBeforeX: Float32Array;
+    readonly pushBeforeZ: Float32Array;
+    /** |Δpush| the contact gave to each agent in the last step. */
+    readonly shove: Float32Array;
+    /** 1 for the agents that take part in the contact this step (`takesPartInContact`), read once. */
+    readonly takesPart: Uint8Array;
+    /** The radius and the effective mass of each agent this step, in doubles: the balance does not change inside the contact step. */
+    readonly radiusOf: Float64Array;
+    readonly massOf: Float64Array;
+    /** Per pair, valid for the positions of the current iteration: the reach, the distance, and the normal (only meaningful when the distance is under the reach) from `j` to `i`. */
+    readonly pairReach: Float64Array;
+    readonly pairDistance: Float64Array;
+    readonly pairNormalX: Float64Array;
+    readonly pairNormalZ: Float64Array;
+};
+/** The arrays the contact and the pressure read and write: the step needs no more of the store, so it can run over a copy of them (a worker). */
+type PhysicsStore = Pick<CrowdStore, 'x' | 'z' | 'y' | 'vx' | 'vz' | 'pushX' | 'pushZ' | 'mass' | 'build' | 'balance' | 'state' | 'band' | 'identity' | 'aimX' | 'aimZ' | 'field' | 'fieldPrev' | 'type' | 'driveFactor'>;
+type PhysicsGrid = Pick<NavGrid, 'size' | 'half' | 'occ' | 'cellOf'>;
+type ContactView = {
+    n: number;
+    readonly store: PhysicsStore;
+    readonly grid: PhysicsGrid;
+    readonly workspace: ContactWorkspace;
+};
+declare const createContactView: (store: PhysicsStore, grid: PhysicsGrid) => ContactView;
+/**
+ * One fixed step of contact in band R0 (`design-chain-horde.md` §4.3): `iterations` rounds of a symmetric Gauss-Seidel impulse (the pairs forward, then backward, so
+ * a low index has no advantage) and a Jacobi position correction (the mean of what each agent was asked to move), then the damping of the push.
+ * It resolves overlap and shock only: pressure is the field of `pressure.ts`. An inelastic impulse never adds energy, and the correction never touches the velocity.
+ */
+declare function contactStep(view: ContactView, params: ContactParams, out: ContactResult): void;
+
+/** The thrown bodies, simulated here and only read by the renderer (`x`, `y`, `z` are the centre of the body, `prev*` the position of the step before). */
+type ThrownPool = {
+    readonly size: number;
+    /** An agent index, `CARRIED_BODY` for a dead body carried until it lands, `FREE_SLOT` for an empty slot. */
+    readonly agent: Int32Array;
+    readonly identity: Uint32Array;
+    readonly corpse: (Corpse | null)[];
+    readonly x: Float32Array;
+    readonly y: Float32Array;
+    readonly z: Float32Array;
+    readonly prevX: Float32Array;
+    readonly prevY: Float32Array;
+    readonly prevZ: Float32Array;
+    readonly vx: Float32Array;
+    readonly vy: Float32Array;
+    readonly vz: Float32Array;
+    readonly pitch: Float32Array;
+    readonly roll: Float32Array;
+    readonly spinPitch: Float32Array;
+    readonly spinRoll: Float32Array;
+    active(): number;
+};
+
+type CrowdNumbers = typeof defaults.numbers;
+type CrowdBand = {
+    readonly max: number;
+    readonly dt: number;
+};
+/** The game's numbers; `bands[3].max` is `Infinity` (JSON keeps it as null). */
+declare const CROWD_DEFAULTS: {
+    readonly sources: Readonly<Record<string, string>>;
+    readonly bands: readonly CrowdBand[];
+    readonly numbers: CrowdNumbers;
+};
+
 /** A custom move: runs on every decision tick after the timed states and before the moves on the target; `true` means it took care of the movement. */
 type CrowdPlugin = {
     readonly id: string;
@@ -635,10 +1019,13 @@ type CrowdOptions = {
     /** Flow field: half window in cells (192), and the clock its time budget reads (default `performance.now`; pass `() => 0` to finish every field in one frame). */
     readonly flow?: {
         readonly radius?: number;
-        readonly clock?: () => number;
+        readonly clock?: () => number; /** Flow budget in cells per step instead of the clock: the same field at any frame rate (`physics.deterministic` sets 20000). */
+        readonly cellsPerStep?: number;
     };
     readonly plugins?: readonly CrowdPlugin[];
     readonly target?: CrowdTarget | null;
+    /** Contact, pressure, balance, mounds, thrown bodies and personality: all off by default, and then the horde is the game's, bit for bit. */
+    readonly physics?: CrowdPhysicsOptions;
 };
 type CrowdView = {
     readonly x: number;
@@ -654,6 +1041,8 @@ type CrowdUpdateContext = {
     readonly flowTarget?: readonly [number, number];
     /** Where the viewer looks (yaw: forward is `(-sin, -cos)`); the stalker wakes when the target turns its back. Default: the target's view. */
     readonly viewYaw?: number;
+    /** Centre of the relevance bands, for scenes without a player near the agents (tests, benches, cutscenes). Default: the target, or `flowTarget` without one. */
+    readonly bandCentre?: readonly [number, number];
 };
 type Crowd = {
     readonly store: CrowdStore;
@@ -667,9 +1056,16 @@ type Crowd = {
         slots: number;
         kills: number;
         heads: number;
+        physics: PhysicsStats;
     };
     /** Height of the bodies piled per grid cell. */
     readonly pile: Float32Array;
+    /** Millimetres of lying bodies per navigation cell, recomputed every fixed step (empty with `physics.mound` off). */
+    readonly mound: Uint16Array;
+    /** The thrown bodies of a blast, simulated here and only drawn by the renderer (empty with `physics.thrown` off). */
+    readonly thrown: ThrownPool;
+    /** A blast: queued, and resolved at the start of the next step in one pass over the agents. Without `physics` it only hurts, kills and stuns. */
+    blast(blast: CrowdBlast): void;
     /** How many agents are steps of a pile now. */
     pileCount(): number;
     readonly trail: {
@@ -690,6 +1086,7 @@ type Crowd = {
     spawn(x: number, z: number, type?: number): number;
     remove(i: number): void;
     update(dt: number, context?: CrowdUpdateContext): void;
+    dispose(): void;
     emitNoise(x: number, z: number, radius: number): void;
     damage(i: number, hit: CrowdHit): CrowdDamageResult;
     kill(i: number, headshot?: boolean): void;
@@ -1125,4 +1522,25 @@ type InfectionBinding = {
  */
 declare function bindInfection(crowd: Crowd, model: InfectionModelLike, options: InfectionBindingOptions): InfectionBinding;
 
-export { AGENT_FIELDS, CELL, CIVILIAN_DEFAULTS, CROWD_DEFAULTS, type Civilian, type CivilianBuilding, type CivilianEventMap, type CivilianEventName, type CivilianNumbers, type CivilianOptions, type CivilianSpec, type CivilianState, type Civilians, type Corpse, type Crowd, type CrowdAge, type CrowdBand, type CrowdCaliber, type CrowdDamageResult, type CrowdEffectId, type CrowdEventMap, type CrowdEventName, type CrowdHit, type CrowdMessageId, type CrowdNumbers, type CrowdOptions, type CrowdOutfit, type CrowdPack, type CrowdPlugin, type CrowdSoundId, type CrowdStore, type CrowdTarget, type CrowdTraits, type CrowdType, type CrowdUpdateContext, type CrowdView, DOOR_DEFAULTS, type Door, type DoorEventMap, type DoorEventName, type DoorNumbers, type Doors, type Flock, type FlockBird, type FlockMode, type FlockOptions, HERD_DEFAULTS, HERD_ROLES, type Herd, type HerdAnimal, type HerdAnimalSpec, type HerdEventMap, type HerdEventName, type HerdNumbers, type HerdOptions, type HerdRole, type InfectionBinding, type InfectionBindingOptions, type InfectionModelLike, MISSING, type MigrationOptions, type NavGrid, type NavGridOptions, type PlayerCrowdLike, type Region, STATE, bindInfection, carrionCenter, createCivilians, createCrowd, createDoors, createFlock, createHerd, createNavGrid, createRng, createStore };
+/** murmur3 fmix32: a full avalanche of the 32 bits. */
+declare const mix32: (value: number) => number;
+/**
+ * 0..1 from an identity, a step and a salt: the counter-based draw every physics feature uses (never the shared `random` stream, whose order is the game's).
+ * The salt goes in before the step so two different `(step, salt)` pairs never share an input.
+ */
+declare const unit: (identity: number, step: number, salt: number) => number;
+/** The identity of the `serial`-th agent born into a crowd seeded with `seed`. */
+declare const identityOf: (seed: number, serial: number) => number;
+
+/** What a worker thread has to offer: browsers and node give it different shapes, so the host adapts them. */
+type WorkerPort = {
+    postMessage(message: unknown, transfer?: ArrayBuffer[]): void;
+    onMessage(listener: (data: unknown) => void): void;
+};
+/**
+ * The worker side: builds the kernel on `init`, then either loops on the shared control word (shared transport) or answers each transferred frame.
+ * A host that loads the worker its own way (a bundler, node `worker_threads`) calls this with its port.
+ */
+declare function attachPhysicsWorker(port: WorkerPort): void;
+
+export { AGENT_FIELDS, BALANCE, CELL, CIVILIAN_DEFAULTS, CROWD_DEFAULTS, CROWD_PHYSICS_DEFAULTS, type Civilian, type CivilianBuilding, type CivilianEventMap, type CivilianEventName, type CivilianNumbers, type CivilianOptions, type CivilianSpec, type CivilianState, type Civilians, type ContactParams, type ContactResult, type ContactView, type Corpse, type Crowd, type CrowdAge, type CrowdBalanceOptions, type CrowdBalanceTraits, type CrowdBand, type CrowdBlast, type CrowdBlastOptions, type CrowdCaliber, type CrowdContactOptions, type CrowdDamageResult, type CrowdDensityOptions, type CrowdEffectId, type CrowdEventMap, type CrowdEventName, type CrowdHit, type CrowdMessageId, type CrowdMoundOptions, type CrowdNumbers, type CrowdOptions, type CrowdOutfit, type CrowdPack, type CrowdPersonalityOptions, type CrowdPhysicsOptions, type CrowdPlayerPressureOptions, type CrowdPlugin, type CrowdPressureOptions, type CrowdSoundId, type CrowdStore, type CrowdTarget, type CrowdThrownOptions, type CrowdTraits, type CrowdType, type CrowdUpdateContext, type CrowdView, DOOR_DEFAULTS, type Door, type DoorEventMap, type DoorEventName, type DoorNumbers, type Doors, FALL_CAUSE, type Flock, type FlockBird, type FlockMode, type FlockOptions, HERD_DEFAULTS, HERD_ROLES, type Herd, type HerdAnimal, type HerdAnimalSpec, type HerdEventMap, type HerdEventName, type HerdNumbers, type HerdOptions, type HerdRole, type InfectionBinding, type InfectionBindingOptions, type InfectionModelLike, MISSING, type MigrationOptions, type NavGrid, type NavGridOptions, type OffloadTransport, type PhysicsStats, type PhysicsWorkerFactory, type PhysicsWorkerHandle, type PlayerCrowdLike, type Region, type ResolvedPhysics, STATE, type ThrownPool, type WorkerPort, attachPhysicsWorker, bindInfection, carrionCenter, contactStep, createCivilians, createContactView, createCrowd, createDoors, createFlock, createHerd, createNavGrid, createRng, createStore, identityOf, mix32, resolvePhysics, unit };