@downdraft/engine 0.1.1 → 0.2.0

package/dist/modules/vitals/src/index.js

@@ -0,0 +1,25 @@
+// ============================================================================
+// @downdraft/engine/modules/vitals — shared health / damage / death / respawn / meters
+//
+// `Vitals` tracks health, damage (with overkill + last-damage-time), death,
+// respawn, delayed regen, and secondary meters (oxygen, energy, hunger, ...)
+// against a caller-supplied host object so `p.health` stays a plain save
+// field. Games wire death/damage UI through the config callbacks.
+//
+// The module wrapper provides a configured factory via DI for module-host
+// games; hand-rolled sims can use `new Vitals(config, host)` directly.
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { Vitals } from "./vitals.js";
+export { Vitals } from "./vitals.js";
+export const VitalsFactoryTok = resourceToken("vitals:factory");
+export function createVitalsModule(config) {
+    return {
+        name: "vitals",
+        version: "1.0.0",
+        provides: [VitalsFactoryTok],
+        register(ctx) {
+            ctx.provide(VitalsFactoryTok, (host, overrides) => new Vitals({ ...config, ...overrides }, host));
+        },
+    };
+}

package/dist/modules/vitals/src/vitals.js

@@ -0,0 +1,195 @@
+// ============================================================================
+// Vitals — shared health / damage / regen / death / respawn / meter tracking
+//
+// Every game in the repo used to hand-roll the same bookkeeping: clamp health
+// on damage, track overkill + last-damage time, transition to a dead state,
+// emit damaged/died/respawned events, regenerate after a damage-free delay,
+// and tick secondary meters (oxygen / air / energy / hunger / thirst) that
+// drain under a condition and deal damage while depleted.
+//
+// `Vitals` owns that bookkeeping while writing through to a caller-supplied
+// host object (e.g. the game's player state struct) so `p.health` stays a
+// plain field that saves, SAB writers, and HUDs can keep reading directly.
+// ============================================================================
+export class Vitals {
+    cfg;
+    host;
+    meterValues = new Map();
+    timeSinceDamage = Infinity;
+    constructor(cfg, host) {
+        this.cfg = cfg;
+        this.host = host;
+    }
+    get health() {
+        return this.host.health;
+    }
+    get maxHealth() {
+        return this.cfg.maxHealth;
+    }
+    get dead() {
+        return this.cfg.isDead ? this.cfg.isDead(this.host) : (this.host.dead ?? this.host.health <= 0);
+    }
+    setDead(dead) {
+        if (this.cfg.setDead)
+            this.cfg.setDead(this.host, dead);
+        else if ("dead" in this.host)
+            this.host.dead = dead;
+    }
+    /**
+     * Apply `amount` damage. No-op (returns null) while dead or when amount <= 0.
+     * Clamps health at 0, tracks overkill, resets the regen-delay timer, fires
+     * `onDamage` always and `onDeath` on the killing blow.
+     */
+    damage(amount, cause) {
+        if (this.dead || amount <= 0)
+            return null;
+        const overkill = Math.max(0, amount - this.host.health);
+        this.host.health = Math.max(0, this.host.health - amount);
+        this.timeSinceDamage = 0;
+        const died = this.host.health <= 0;
+        if (died)
+            this.setDead(true);
+        const event = {
+            health: this.host.health,
+            maxHealth: this.cfg.maxHealth,
+            amount,
+            cause,
+            overkill,
+            died,
+        };
+        this.cfg.onDamage?.(event, this.host);
+        if (died)
+            this.cfg.onDeath?.({ cause, overkill }, this.host);
+        return event;
+    }
+    /** Heal up to `maxHealth`. Returns the amount actually applied. */
+    heal(amount) {
+        const next = Math.min(this.cfg.maxHealth, this.host.health + Math.max(0, amount));
+        const applied = next - this.host.health;
+        this.host.health = next;
+        return applied;
+    }
+    /** Kill outright (lethal damage path that bypasses the dead guard). */
+    kill(cause) {
+        if (this.dead)
+            return;
+        const overkill = 0;
+        this.host.health = 0;
+        this.setDead(true);
+        this.cfg.onDeath?.({ cause, overkill }, this.host);
+    }
+    /** Restore full health (+ all meters unless `restoreMeters: false`) and clear dead. */
+    respawn(opts) {
+        this.host.health = this.cfg.maxHealth;
+        this.setDead(false);
+        this.timeSinceDamage = 0;
+        if (opts?.restoreMeters !== false) {
+            for (const [name, m] of Object.entries(this.cfg.meters ?? {})) {
+                this.writeMeter(name, m.initial ?? m.max, m);
+            }
+        }
+        this.cfg.onRespawn?.(this.host);
+    }
+    // ── Meters ──
+    meter(name) {
+        const m = this.cfg.meters?.[name];
+        if (!m)
+            throw new Error(`Vitals: unknown meter "${name}"`);
+        if (m.field)
+            return this.host[m.field] ?? (m.initial ?? m.max);
+        return this.meterValues.get(name) ?? (m.initial ?? m.max);
+    }
+    setMeter(name, value) {
+        const m = this.cfg.meters?.[name];
+        if (!m)
+            throw new Error(`Vitals: unknown meter "${name}"`);
+        this.writeMeter(name, value, m);
+    }
+    meterMax(name) {
+        const m = this.cfg.meters?.[name];
+        if (!m)
+            throw new Error(`Vitals: unknown meter "${name}"`);
+        return m.max;
+    }
+    /** Imperative drain (e.g. an action tax like sprint/climb energy). */
+    drainMeter(name, amount) {
+        this.setMeter(name, this.meter(name) - Math.max(0, amount));
+    }
+    writeMeter(name, value, m) {
+        const clamped = Math.max(0, Math.min(m.max, value));
+        const prev = this.meter(name);
+        if (m.field)
+            this.host[m.field] = clamped;
+        else
+            this.meterValues.set(name, clamped);
+        if (clamped !== prev)
+            m.onChange?.(clamped, prev);
+    }
+    /**
+     * Advance meters + health regen by `dt`. `dt` is in whatever unit the rates
+     * use — seconds for per-second rates, or 1 per fixed tick for per-tick rates.
+     *
+     * Condition values may be `boolean | number`: a number > 0 counts as active
+     * and multiplies the meter's `drainRate` (e.g. a biome's oxygen drain
+     * multiplier); depletion gates only check truthiness.
+     *
+     * Meter rules per update:
+     *  - drains at `drainRate × conditionValue` while `conditions[drainWhen]` is
+     *    truthy (or always at `drainRate` when no `drainWhen` is set)
+     *  - recovers at `recoverRate` while the drain condition is falsy
+     *  - while at 0, applies `depleteDamageRate` health damage gated by
+     *    `conditions[depleteWhen ?? drainWhen]` (or unconditional when neither set)
+     */
+    update(dt, conditions = {}) {
+        this.timeSinceDamage += dt;
+        for (const [name, m] of Object.entries(this.cfg.meters ?? {})) {
+            const cond = m.drainWhen === undefined ? true : conditions[m.drainWhen];
+            const drainMul = cond === true ? 1 : cond || 0;
+            if (drainMul > 0) {
+                if (m.drainRate)
+                    this.writeMeter(name, this.meter(name) - m.drainRate * drainMul * dt, m);
+            }
+            else if (m.recoverRate) {
+                this.writeMeter(name, this.meter(name) + m.recoverRate * dt, m);
+            }
+            if (m.depleteDamageRate && this.meter(name) <= 0) {
+                const gate = m.depleteWhen ?? m.drainWhen;
+                if (gate === undefined || gate === "" || conditions[gate]) {
+                    this.damage(m.depleteDamageRate * dt, m.depleteDamageCause);
+                }
+            }
+        }
+        const regen = this.cfg.regen;
+        if (regen && !this.dead && this.host.health < this.cfg.maxHealth && this.timeSinceDamage >= regen.delay) {
+            this.heal(regen.rate * dt);
+        }
+    }
+    // ── Save / load ──
+    serialize() {
+        const snap = { health: this.host.health, dead: this.dead };
+        const meters = this.cfg.meters;
+        if (meters && Object.keys(meters).length > 0) {
+            snap.meters = {};
+            for (const name of Object.keys(meters))
+                snap.meters[name] = this.meter(name);
+        }
+        return snap;
+    }
+    restore(snap) {
+        if (!snap)
+            return;
+        if (typeof snap.health === "number")
+            this.host.health = Math.min(this.cfg.maxHealth, snap.health);
+        if (typeof snap.dead === "boolean")
+            this.setDead(snap.dead);
+        if (snap.meters) {
+            for (const [name, v] of Object.entries(snap.meters)) {
+                if (this.cfg.meters?.[name])
+                    this.setMeter(name, v);
+            }
+        }
+        // Restart the regen-delay window — a restored player waits for the delay
+        // before regenerating, same as one that just took damage.
+        this.timeSinceDamage = 0;
+    }
+}

package/dist/modules/xr/src/camera-rig.js

@@ -0,0 +1,119 @@
+const DEFAULT_VIEWPORT = { x: 0, y: 0, w: 1, h: 1 };
+export class XRCameraRig {
+    layerManager;
+    getWorldOrigin;
+    headPosition = [0, 0, 0];
+    headQuaternion = [0, 0, 0, 1];
+    constructor(layerManager, getWorldOrigin) {
+        this.layerManager = layerManager;
+        this.getWorldOrigin = getWorldOrigin;
+    }
+    computeEyeCameras(screenW, screenH) {
+        const left = this.computeEyeCamera("left", screenW, screenH);
+        const right = this.computeEyeCamera("right", screenW, screenH);
+        return [left, right];
+    }
+    computeEyeCamera(eye, screenW, screenH) {
+        const projMatrix = this.layerManager.getProjectionMatrix(eye);
+        const viewMatrix = this.layerManager.getViewMatrix(eye);
+        const viewport = this.layerManager.getViewport(eye);
+        if (!projMatrix || !viewMatrix)
+            return null;
+        const vp = viewport
+            ? { x: viewport.x, y: viewport.y, w: viewport.width, h: viewport.height }
+            : DEFAULT_VIEWPORT;
+        const aspect = vp.w > 0 && vp.h > 0 ? vp.w / vp.h : 1;
+        const worldOrigin = this.getWorldOrigin();
+        const worldMatrix = composeWorldMatrix(worldOrigin);
+        const finalViewMatrix = multiplyMat4(worldMatrix, viewMatrix);
+        const position = extractPosition(finalViewMatrix);
+        return {
+            camera: {
+                position,
+                target: [position[0], position[1] - 1, position[2]],
+                up: [0, 1, 0],
+                fov: 90,
+                near: 0.05,
+                far: 1000,
+                aspect,
+                projectionMatrix: projMatrix,
+                viewMatrix: finalViewMatrix,
+            },
+            viewport: vp,
+        };
+    }
+    updateHeadPose(pose, referenceSpace) {
+        const matrix = pose.transform.matrix;
+        const worldOrigin = this.getWorldOrigin();
+        const worldMatrix = composeWorldMatrix(worldOrigin);
+        const headMatrix = multiplyMat4(worldMatrix, matrix);
+        this.headPosition = extractPosition(headMatrix);
+        this.headQuaternion = extractQuaternion(headMatrix);
+    }
+    getHeadPose() {
+        return { position: this.headPosition, quaternion: this.headQuaternion };
+    }
+}
+function composeWorldMatrix(origin) {
+    const [px, py, pz] = origin.position;
+    const [qx, qy, qz, qw] = origin.quaternion;
+    const x2 = qx + qx, y2 = qy + qy, z2 = qz + qz;
+    const xx = qx * x2, xy = qx * y2, xz = qx * z2;
+    const yy = qy * y2, yz = qy * z2, zz = qz * z2;
+    const wx = qw * x2, wy = qw * y2, wz = qw * z2;
+    return new Float32Array([
+        1 - (yy + zz), xy + wz, xz - wy, 0,
+        xy - wz, 1 - (xx + zz), yz + wx, 0,
+        xz + wy, yz - wx, 1 - (xx + yy), 0,
+        px, py, pz, 1,
+    ]);
+}
+function multiplyMat4(a, b) {
+    const result = new Float32Array(16);
+    for (let i = 0; i < 4; i++) {
+        for (let j = 0; j < 4; j++) {
+            let sum = 0;
+            for (let k = 0; k < 4; k++) {
+                sum += a[i * 4 + k] * b[k * 4 + j];
+            }
+            result[i * 4 + j] = sum;
+        }
+    }
+    return result;
+}
+function extractPosition(m) {
+    return [m[12], m[13], m[14]];
+}
+function extractQuaternion(m) {
+    const trace = m[0] + m[5] + m[10];
+    let qw, qx, qy, qz;
+    if (trace > 0) {
+        const s = 0.5 / Math.sqrt(trace + 1);
+        qw = 0.25 / s;
+        qx = (m[6] - m[9]) * s;
+        qy = (m[8] - m[2]) * s;
+        qz = (m[1] - m[4]) * s;
+    }
+    else if (m[0] > m[5] && m[0] > m[10]) {
+        const s = 2 * Math.sqrt(1 + m[0] - m[5] - m[10]);
+        qw = (m[6] - m[9]) / s;
+        qx = 0.25 * s;
+        qy = (m[4] + m[1]) / s;
+        qz = (m[8] + m[2]) / s;
+    }
+    else if (m[5] > m[10]) {
+        const s = 2 * Math.sqrt(1 + m[5] - m[0] - m[10]);
+        qw = (m[8] - m[2]) / s;
+        qx = (m[4] + m[1]) / s;
+        qy = 0.25 * s;
+        qz = (m[9] + m[6]) / s;
+    }
+    else {
+        const s = 2 * Math.sqrt(1 + m[10] - m[0] - m[5]);
+        qw = (m[1] - m[4]) / s;
+        qx = (m[8] + m[2]) / s;
+        qy = (m[9] + m[6]) / s;
+        qz = 0.25 * s;
+    }
+    return [qx, qy, qz, qw];
+}

package/dist/modules/xr/src/debug.js

@@ -0,0 +1,45 @@
+import { isXRAvailable, isXRGPUBindingAvailable, isVRSupported } from "./session.js";
+export function getXRDebugInfo(plugin) {
+    return {
+        xrAvailable: isXRAvailable(),
+        xrGPUBindingAvailable: isXRGPUBindingAvailable(),
+        vrSupported: false,
+        sessionState: plugin.getSessionManager().getState(),
+        active: plugin.isActive(),
+        controllerCount: plugin.getInputMapper().getControllerCount(),
+        headPosition: plugin.getHeadPose().position,
+        headQuaternion: plugin.getHeadPose().quaternion,
+    };
+}
+export async function checkXRSupport() {
+    const available = isXRAvailable();
+    const gpuBinding = isXRGPUBindingAvailable();
+    const vrSupported = available ? await isVRSupported() : false;
+    let message;
+    if (!available) {
+        message = "WebXR API not available. Use a WebXR-compatible browser (Chrome/Edge with WebXR support).";
+    }
+    else if (!gpuBinding) {
+        message = "XRGPUBinding not available. Enable chrome://flags/#webxr-incubations for WebGPU-native XR rendering.";
+    }
+    else if (!vrSupported) {
+        message = "Immersive VR not supported. Connect a VR headset or use a WebXR emulator.";
+    }
+    else {
+        message = "WebXR VR is ready.";
+    }
+    return { available, vrSupported, gpuBinding, message };
+}
+export function formatXRDebugInfo(info) {
+    const lines = [
+        `XR Available: ${info.xrAvailable ? "YES" : "NO"}`,
+        `XRGPU Binding: ${info.xrGPUBindingAvailable ? "YES" : "NO"}`,
+        `VR Supported: ${info.vrSupported ? "YES" : "NO"}`,
+        `Session State: ${info.sessionState}`,
+        `Active: ${info.active ? "YES" : "NO"}`,
+        `Controllers: ${info.controllerCount}`,
+        `Head Pos: [${info.headPosition[0].toFixed(3)}, ${info.headPosition[1].toFixed(3)}, ${info.headPosition[2].toFixed(3)}]`,
+        `Head Quat: [${info.headQuaternion[0].toFixed(3)}, ${info.headQuaternion[1].toFixed(3)}, ${info.headQuaternion[2].toFixed(3)}, ${info.headQuaternion[3].toFixed(3)}]`,
+    ];
+    return lines.join("\n");
+}

package/dist/modules/xr/src/frame-loop.js

@@ -0,0 +1,139 @@
+// ============================================================================
+// XRFrameLoop — drives the XR render loop through the RendererModuleContext
+//
+// Installs XR-specific overrides on the RendererModuleContext:
+//  - XR rAF source (session.requestAnimationFrame instead of window.rAF)
+//  - XR render target provider (per-eye XRGPULayer textures)
+//  - Viewport camera provider (per-eye stereo cameras)
+//  - Stereo viewport count (2)
+//  - beforeFrame hook (XR input mapping)
+//
+// On stop(), all overrides are cleared and the desktop render loop resumes.
+// ============================================================================
+const DEFAULT_VIEWPORT = { x: 0, y: 0, w: 1, h: 1 };
+class XRRenderTargetProvider {
+    layerManager;
+    constructor(layerManager) {
+        this.layerManager = layerManager;
+    }
+    getColorView(viewportIdx) {
+        const eye = viewportIdx === 0 ? "left" : "right";
+        return this.layerManager.getColorTextureView(eye);
+    }
+    getDepthView(viewportIdx, _w, _h) {
+        const eye = viewportIdx === 0 ? "left" : "right";
+        return this.layerManager.getDepthTextureView(eye);
+    }
+    getViewportCount() {
+        return 2;
+    }
+    getViewportRect(idx, _screenW, _screenH) {
+        const eye = idx === 0 ? "left" : "right";
+        const vp = this.layerManager.getViewport(eye);
+        if (vp) {
+            return { x: vp.x, y: vp.y, w: vp.width, h: vp.height };
+        }
+        return DEFAULT_VIEWPORT;
+    }
+    beginFrame() {
+        // no-op — layer views are updated in XRFrameLoop.onXRFrame before renderFrame
+    }
+    endFrame(_encoder) {
+        // no-op — XRGPULayer textures are consumed by the XR compositor automatically
+    }
+}
+export class XRFrameLoop {
+    ctx;
+    sessionManager;
+    layerManager;
+    cameraRig;
+    inputState;
+    inputMapper;
+    canvas;
+    targetProvider;
+    active = false;
+    currentFrame = null;
+    // Unsubscribe fns for context hooks installed during start().
+    unsubBeforeFrame = null;
+    constructor(ctx, sessionManager, layerManager, cameraRig, options) {
+        this.ctx = ctx;
+        this.sessionManager = sessionManager;
+        this.layerManager = layerManager;
+        this.cameraRig = cameraRig;
+        this.inputState = options.inputState ?? null;
+        this.inputMapper = options.inputMapper ?? null;
+        this.canvas = options.canvas;
+        this.targetProvider = new XRRenderTargetProvider(layerManager);
+    }
+    start() {
+        if (this.active)
+            return;
+        const session = this.sessionManager.getSession();
+        if (!session)
+            throw new Error("No active XR session");
+        this.active = true;
+        // Install XR rAF source
+        this.ctx.setRAFSource((cb) => session.requestAnimationFrame((time, frame) => {
+            this.onXRFrame(time, frame);
+            cb(time);
+        }), (id) => session.cancelAnimationFrame(id));
+        // Install XR render target provider
+        this.ctx.setRenderTargetProvider(this.targetProvider);
+        // Set viewport count to 2 for stereo
+        this.ctx.setViewportCount(2);
+        // Install per-eye viewport camera provider (takes priority over the
+        // game's onViewport callback)
+        this.ctx.setViewportCameraProvider((viewportIdx, _dt, _elapsedTime) => {
+            const eye = viewportIdx === 0 ? "left" : "right";
+            const [left, right] = this.cameraRig.computeEyeCameras(this.canvas.width, this.canvas.height);
+            const cam = eye === "left" ? left : right;
+            if (!cam)
+                return null;
+            return cam;
+        });
+        // Install beforeFrame hook for XR input mapping
+        this.unsubBeforeFrame = this.ctx.onFrame("beforeFrame", (_dt, _elapsedTime) => {
+            const refSpace = this.sessionManager.getReferenceSpace();
+            if (refSpace && this.currentFrame && this.inputMapper && this.inputState) {
+                this.inputMapper.update(this.currentFrame, refSpace, this.inputState);
+            }
+        });
+    }
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.currentFrame = null;
+        // Restore desktop rAF
+        this.ctx.setRAFSource(null, null);
+        // Remove XR render target provider
+        this.ctx.setRenderTargetProvider(null);
+        // Restore viewport count to 1
+        this.ctx.setViewportCount(1);
+        // Remove viewport camera provider
+        this.ctx.setViewportCameraProvider(null);
+        // Remove beforeFrame hook
+        this.unsubBeforeFrame?.();
+        this.unsubBeforeFrame = null;
+        // Clear XR controller state from input
+        if (this.inputState) {
+            this.inputState.xrControllers = [];
+        }
+    }
+    onXRFrame(_time, frame) {
+        this.currentFrame = frame;
+        const refSpace = this.sessionManager.getReferenceSpace();
+        if (!refSpace)
+            return;
+        const pose = frame.getViewerPose(refSpace);
+        if (!pose)
+            return;
+        // Update layer views from the pose
+        this.layerManager.beginFrame(frame, refSpace);
+        // Update head pose for game logic
+        this.cameraRig.updateHeadPose(pose, refSpace);
+    }
+    isActive() {
+        return this.active;
+    }
+}

package/dist/modules/xr/src/index.js

@@ -0,0 +1,10 @@
+/// <reference path="./webxr.d.ts" />
+export { XRCameraRig } from "./camera-rig.js";
+export { checkXRSupport, formatXRDebugInfo, getXRDebugInfo } from "./debug.js";
+export { XRFrameLoop } from "./frame-loop.js";
+export { XRInputMapper } from "./input.js";
+export { XRLayerManager } from "./layer.js";
+export { isVRSupported, isXRAvailable, isXRGPUBindingAvailable, XRSessionManager } from "./session.js";
+export { xrModule } from "./sim-module.js";
+export { DEFAULT_XR_CONFIG } from "./types.js";
+export { XRModule } from "./xr-module.js";