@netforge/engine 0.0.0-stage → 0.2.0

package/dist/runtime/arena.d.ts

@@ -0,0 +1,86 @@
+import type { SimConfig } from "@netforge/engine-sim";
+import type { Backend } from "./renderer.js";
+export interface ArenaOptions {
+    readonly sim?: SimConfig;
+    readonly forceWebGL?: boolean;
+    /** Called after every rendered frame with the latest numbers. */
+    readonly onStats?: (s: ArenaStats) => void;
+    /** Keep frame time near this budget by scaling resolution (ms). Default 16.7. */
+    readonly frameBudgetMs?: number;
+    /** Feed scripted inputs instead of the keyboard (headless measurement). */
+    readonly autopilot?: boolean;
+}
+export interface ArenaStats {
+    readonly backend: Backend;
+    readonly fps: number;
+    /** Interval between frames (what the player feels). */
+    readonly frameMs: {
+        readonly mean: number;
+        readonly p50: number;
+        readonly p95: number;
+        readonly p99: number;
+    };
+    /** Main-thread time spent inside the frame callback (sim + render submission). */
+    readonly cpuMs: {
+        readonly mean: number;
+        readonly p95: number;
+    };
+    readonly simMsPerTick: number;
+    readonly drawCalls: number;
+    readonly triangles: number;
+    readonly entities: number;
+    readonly enemies: number;
+    readonly frames: number;
+    readonly pixelRatio: number;
+    readonly tick: number;
+    readonly health: number;
+    readonly kills: number;
+}
+/**
+ * The week-2 single-player arena: engine-sim on a fixed tick, rendered by
+ * three.js with interpolation, one instanced draw for every enemy, a
+ * follow camera, keyboard/mouse/touch input. Placeholder primitives only.
+ */
+export declare class ArenaClient {
+    private readonly host;
+    private readonly handle;
+    private readonly world;
+    private readonly opts;
+    private constructor();
+    private scene;
+    private rig;
+    private input;
+    private crowd;
+    private playerMesh;
+    private pulse;
+    private pulseT;
+    private stepper;
+    private readonly frame;
+    private readonly cpu;
+    private readonly sim;
+    private last;
+    private frames;
+    private kills;
+    private flash;
+    private pixelRatio;
+    private resLastChange;
+    private readonly target;
+    private autoYaw;
+    private autoSeq;
+    private disposed;
+    private latest;
+    static create(host: HTMLElement, opts?: ArenaOptions): Promise<ArenaClient>;
+    private build;
+    private resize;
+    start(): void;
+    /** Latest numbers (also passed to `onStats`). */
+    stats(): ArenaStats | null;
+    private autopilotInput;
+    private loop;
+    private drawPlayer;
+    private onEvents;
+    private animateFx;
+    /** Dynamic resolution: hold the frame budget by trading pixels (spec §5 quality tiers). */
+    private adaptResolution;
+    dispose(): void;
+}

package/dist/runtime/arena.js

@@ -0,0 +1,269 @@
+import { AmbientLight, BoxGeometry, CapsuleGeometry, Color, ConeGeometry, CylinderGeometry, DirectionalLight, Fog, GridHelper, HemisphereLight, Mesh, MeshBasicMaterial, MeshStandardMaterial, PlaneGeometry, RingGeometry, Scene, Vector3, } from "three/webgpu";
+import { EntityFlag, EntityKind, FixedStepper, addPlayer, createWorld, destroyWorld, initSim, renderView, step, } from "@netforge/engine-sim";
+import { CameraRig } from "./camera.js";
+import { InstancedCrowd } from "./crowd.js";
+import { InputController } from "./input.js";
+import { lerp } from "./interpolate.js";
+import { createRenderer } from "./renderer.js";
+import { FrameStats } from "./stats.js";
+const PLAYER_ID = 1;
+/**
+ * The week-2 single-player arena: engine-sim on a fixed tick, rendered by
+ * three.js with interpolation, one instanced draw for every enemy, a
+ * follow camera, keyboard/mouse/touch input. Placeholder primitives only.
+ */
+export class ArenaClient {
+    host;
+    handle;
+    world;
+    opts;
+    constructor(host, handle, world, opts) {
+        this.host = host;
+        this.handle = handle;
+        this.world = world;
+        this.opts = opts;
+    }
+    scene = new Scene();
+    rig;
+    input;
+    crowd;
+    playerMesh;
+    pulse;
+    pulseT = 1;
+    stepper;
+    frame = new FrameStats();
+    cpu = new FrameStats();
+    sim = new FrameStats(120);
+    last = 0;
+    frames = 0;
+    kills = 0;
+    flash = 0;
+    pixelRatio = 1;
+    resLastChange = 0;
+    target = new Vector3();
+    autoYaw = 0;
+    autoSeq = 0;
+    disposed = false;
+    latest = null;
+    static async create(host, opts = {}) {
+        await initSim();
+        const canvas = document.createElement("canvas");
+        canvas.style.cssText = "display:block;width:100%;height:100%;touch-action:none";
+        host.append(canvas);
+        const handle = await createRenderer(canvas, opts.forceWebGL === undefined ? {} : { forceWebGL: opts.forceWebGL });
+        const world = createWorld(opts.sim);
+        addPlayer(world, PLAYER_ID);
+        const c = new ArenaClient(host, handle, world, opts);
+        c.build();
+        return c;
+    }
+    build() {
+        const { renderer } = this.handle;
+        const cfg = this.world.config;
+        const half = cfg.arena.halfExtent;
+        this.pixelRatio = renderer.getPixelRatio();
+        const bg = new Color(0x0b0d12);
+        this.scene.background = bg;
+        this.scene.fog = new Fog(bg, 40, 140);
+        this.scene.add(new HemisphereLight(0xbfd4ff, 0x1a1408, 1.1));
+        this.scene.add(new AmbientLight(0xffffff, 0.15));
+        const sun = new DirectionalLight(0xffffff, 1.6);
+        sun.position.set(20, 40, 10);
+        this.scene.add(sun);
+        const floor = new Mesh(new PlaneGeometry(half * 2, half * 2), new MeshStandardMaterial({ color: 0x1b2230, roughness: 0.95 }));
+        floor.rotation.x = -Math.PI / 2;
+        this.scene.add(floor);
+        const grid = new GridHelper(half * 2, Math.round(half), 0x2f3a50, 0x232b3b);
+        grid.position.y = 0.01;
+        this.scene.add(grid);
+        const wallMat = new MeshStandardMaterial({ color: 0x3a4660, roughness: 0.8 });
+        const h = cfg.arena.wallHeight;
+        for (const [x, z, w, d] of [
+            [0, half + 0.5, half * 2 + 2, 1],
+            [0, -half - 0.5, half * 2 + 2, 1],
+            [half + 0.5, 0, 1, half * 2 + 2],
+            [-half - 0.5, 0, 1, half * 2 + 2],
+        ]) {
+            const m = new Mesh(new BoxGeometry(w, h, d), wallMat);
+            m.position.set(x, h / 2, z);
+            this.scene.add(m);
+        }
+        const pillarMat = new MeshStandardMaterial({ color: 0x55627d, roughness: 0.7 });
+        for (const p of cfg.arena.pillars) {
+            const m = new Mesh(new CylinderGeometry(p.radius, p.radius, p.height, 24), pillarMat);
+            m.position.set(p.x, p.height / 2, p.z);
+            this.scene.add(m);
+        }
+        const pr = cfg.player;
+        this.playerMesh = new Mesh(new CapsuleGeometry(pr.radius, pr.halfHeight * 2, 4, 12), new MeshStandardMaterial({ color: 0x4fd1c5, roughness: 0.4, emissive: new Color(0x0b3b38) }));
+        const nose = new Mesh(new BoxGeometry(0.18, 0.18, 0.4), new MeshStandardMaterial({ color: 0xffffff }));
+        nose.position.set(0, 0.35, -pr.radius);
+        this.playerMesh.add(nose);
+        this.scene.add(this.playerMesh);
+        // Enemies: a 6-sided cone pointing along -z (its facing), one draw call.
+        const er = cfg.enemies.radius;
+        const cone = new ConeGeometry(er, er * 2.4, 6);
+        cone.rotateX(-Math.PI / 2);
+        const cap = Math.max(16, cfg.enemies.target + cfg.enemies.spawnPerTick);
+        this.crowd = new InstancedCrowd(cone, new MeshStandardMaterial({ color: 0xf06449, roughness: 0.6 }), cap, EntityKind.Enemy);
+        this.scene.add(this.crowd.mesh);
+        this.pulse = new Mesh(new RingGeometry(0.85, 1, 48), new MeshBasicMaterial({ color: 0x9ae6ff, transparent: true, opacity: 0, depthWrite: false }));
+        this.pulse.rotation.x = -Math.PI / 2;
+        this.scene.add(this.pulse);
+        this.rig = new CameraRig(1);
+        this.input = new InputController(this.host, this.rig);
+        this.stepper = new FixedStepper(this.world.tickRate, 4);
+        this.resize();
+        const ro = new ResizeObserver(() => this.resize());
+        ro.observe(this.host);
+        // Nothing runs while the tab is hidden; on return, drop the backlog.
+        document.addEventListener("visibilitychange", () => {
+            if (!document.hidden) {
+                this.stepper.reset();
+                this.last = 0;
+            }
+        });
+    }
+    resize() {
+        const w = Math.max(1, this.host.clientWidth);
+        const h = Math.max(1, this.host.clientHeight);
+        this.handle.renderer.setSize(w, h, false);
+        this.rig.resize(w / h);
+    }
+    start() {
+        this.handle.renderer.setAnimationLoop((t) => this.loop(t));
+    }
+    /** Latest numbers (also passed to `onStats`). */
+    stats() {
+        return this.latest;
+    }
+    autopilotInput(tick) {
+        // Circle-strafe and pulse: exercises movement, the crowd and combat.
+        this.autoYaw += 0.01;
+        return { seq: ++this.autoSeq, tick, moveX: 0.6, moveZ: 0.8, yaw: this.autoYaw, buttons: tick % 20 < 2 ? 2 : 0 };
+    }
+    loop(now) {
+        if (this.disposed || document.hidden)
+            return;
+        const t0 = performance.now();
+        const dtMs = this.last === 0 ? 1000 / 60 : now - this.last;
+        if (this.last !== 0)
+            this.frame.push(dtMs);
+        this.last = now;
+        const adv = this.stepper.advance(dtMs);
+        const events = [];
+        for (let i = 0; i < adv.ticks; i++) {
+            const cmd = this.opts.autopilot ? this.autopilotInput(this.world.tick) : this.input.sample(this.world.tick);
+            if (this.opts.autopilot)
+                this.rig.yaw = cmd.yaw;
+            const s0 = performance.now();
+            const r = step(this.world, new Map([[PLAYER_ID, cmd]]));
+            this.sim.push(performance.now() - s0);
+            for (const e of r.events)
+                events.push(e);
+        }
+        this.onEvents(events);
+        const view = renderView(this.world);
+        const enemies = this.crowd.update(view, adv.alpha);
+        const me = this.drawPlayer(view, adv.alpha);
+        const dt = dtMs / 1000;
+        this.rig.update(this.target, dt);
+        this.animateFx(dt);
+        this.handle.renderer.render(this.scene, this.rig.camera);
+        this.cpu.push(performance.now() - t0);
+        this.frames++;
+        this.adaptResolution(now);
+        const info = this.handle.renderer.info.render;
+        const mean = this.frame.mean();
+        this.latest = {
+            backend: this.handle.backend,
+            fps: mean > 0 ? 1000 / mean : 0,
+            frameMs: { mean, p50: this.frame.percentile(0.5), p95: this.frame.percentile(0.95), p99: this.frame.percentile(0.99) },
+            cpuMs: { mean: this.cpu.mean(), p95: this.cpu.percentile(0.95) },
+            simMsPerTick: this.sim.mean(),
+            drawCalls: info.drawCalls,
+            triangles: info.triangles,
+            entities: view.count,
+            enemies,
+            frames: this.frames,
+            pixelRatio: this.pixelRatio,
+            tick: this.world.tick,
+            health: me?.health ?? 0,
+            kills: this.kills,
+        };
+        this.opts.onStats?.(this.latest);
+    }
+    drawPlayer(view, alpha) {
+        for (let i = 0; i < view.count; i++) {
+            if (view.kind[i] !== EntityKind.Player || view.owner[i] !== PLAYER_ID)
+                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);
+            this.playerMesh.position.set(x, y, z);
+            this.playerMesh.rotation.y = view.yaw[i] ?? 0;
+            this.playerMesh.visible = ((view.flags[i] ?? 0) & EntityFlag.Dead) === 0;
+            this.target.set(x, y, z);
+            return { health: view.health[i] ?? 0 };
+        }
+        return null;
+    }
+    onEvents(events) {
+        for (const e of events) {
+            if (e.type === "enemy.killed")
+                this.kills++;
+            else if (e.type === "player.pulse") {
+                this.pulseT = 0;
+                this.rig.shake(0.15, 0.12);
+            }
+            else if (e.type === "player.hit") {
+                this.flash = 1;
+                this.rig.shake(0.25, 0.15);
+            }
+        }
+    }
+    animateFx(dt) {
+        const mat = this.pulse.material;
+        if (this.pulseT < 1) {
+            this.pulseT = Math.min(1, this.pulseT + dt * 4);
+            const r = this.world.config.player.pulseRadius * (0.3 + 0.7 * this.pulseT);
+            this.pulse.scale.setScalar(r);
+            this.pulse.position.set(this.target.x, 0.05, this.target.z);
+            mat.opacity = 0.8 * (1 - this.pulseT);
+        }
+        else {
+            mat.opacity = 0;
+        }
+        if (this.flash > 0) {
+            this.flash = Math.max(0, this.flash - dt * 5);
+            this.playerMesh.material.emissive.setRGB(0.05 + this.flash, 0.23 * (1 - this.flash), 0.22 * (1 - this.flash));
+        }
+    }
+    /** Dynamic resolution: hold the frame budget by trading pixels (spec §5 quality tiers). */
+    adaptResolution(now) {
+        if (this.frame.count < 120 || now - this.resLastChange < 2000)
+            return;
+        const budget = this.opts.frameBudgetMs ?? 1000 / 60;
+        const p95 = this.frame.percentile(0.95);
+        const cap = Math.min(globalThis.devicePixelRatio || 1, 2);
+        let next = this.pixelRatio;
+        if (p95 > budget * 1.25 && this.pixelRatio > 0.75)
+            next = Math.max(0.75, this.pixelRatio - 0.25);
+        else if (p95 < budget * 1.05 && this.pixelRatio < cap)
+            next = Math.min(cap, this.pixelRatio + 0.25);
+        if (next !== this.pixelRatio) {
+            this.pixelRatio = next;
+            this.handle.renderer.setPixelRatio(next);
+            this.resize();
+            this.resLastChange = now;
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.handle.renderer.setAnimationLoop(null);
+        this.input.dispose();
+        this.crowd.dispose();
+        this.handle.renderer.dispose();
+        destroyWorld(this.world);
+    }
+}

package/dist/runtime/assets.d.ts

@@ -0,0 +1,26 @@
+import type { WebGPURenderer } from "three/webgpu";
+import type { GLTF } from "three/addons/loaders/GLTFLoader.js";
+export interface AssetLoaderOptions {
+    /**
+     * Maps a library id ("style.lowpoly.mech_01") to a URL on the asset CDN.
+     * Games never see URLs (spec §10); only this resolver does.
+     */
+    readonly resolve: (id: string) => string;
+    /** Where basis_transcoder.js/.wasm are served (copied from three/examples/jsm/libs/basis/). */
+    readonly transcoderPath: string;
+}
+/**
+ * glTF loading with the runtime's compression stack: meshopt geometry
+ * (EXT_meshopt_compression) and KTX2/Basis textures (KHR_texture_basisu).
+ * Loads are cached by id, so a prefab used 2,000 times is fetched once.
+ */
+export declare class AssetLoader {
+    private readonly opts;
+    private readonly gltf;
+    private readonly ktx2;
+    private readonly cache;
+    private ready;
+    constructor(renderer: WebGPURenderer, opts: AssetLoaderOptions);
+    load(id: string): Promise<GLTF>;
+    dispose(): void;
+}

package/dist/runtime/assets.js

@@ -0,0 +1,35 @@
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";
+import { MeshoptDecoder } from "three/addons/libs/meshopt_decoder.module.js";
+/**
+ * glTF loading with the runtime's compression stack: meshopt geometry
+ * (EXT_meshopt_compression) and KTX2/Basis textures (KHR_texture_basisu).
+ * Loads are cached by id, so a prefab used 2,000 times is fetched once.
+ */
+export class AssetLoader {
+    opts;
+    gltf;
+    ktx2;
+    cache = new Map();
+    ready;
+    constructor(renderer, opts) {
+        this.opts = opts;
+        this.ktx2 = new KTX2Loader().setTranscoderPath(opts.transcoderPath);
+        this.ready = this.ktx2.detectSupportAsync(renderer).then(() => undefined);
+        this.gltf = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder).setKTX2Loader(this.ktx2);
+    }
+    load(id) {
+        let p = this.cache.get(id);
+        if (!p) {
+            const url = this.opts.resolve(id);
+            p = this.ready.then(() => this.gltf.loadAsync(url));
+            p.catch(() => this.cache.delete(id));
+            this.cache.set(id, p);
+        }
+        return p;
+    }
+    dispose() {
+        this.ktx2.dispose();
+        this.cache.clear();
+    }
+}

package/dist/runtime/camera.d.ts

@@ -0,0 +1,113 @@
+import { PerspectiveCamera, Vector3 } from "three/webgpu";
+import type { Camera } from "three/webgpu";
+import { Trauma } from "./feel/trauma.js";
+import type { TraumaOptions } from "./feel/trauma.js";
+export interface CameraRigOptions {
+    readonly distance?: number;
+    readonly height?: number;
+    readonly minPitch?: number;
+    readonly maxPitch?: number;
+    /** Follow stiffness, 1/s. Higher is tighter (a critically damped spring, no overshoot). */
+    readonly follow?: number;
+    /** Seconds of target velocity the camera looks ahead by (camera lead, §13). */
+    readonly lead?: number;
+    /** Largest look-ahead, m. Default 6 (a teleport never flings the camera). */
+    readonly leadMax?: number;
+    /** How fast the look-ahead itself settles, 1/s (0 = instant). Default 10. */
+    readonly leadSmoothing?: number;
+    /** The target may move this far (m, ground plane) before the camera follows. Default 0. */
+    readonly deadZone?: number;
+    readonly fov?: number;
+    /** Trauma shake tuning (maxOffset in m, maxRoll in rad, decay per second). */
+    readonly shake?: TraumaOptions;
+    /** FOV punch spring: frequency Hz and damping ratio. Default 4 Hz, 0.55. */
+    readonly punchFrequency?: number;
+    readonly punchDamping?: number;
+    /**
+     * Keep the visible ground inside these bounds (world x/z, m): near a wall
+     * the camera stops instead of showing the void past it. Pass the play
+     * field plus however much dressed outside ground should show.
+     */
+    readonly bounds?: GroundBounds | null;
+    /** Height of the ground plane the bounds apply to. Default 0. */
+    readonly groundY?: number;
+}
+/** A rectangle on the ground plane. */
+export interface GroundBounds {
+    readonly minX: number;
+    readonly maxX: number;
+    readonly minZ: number;
+    readonly maxZ: number;
+}
+/** Square bounds around the origin: a field of half size `half` plus `margin` of outside ground. */
+export declare function fieldBounds(half: number, margin?: number): GroundBounds;
+/**
+ * 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 declare function groundFootprint(camera: Camera, groundY?: number, reach?: number): GroundBounds;
+/**
+ * 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 declare function boundsShift(seen: GroundBounds, bounds: GroundBounds): {
+    x: number;
+    z: number;
+};
+/**
+ * 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 declare class CameraRig {
+    readonly camera: PerspectiveCamera;
+    yaw: number;
+    pitch: number;
+    /** Trauma shake (add with `addTrauma`). */
+    readonly trauma: Trauma;
+    /** This frame's shake offset (world, m) and roll (rad). */
+    readonly offset: Vector3;
+    roll: number;
+    private readonly focus;
+    private readonly focusVel;
+    private readonly lastTarget;
+    private readonly vel;
+    private readonly leadVec;
+    private readonly fovSpring;
+    private initialised;
+    private readonly o;
+    private bounds;
+    /** This frame's clamp shift (m, ground plane): non-zero while the bounds hold the camera back. */
+    readonly clampShift: {
+        x: number;
+        z: number;
+    };
+    constructor(aspect: number, opts?: CameraRigOptions);
+    /** Camera distance from the focus, m (e.g. pull back on a portrait phone). */
+    setDistance(metres: number): void;
+    /** Keep the visible ground inside `bounds` (null lets the camera follow anywhere). */
+    setBounds(bounds: GroundBounds | null): void;
+    /** The point the camera looks at (after follow and lead). */
+    get target(): Readonly<Vector3>;
+    /** Apply look input (radians). */
+    look(dYaw: number, dPitch: number): void;
+    /** Add trauma 0..1 (game feel, §13): the shake is trauma squared, so small hits barely move it. */
+    addTrauma(amount: number): void;
+    /** The classic shake: about `amplitude` m of shake held for `seconds`, then fading. */
+    shake(amplitude: number, seconds: number): void;
+    /** Kick the field of view by `degrees` (negative zooms in) and spring back. */
+    punch(degrees: number): void;
+    /** Current FOV offset from the punch spring, degrees. */
+    get fovKick(): number;
+    /**
+     * Follow `target`. `dt` is the (hit-stop scaled) frame delta; pass
+     * `realDt` so shake and punches keep moving during a hit-stop.
+     */
+    update(target: Vector3, dt: number, realDt?: number): void;
+    resize(aspect: number): void;
+}