@netforge/engine 0.0.0-stage → 0.1.0

package/dist/runtime/camera.js

@@ -0,0 +1,247 @@
+import { PerspectiveCamera, Vector3 } from "three/webgpu";
+import { Spring, stepSpring } from "./feel/spring.js";
+import { Trauma } from "./feel/trauma.js";
+import { damp } from "./interpolate.js";
+/** Square bounds around the origin: a field of half size `half` plus `margin` of outside ground. */
+export function fieldBounds(half, margin = 0) {
+    const h = half + margin;
+    return { minX: -h, maxX: h, minZ: -h, maxZ: h };
+}
+const CORNERS = [
+    [-1, -1],
+    [1, -1],
+    [1, 1],
+    [-1, 1],
+];
+const _a = new Vector3();
+const _b = new Vector3();
+/**
+ * The ground a camera sees: the box around where its four corner rays meet
+ * the plane y = `groundY`. A ray at or above the horizon counts as reaching
+ * `reach` m out along the ground. The camera's matrices must be current.
+ */
+export function groundFootprint(camera, groundY = 0, reach = 400) {
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minZ = Infinity;
+    let maxZ = -Infinity;
+    const origin = _a.setFromMatrixPosition(camera.matrixWorld);
+    const ox = origin.x;
+    const oy = origin.y;
+    const oz = origin.z;
+    for (const [x, y] of CORNERS) {
+        const p = _b.set(x, y, 0.5).unproject(camera);
+        let dx = p.x - ox;
+        const dy = p.y - oy;
+        let dz = p.z - oz;
+        let t;
+        if (dy < -1e-6 && oy > groundY)
+            t = (groundY - oy) / dy;
+        else {
+            // Above the horizon: as far as `reach` along the ground.
+            const flat = Math.hypot(dx, dz) || 1;
+            dx /= flat;
+            dz /= flat;
+            t = reach;
+        }
+        const gx = ox + dx * t;
+        const gz = oz + dz * t;
+        if (gx < minX)
+            minX = gx;
+        if (gx > maxX)
+            maxX = gx;
+        if (gz < minZ)
+            minZ = gz;
+        if (gz > maxZ)
+            maxZ = gz;
+    }
+    return { minX, maxX, minZ, maxZ };
+}
+/**
+ * How far to move a view so `seen` stays inside `bounds`, per axis: zero
+ * when it already fits, the overshoot when it pokes out of one side, and
+ * centring when it is wider than the bounds.
+ */
+export function boundsShift(seen, bounds) {
+    const axis = (lo, hi, min, max) => {
+        if (hi - lo >= max - min)
+            return (min + max) / 2 - (lo + hi) / 2;
+        if (lo < min)
+            return min - lo;
+        if (hi > max)
+            return max - hi;
+        return 0;
+    };
+    return { x: axis(seen.minX, seen.maxX, bounds.minX, bounds.maxX), z: axis(seen.minZ, seen.maxZ, bounds.minZ, bounds.maxZ) };
+}
+/**
+ * Third-person orbit-follow camera with the camera parts of the feel kit:
+ * critically damped follow, smoothed and clamped lead, a dead zone, trauma
+ * shake and FOV punches. `yaw` matches the sim's convention (0 looks down
+ * -z), so the input layer can send the camera's yaw as the character's
+ * facing. Shake is applied as a per-frame `offset` and `roll` on top of the
+ * computed pose, so it never accumulates drift.
+ */
+export class CameraRig {
+    camera;
+    yaw = 0;
+    pitch = 0.45;
+    /** Trauma shake (add with `addTrauma`). */
+    trauma;
+    /** This frame's shake offset (world, m) and roll (rad). */
+    offset = new Vector3();
+    roll = 0;
+    focus = new Vector3();
+    focusVel = new Vector3();
+    lastTarget = new Vector3();
+    vel = new Vector3();
+    leadVec = new Vector3();
+    fovSpring;
+    initialised = false;
+    o;
+    bounds;
+    /** This frame's clamp shift (m, ground plane): non-zero while the bounds hold the camera back. */
+    clampShift = { x: 0, z: 0 };
+    constructor(aspect, opts = {}) {
+        this.o = {
+            distance: 9,
+            height: 1.2,
+            minPitch: -0.2,
+            maxPitch: 1.35,
+            follow: 12,
+            lead: 0.15,
+            leadMax: 6,
+            leadSmoothing: 10,
+            deadZone: 0,
+            fov: 60,
+            punchFrequency: 4,
+            punchDamping: 0.55,
+            groundY: 0,
+            ...opts,
+            shake: opts.shake ?? {},
+        };
+        this.bounds = opts.bounds ?? null;
+        this.camera = new PerspectiveCamera(this.o.fov, aspect, 0.1, 500);
+        this.trauma = new Trauma({ maxOffset: 0.6, maxRoll: 0.035, ...this.o.shake });
+        this.fovSpring = new Spring(0, { frequency: this.o.punchFrequency, damping: this.o.punchDamping });
+    }
+    /** Camera distance from the focus, m (e.g. pull back on a portrait phone). */
+    setDistance(metres) {
+        this.o.distance = metres;
+    }
+    /** Keep the visible ground inside `bounds` (null lets the camera follow anywhere). */
+    setBounds(bounds) {
+        this.bounds = bounds;
+    }
+    /** The point the camera looks at (after follow and lead). */
+    get target() {
+        return this.focus;
+    }
+    /** Apply look input (radians). */
+    look(dYaw, dPitch) {
+        this.yaw += dYaw;
+        this.pitch = Math.min(this.o.maxPitch, Math.max(this.o.minPitch, this.pitch + dPitch));
+    }
+    /** Add trauma 0..1 (game feel, §13): the shake is trauma squared, so small hits barely move it. */
+    addTrauma(amount) {
+        this.trauma.add(amount);
+    }
+    /** The classic shake: about `amplitude` m of shake held for `seconds`, then fading. */
+    shake(amplitude, seconds) {
+        this.trauma.add(this.trauma.traumaFor(amplitude));
+        this.trauma.sustain(seconds * 0.5);
+    }
+    /** Kick the field of view by `degrees` (negative zooms in) and spring back. */
+    punch(degrees) {
+        this.fovSpring.value = Math.max(-20, Math.min(20, this.fovSpring.value + degrees));
+    }
+    /** Current FOV offset from the punch spring, degrees. */
+    get fovKick() {
+        return this.fovSpring.value;
+    }
+    /**
+     * Follow `target`. `dt` is the (hit-stop scaled) frame delta; pass
+     * `realDt` so shake and punches keep moving during a hit-stop.
+     */
+    update(target, dt, realDt = dt) {
+        if (!this.initialised) {
+            this.focus.copy(target);
+            this.lastTarget.copy(target);
+            this.initialised = true;
+        }
+        if (dt > 0) {
+            this.vel.subVectors(target, this.lastTarget).divideScalar(dt);
+            this.lastTarget.copy(target);
+            // Lead: velocity times lead seconds, clamped, then smoothed.
+            let lx = this.vel.x * this.o.lead;
+            let lz = this.vel.z * this.o.lead;
+            const len = Math.hypot(lx, lz);
+            if (len > this.o.leadMax) {
+                lx *= this.o.leadMax / len;
+                lz *= this.o.leadMax / len;
+            }
+            const k = this.o.leadSmoothing > 0 ? damp(this.o.leadSmoothing, dt) : 1;
+            this.leadVec.x += (lx - this.leadVec.x) * k;
+            this.leadVec.z += (lz - this.leadVec.z) * k;
+        }
+        let goalX = target.x + this.leadVec.x;
+        let goalZ = target.z + this.leadVec.z;
+        const goalY = target.y + this.o.height;
+        if (this.o.deadZone > 0) {
+            const dx = goalX - this.focus.x;
+            const dz = goalZ - this.focus.z;
+            const d = Math.hypot(dx, dz);
+            if (d <= this.o.deadZone) {
+                goalX = this.focus.x;
+                goalZ = this.focus.z;
+            }
+            else {
+                const s = (d - this.o.deadZone) / d;
+                goalX = this.focus.x + dx * s;
+                goalZ = this.focus.z + dz * s;
+            }
+        }
+        if (dt > 0) {
+            const w = 2 * this.o.follow;
+            [this.focus.x, this.focusVel.x] = stepSpring(this.focus.x, this.focusVel.x, goalX, w, 1, dt);
+            [this.focus.y, this.focusVel.y] = stepSpring(this.focus.y, this.focusVel.y, goalY, w, 1, dt);
+            [this.focus.z, this.focusVel.z] = stepSpring(this.focus.z, this.focusVel.z, goalZ, w, 1, dt);
+        }
+        // Shake and punch run on real time.
+        this.trauma.update(realDt);
+        this.fovSpring.step(realDt);
+        const cy = Math.cos(this.yaw);
+        const sy = Math.sin(this.yaw);
+        // Camera right is (cos yaw, 0, -sin yaw); shake moves it sideways and up.
+        this.offset.set(cy * this.trauma.x, this.trauma.y, -sy * this.trauma.x);
+        this.roll = this.trauma.roll;
+        const cp = Math.cos(this.pitch);
+        const d = this.o.distance;
+        this.camera.position.set(this.focus.x + sy * cp * d + this.offset.x, this.focus.y + Math.sin(this.pitch) * d + this.offset.y, this.focus.z + cy * cp * d + this.offset.z);
+        this.camera.lookAt(this.focus.x + this.offset.x, this.focus.y + this.offset.y, this.focus.z + this.offset.z);
+        this.clampShift.x = 0;
+        this.clampShift.z = 0;
+        if (this.bounds) {
+            // Clamp on the un-shaken pose, so a shake near a wall still shakes.
+            this.camera.position.sub(this.offset);
+            this.camera.updateMatrixWorld();
+            const shift = boundsShift(groundFootprint(this.camera, this.o.groundY), this.bounds);
+            this.clampShift.x = shift.x;
+            this.clampShift.z = shift.z;
+            this.camera.position.add(this.offset);
+            this.camera.position.x += shift.x;
+            this.camera.position.z += shift.z;
+        }
+        if (this.roll !== 0)
+            this.camera.rotateZ(this.roll);
+        const fov = this.o.fov + this.fovSpring.value;
+        if (Math.abs(this.camera.fov - fov) > 1e-4) {
+            this.camera.fov = fov;
+            this.camera.updateProjectionMatrix();
+        }
+    }
+    resize(aspect) {
+        this.camera.aspect = aspect;
+        this.camera.updateProjectionMatrix();
+    }
+}

package/dist/runtime/crowd.d.ts

@@ -0,0 +1,18 @@
+import { InstancedMesh, Material } from "three/webgpu";
+import type { BufferGeometry } from "three/webgpu";
+import type { RenderView } from "@netforge/engine-sim";
+/**
+ * One InstancedMesh per entity kind: 2,000 enemies are one draw call
+ * (spec §5). Each frame writes interpolated matrices straight into the
+ * instance buffer (rotation about y only; no per-instance Object3D).
+ */
+export declare class InstancedCrowd {
+    private readonly kind;
+    private readonly scale;
+    readonly mesh: InstancedMesh;
+    private readonly capacity;
+    constructor(geometry: BufferGeometry, material: Material, capacity: number, kind: number, scale?: number);
+    /** Write this frame's instances from a sim render view at interpolation `alpha` (0..1). */
+    update(view: RenderView, alpha: number): number;
+    dispose(): void;
+}

package/dist/runtime/crowd.js

@@ -0,0 +1,62 @@
+import { InstancedMesh } from "three/webgpu";
+import { lerp, lerpAngle } from "./interpolate.js";
+/**
+ * One InstancedMesh per entity kind: 2,000 enemies are one draw call
+ * (spec §5). Each frame writes interpolated matrices straight into the
+ * instance buffer (rotation about y only; no per-instance Object3D).
+ */
+export class InstancedCrowd {
+    kind;
+    scale;
+    mesh;
+    capacity;
+    constructor(geometry, material, capacity, kind, scale = 1) {
+        this.kind = kind;
+        this.scale = scale;
+        this.capacity = capacity;
+        this.mesh = new InstancedMesh(geometry, material, capacity);
+        this.mesh.count = 0;
+        // Instances span the whole arena; culling one bounding sphere saves nothing.
+        this.mesh.frustumCulled = false;
+    }
+    /** Write this frame's instances from a sim render view at interpolation `alpha` (0..1). */
+    update(view, alpha) {
+        const m = this.mesh.instanceMatrix.array;
+        const s = this.scale;
+        let n = 0;
+        for (let i = 0; i < view.count && n < this.capacity; i++) {
+            if (view.kind[i] !== this.kind)
+                continue;
+            const x = lerp(view.prevX[i] ?? 0, view.x[i] ?? 0, alpha);
+            const y = lerp(view.prevY[i] ?? 0, view.y[i] ?? 0, alpha);
+            const z = lerp(view.prevZ[i] ?? 0, view.z[i] ?? 0, alpha);
+            const yaw = lerpAngle(view.prevYaw[i] ?? 0, view.yaw[i] ?? 0, alpha);
+            const c = Math.cos(yaw) * s;
+            const sn = Math.sin(yaw) * s;
+            const o = n * 16;
+            m[o] = c;
+            m[o + 1] = 0;
+            m[o + 2] = -sn;
+            m[o + 3] = 0;
+            m[o + 4] = 0;
+            m[o + 5] = s;
+            m[o + 6] = 0;
+            m[o + 7] = 0;
+            m[o + 8] = sn;
+            m[o + 9] = 0;
+            m[o + 10] = c;
+            m[o + 11] = 0;
+            m[o + 12] = x;
+            m[o + 13] = y;
+            m[o + 14] = z;
+            m[o + 15] = 1;
+            n++;
+        }
+        this.mesh.count = n;
+        this.mesh.instanceMatrix.needsUpdate = true;
+        return n;
+    }
+    dispose() {
+        this.mesh.dispose();
+    }
+}

package/dist/runtime/feel/audio.d.ts

@@ -0,0 +1,150 @@
+export interface SynthRecipe {
+    readonly wave: OscillatorType | "noise";
+    /** Start and end frequency, Hz. */
+    readonly f0: number;
+    readonly f1: number;
+    readonly ms: number;
+    readonly gain: number;
+}
+export interface CueOptions {
+    /** Least time between two plays of this cue, ms. Default 40. */
+    readonly minGapMs?: number;
+    /** Random pitch spread, as a fraction (0.08 = plus or minus 8%). Default 0.06. */
+    readonly pitchVar?: number;
+    /** Random gain spread, fraction. Default 0.1. */
+    readonly gainVar?: number;
+    /** Most voices of this cue at once. Default 4. */
+    readonly voices?: number;
+}
+export interface PlayOptions {
+    /** Pitch multiplier (on top of the random variation). */
+    readonly pitch?: number;
+    /** Gain multiplier. */
+    readonly gain?: number;
+    /** Stereo pan -1..1 (wins over screenX). */
+    readonly pan?: number;
+    /** Pan from a screen x position in pixels and the screen width. */
+    readonly screenX?: number;
+    readonly width?: number;
+    /** Distance from the listener, m (inverse falloff past refDistance, silent past maxDistance). */
+    readonly distance?: number;
+}
+/** The built-in cues every template can use by name. */
+export declare const DEFAULT_CUES: Readonly<Record<string, SynthRecipe & CueOptions>>;
+/**
+ * The DOM-free decision core: may a cue start now? Per-cue gap and voice
+ * cap, and a global voice cap.
+ */
+export declare class CueGate {
+    maxVoices: number;
+    private readonly last;
+    private readonly playing;
+    constructor(maxVoices?: number);
+    allow(name: string, nowMs: number, durationMs: number, minGapMs: number, cueVoices: number): boolean;
+    get voices(): number;
+}
+/** Gain for a source `distance` m away (inverse falloff, 0 past maxDistance). */
+export declare function distanceGain(distance: number, refDistance?: number, maxDistance?: number, rolloff?: number): number;
+export interface FeelAudioOptions {
+    /** Master gain 0..1. Default 0.18. */
+    readonly master?: number;
+    /** Most voices at once across all cues. Default 16. */
+    readonly voices?: number;
+    readonly refDistance?: number;
+    readonly maxDistance?: number;
+    /** Build the context (tests pass a fake). Default `new AudioContext()`. */
+    readonly context?: () => AudioContext;
+    /** Clock in ms (tests). Default performance.now. */
+    readonly now?: () => number;
+    /** Seed for pitch and gain variation. */
+    readonly seed?: number;
+}
+export declare class FeelAudio {
+    muted: boolean;
+    /** Cues actually started (playtest counters). */
+    played: number;
+    readonly gate: CueGate;
+    private ctx;
+    private masterNode;
+    private noise;
+    private masterGain;
+    private readonly cues;
+    private readonly unlocked;
+    private readonly rnd;
+    private readonly o;
+    constructor(opts?: FeelAudioOptions);
+    /** Start WebAudio (call from a user gesture; browsers block audio before one). Safe to call repeatedly. */
+    unlock(): void;
+    /** Run `fn` with the AudioContext once audio is unlocked (now, if it already is). */
+    whenUnlocked(fn: (ctx: AudioContext) => void): void;
+    /** The AudioContext, once unlocked (music and other buses hang off it). */
+    get context(): AudioContext | null;
+    /** Unlock on the first pointer or key press on `target` (default window). */
+    unlockOnGesture(target?: EventTarget): void;
+    get ready(): boolean;
+    get master(): number;
+    set master(v: number);
+    /** Define or replace a cue's synth recipe and options. */
+    define(name: string, recipe: SynthRecipe, opts?: CueOptions): void;
+    /**
+     * Use a real sample for a cue (an AudioBuffer, or a URL fetched and decoded once audio is unlocked).
+     * `opts.gain` is the sample's level before the master gain (default: the cue's synth level).
+     */
+    addBuffer(name: string, source: AudioBuffer | string, opts?: CueOptions & {
+        readonly gain?: number;
+    }): Promise<void>;
+    has(name: string): boolean;
+    /** Play a cue. Returns false when muted, locked, unknown, throttled or out of voices. */
+    play(name: string, opts?: PlayOptions): boolean;
+    /** An impact scaled by damage (bigger hits are louder and lower). */
+    impact(damage: number, opts?: PlayOptions): boolean;
+    private voice;
+    private noiseBuffer;
+}
+/** Surfaces change a footstep's pitch and weight. */
+export declare const SURFACES: {
+    readonly grass: {
+        readonly pitch: 0.85;
+        readonly gain: 0.8;
+    };
+    readonly dirt: {
+        readonly pitch: 0.9;
+        readonly gain: 0.9;
+    };
+    readonly stone: {
+        readonly pitch: 1.25;
+        readonly gain: 1;
+    };
+    readonly wood: {
+        readonly pitch: 1.05;
+        readonly gain: 1;
+    };
+    readonly metal: {
+        readonly pitch: 1.6;
+        readonly gain: 1.1;
+    };
+};
+export type Surface = keyof typeof SURFACES;
+export interface FootstepOptions {
+    /** Metres per step. Default 1.4. */
+    readonly stride?: number;
+    /** Most steps per second. Default 6. */
+    readonly maxRate?: number;
+    /** Below this speed (m/s) no steps play. Default 0.6. */
+    readonly minSpeed?: number;
+}
+/**
+ * Footstep cadence from speed: steps per second = speed / stride, with an
+ * alternating left/right pitch. Calls `play(pitch, gain)` on each step.
+ */
+export declare class Footsteps {
+    private readonly play;
+    surface: Surface;
+    steps: number;
+    private phase;
+    private left;
+    private readonly o;
+    constructor(play: (pitch: number, gain: number) => void, opts?: FootstepOptions);
+    /** Advance by `dt` seconds at `speed` m/s. Returns the number of steps played. */
+    update(dt: number, speed: number, grounded?: boolean): number;
+}