@jgengine/core 0.9.0 → 0.11.0

package/dist/orders/orderQueue.js

@@ -0,0 +1,211 @@
+/**
+ * Composable entity orders: a serializable command queue with lifecycle,
+ * preemption, and pluggable order kinds (#912). Player- or AI-issued intent
+ * ("move here", "attack that", "patrol this route") becomes reusable data
+ * instead of a hard-coded RTS verb kit. The queue owns issue -> activate ->
+ * tick -> complete/cancel lifecycle and deterministic preemption policy; each
+ * order KIND owns what "running" means, composed over narrow world adapters.
+ * Engine code never branches on `move`, `attack`, or any game verb -- kinds are
+ * looked up by string in a registry, so a game adds a verb by registering data.
+ */
+/**
+ * Build an empty order-kind registry. Register the built-in compositions from
+ * `orders/orderKinds` or your own verbs, then hand it to `createOrderQueue`.
+ * One registry is shared by many per-entity queues.
+ *
+ * @capability order-registry register order verbs (move/attack/custom) as data so engine code never branches on a verb
+ */
+export function createOrderRegistry() {
+    const kinds = new Map();
+    return {
+        define(kind) {
+            if (kinds.has(kind.kind))
+                throw new Error(`Order kind "${kind.kind}" is already defined.`);
+            kinds.set(kind.kind, kind);
+        },
+        has(kind) {
+            return kinds.has(kind);
+        },
+        get(kind) {
+            return kinds.get(kind) ?? null;
+        },
+        kinds() {
+            return [...kinds.keys()];
+        },
+    };
+}
+function cloneOrder(order) {
+    return structuredClone(order);
+}
+/**
+ * Create a per-entity order queue over a shared kind registry. The queue owns
+ * the deterministic lifecycle and preemption policy; the kinds own behavior.
+ * Nothing here is random or unbounded: id generation is injected, activation is
+ * bounded by the pending count, and a single `tick` advances at most the active
+ * order plus one activation.
+ *
+ * @capability order-queue serializable per-entity command queue with lifecycle, preemption, and pluggable order kinds
+ */
+export function createOrderQueue(registry, options = {}) {
+    const onEvent = options.onEvent;
+    let counter = 0;
+    const genId = options.genId ?? (() => `order-${++counter}`);
+    let active = options.initial ? options.initial.active : null;
+    let pending = options.initial ? [...options.initial.pending] : [];
+    function emit(type, order, reason) {
+        onEvent?.({ type, orderId: order.id, kind: order.kind, reason });
+    }
+    function markCanceled(order, reason) {
+        order.phase = "canceled";
+        order.cancelReason = reason;
+        emit("canceled", order, reason);
+    }
+    function finishActive(ctx, outcome) {
+        if (active === null)
+            return;
+        const kind = registry.get(active.kind);
+        kind?.finish?.(active, ctx, outcome);
+    }
+    /** Pull pending orders forward until one activates or the queue drains. Bounded by the pending length at entry. */
+    function activateNext(ctx, report) {
+        let budget = pending.length;
+        while (active === null && budget > 0) {
+            budget -= 1;
+            const next = pending.shift();
+            if (next === undefined)
+                return;
+            const kind = registry.get(next.kind);
+            if (kind === null) {
+                markCanceled(next, "invalid");
+                report.canceled.push({ id: next.id, reason: "invalid" });
+                continue;
+            }
+            const started = kind.start(next, ctx);
+            if (!started.ok) {
+                markCanceled(next, "invalid");
+                report.canceled.push({ id: next.id, reason: "invalid" });
+                continue;
+            }
+            next.phase = "active";
+            active = next;
+            emit("activated", next);
+            report.activated.push(next.id);
+        }
+    }
+    return {
+        issue(request) {
+            const kind = registry.get(request.kind);
+            if (kind === null)
+                return { status: "rejected", reason: `Unknown order kind "${request.kind}".` };
+            const rejection = kind.validate?.(request.payload) ?? null;
+            if (rejection)
+                return { status: "rejected", reason: rejection.reason };
+            const policy = request.policy ?? "replace";
+            if (policy === "reject" && (active !== null || pending.length > 0)) {
+                return { status: "rejected", reason: "Queue is busy and policy is reject." };
+            }
+            const order = {
+                id: request.id ?? genId(),
+                kind: request.kind,
+                payload: request.payload,
+                phase: "queued",
+                uninterruptible: request.uninterruptible ?? false,
+                ...(request.issuer !== undefined ? { issuer: request.issuer } : {}),
+            };
+            emit("issued", order);
+            if (policy === "replace") {
+                // Preempt the active order unless it is protected; a protected order
+                // finishes first and the newcomer waits at the front of the queue.
+                for (const queued of pending)
+                    markCanceled(queued, "replaced");
+                pending = [];
+                if (active !== null && !active.uninterruptible) {
+                    markCanceled(active, "replaced");
+                    active = null;
+                }
+                pending.push(order);
+                return { status: active !== null ? "queued" : "accepted", order: order };
+            }
+            if (policy === "front") {
+                pending.unshift(order);
+                return { status: active !== null ? "queued" : "accepted", order: order };
+            }
+            // append (and the empty-queue reject case)
+            pending.push(order);
+            return { status: active !== null || pending.length > 1 ? "queued" : "accepted", order: order };
+        },
+        tick(ctx, dt) {
+            const report = { active: null, activated: [], completed: [], canceled: [] };
+            if (active === null)
+                activateNext(ctx, report);
+            if (active !== null) {
+                const kind = registry.get(active.kind);
+                if (kind === null) {
+                    markCanceled(active, "invalid");
+                    report.canceled.push({ id: active.id, reason: "invalid" });
+                    active = null;
+                    activateNext(ctx, report);
+                }
+                else {
+                    const progress = kind.update(active, ctx, dt);
+                    if (progress.status === "completed") {
+                        finishActive(ctx, { phase: "completed" });
+                        active.phase = "completed";
+                        emit("completed", active);
+                        report.completed.push(active.id);
+                        active = null;
+                        activateNext(ctx, report);
+                    }
+                    else if (progress.status === "failed") {
+                        finishActive(ctx, { phase: "canceled", reason: "failed" });
+                        markCanceled(active, "failed");
+                        report.canceled.push({ id: active.id, reason: "failed" });
+                        active = null;
+                        activateNext(ctx, report);
+                    }
+                }
+            }
+            report.active = active;
+            return report;
+        },
+        active() {
+            return active;
+        },
+        pending() {
+            return [...pending];
+        },
+        isIdle() {
+            return active === null && pending.length === 0;
+        },
+        cancelActive(ctx, reason = "requested") {
+            if (active === null)
+                return;
+            finishActive(ctx, { phase: "canceled", reason });
+            markCanceled(active, reason);
+            active = null;
+        },
+        cancelAll(ctx, reason = "requested") {
+            for (const queued of pending)
+                markCanceled(queued, reason);
+            pending = [];
+            if (active !== null) {
+                finishActive(ctx, { phase: "canceled", reason });
+                markCanceled(active, reason);
+                active = null;
+            }
+        },
+        clear(ctx) {
+            this.cancelAll(ctx, "cleared");
+        },
+        serialize() {
+            return {
+                active: active ? cloneOrder(active) : null,
+                pending: pending.map(cloneOrder),
+            };
+        },
+        load(state) {
+            active = state.active ? cloneOrder(state.active) : null;
+            pending = state.pending.map(cloneOrder);
+        },
+    };
+}

package/dist/physics/drivableVehicle.d.ts

@@ -0,0 +1,29 @@
+import type { AxisInput } from "../input/axisInput.js";
+import type { KinematicVehicle, KinematicVehicleModifiers, KinematicVehicleStep } from "./kinematicVehicle.js";
+/** World-space `[x, y, z]` for a drivable vehicle's resolved pose. */
+export type DrivableVehiclePosition = readonly [number, number, number];
+/** Options for {@link tickDrivableVehicle} — ground snapping and per-tick tuning modifiers. */
+export interface DrivableVehicleOptions {
+    /** Resamples world-space Y each tick (terrain height, a ramp, a bridge deck); omit to keep the sim's own flat `y`. */
+    groundHeight?: (x: number, z: number) => number;
+    modifiers?: KinematicVehicleModifiers;
+}
+/** A `setPose`-ready patch — spread straight into `entities.setPose(vehicleId, drive.pose)`. */
+export interface DrivableVehiclePose {
+    position: DrivableVehiclePosition;
+    rotationY: number;
+    dt: number;
+}
+/** {@link tickDrivableVehicle}'s result — the ready-to-apply pose patch plus the raw sim step for HUD/telemetry reads. */
+export interface DrivableVehicleStep {
+    pose: DrivableVehiclePose;
+    step: KinematicVehicleStep;
+}
+/**
+ * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
+ * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
+ * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
+ * points; this function only steps the sim and shapes the pose patch, nothing else.
+ */
+export declare function tickDrivableVehicle(vehicle: KinematicVehicle, dt: number, axis: AxisInput, options?: DrivableVehicleOptions): DrivableVehicleStep;

package/dist/physics/drivableVehicle.js

@@ -0,0 +1,16 @@
+/**
+ * Connects an `AxisInput` sample straight through a {@link KinematicVehicle} to a scene entity's pose
+ * for one tick (#533.1) — the throttle/steer/handbrake → sim → `setPose` loop every drivable-vehicle
+ * game hand-rolled. Ground-snaps the result when `groundHeight` is given (terrain-following cars, not
+ * just flat racetracks). Pair with `scene/vehicleSeat` for who is allowed to drive and where the camera
+ * points; this function only steps the sim and shapes the pose patch, nothing else.
+ */
+export function tickDrivableVehicle(vehicle, dt, axis, options = {}) {
+    const step = vehicle.tick(dt, axis, options.modifiers);
+    const [x, y, z] = step.position;
+    const resolvedY = options.groundHeight === undefined ? y : options.groundHeight(x, z);
+    return {
+        pose: { position: [x, resolvedY, z], rotationY: step.heading, dt },
+        step,
+    };
+}

package/dist/physics/kinematicVehicle.d.ts

@@ -20,6 +20,26 @@ export interface KinematicVehicleOptions {
     surfaceFriction?: (x: number, z: number) => number;
     /** Extra velocity damping per second by world position (rough ground drag); default `0`. */
     dragAt?: (x: number, z: number) => number;
+    /**
+     * Veto or clamp a planar move before it commits — walls, closed gates, arena bounds. Given the
+     * attempted `from`→`to` on the XZ plane, return the destination actually allowed; velocity is
+     * rederived from the permitted displacement, so motion blocked on an axis stops on that axis
+     * instead of grinding into the obstacle. Default: no clamp (the move always commits).
+     */
+    clampMove?: (from: readonly [number, number], to: readonly [number, number]) => readonly [number, number];
+}
+/**
+ * Per-tick multipliers layered over the base tuning — the transient overrides games apply for one
+ * frame without rebuilding the vehicle: nitro/boost, a braced-plow bonus, or entering a speed zone or
+ * slow field. Each defaults to `1` (no change), so passing nothing leaves the base tuning untouched.
+ */
+export interface KinematicVehicleModifiers {
+    /** Scale top speed this tick (sustained boost, speed pads). */
+    topSpeedScale?: number;
+    /** Scale engine acceleration this tick (boost, brace bonus). */
+    accelScale?: number;
+    /** Scale turn rate this tick (brace penalty, heavy-load steering). */
+    turnRateScale?: number;
 }
 export interface KinematicVehicleStep {
     position: readonly [number, number, number];
@@ -39,7 +59,7 @@ export interface KinematicVehicleStep {
  * (drift meters, boost, off-track rules) via `surfaceFriction`/`dragAt` hooks and the returned slip.
  */
 export interface KinematicVehicle {
-    tick(dt: number, axis: AxisInput): KinematicVehicleStep;
+    tick(dt: number, axis: AxisInput, modifiers?: KinematicVehicleModifiers): KinematicVehicleStep;
     pose(): {
         position: readonly [number, number, number];
         heading: number;

package/dist/physics/kinematicVehicle.js

@@ -5,6 +5,7 @@ export function createKinematicVehicle(tuning, options = {}) {
     const rollingResistance = tuning.rollingResistance ?? 0;
     const surfaceFriction = options.surfaceFriction ?? (() => 1);
     const dragAt = options.dragAt ?? (() => 0);
+    const clampMove = options.clampMove;
     let x = options.position?.[0] ?? 0;
     let y = options.position?.[1] ?? 0;
     let z = options.position?.[2] ?? 0;
@@ -15,21 +16,24 @@ export function createKinematicVehicle(tuning, options = {}) {
         return [Math.sin(heading), Math.cos(heading)];
     }
     return {
-        tick(dt, axis) {
+        tick(dt, axis, modifiers) {
+            const topSpeed = tuning.topSpeed * (modifiers?.topSpeedScale ?? 1);
+            const engineAccel = tuning.engineAccel * (modifiers?.accelScale ?? 1);
+            const turnRate = tuning.turnRate * (modifiers?.turnRateScale ?? 1);
             const [fx0, fz0] = forward();
             const speed = vx * fx0 + vz * fz0;
             const steerScale = Math.min(1, Math.abs(speed) / tuning.turnSpeedRef);
             const direction = speed >= 0 ? 1 : -1;
-            heading = steerYaw(heading, axis.steer * steerScale * direction, tuning.turnRate, dt);
+            heading = steerYaw(heading, axis.steer * steerScale * direction, turnRate, dt);
             const [fx, fz] = forward();
             let accel = 0;
-            if (axis.throttle > 0 && speed < tuning.topSpeed)
-                accel += axis.throttle * tuning.engineAccel;
+            if (axis.throttle > 0 && speed < topSpeed)
+                accel += axis.throttle * engineAccel;
             if (axis.brake > 0) {
                 if (speed > 0.2)
                     accel -= axis.brake * tuning.brakeAccel;
                 else if (speed > -tuning.reverseSpeed)
-                    accel -= axis.brake * tuning.engineAccel;
+                    accel -= axis.brake * engineAccel;
             }
             vx += fx * accel * dt;
             vz += fz * accel * dt;
@@ -52,13 +56,24 @@ export function createKinematicVehicle(tuning, options = {}) {
                 vx *= dragDamp;
                 vz *= dragDamp;
             }
-            x += vx * dt;
-            z += vz * dt;
+            const toX = x + vx * dt;
+            const toZ = z + vz * dt;
+            if (clampMove !== undefined && dt > 0) {
+                const allowed = clampMove([x, z], [toX, toZ]);
+                vx = (allowed[0] - x) / dt;
+                vz = (allowed[1] - z) / dt;
+                x = allowed[0];
+                z = allowed[1];
+            }
+            else {
+                x = toX;
+                z = toZ;
+            }
             return {
                 position: [x, y, z],
                 heading,
                 forwardSpeed: vx * fx + vz * fz,
-                lateralSpeed: keptLateral * dragDamp,
+                lateralSpeed: -vx * fz + vz * fx,
                 slip,
                 surface,
             };

package/dist/physics/physicsWorld.d.ts

@@ -2,6 +2,12 @@ export interface PhysicsBounds {
     min: readonly [number, number, number];
     max: readonly [number, number, number];
 }
+/**
+ * Simulation fidelity intent: `low` (cheap — many bodies, loose stacks, forgiving sleep), `standard`
+ * (default), `high` (tight stacks, accurate joints, worth the extra solver work). Sets the solver
+ * knobs below to a matched preset; an individual knob left explicit always wins over the preset.
+ */
+export type PhysicsPrecision = "low" | "standard" | "high";
 export interface PhysicsWorldConfig {
     /** Maximum bodies the SoA buffers can hold. Fixed at construction; no reallocation later. */
     capacity: number;
@@ -9,8 +15,8 @@ export interface PhysicsWorldConfig {
     bounds: PhysicsBounds;
     /** Downward acceleration applied to awake bodies each substep. Default -20. */
     gravity?: number;
-    /** Broadphase cell edge; tune to ≈ small-body diameter. Default 1. */
-    cellSize?: number;
+    /** Simulation fidelity intent. Default "standard" — see {@link PhysicsPrecision}. */
+    precision?: PhysicsPrecision;
     /** Fixed substep length in seconds. Default 1/60. */
     fixedDt?: number;
     /** Cap on substeps per `step()` — bounds catch-up work, drops the rest. Default 4. */
@@ -23,21 +29,27 @@ export interface PhysicsWorldConfig {
     friction?: number;
     /** Per-second linear velocity damping (physical energy bleed so piles settle and sleep). Default 0.2. */
     linearDamping?: number;
-    /** Sequential-impulse velocity iterations per substep (higher = more stable stacks). Default 4. */
+    /** Speed at or below which a body counts as still. Default 0.08. */
+    sleepLinearVelocity?: number;
+    /** Maximum simultaneous joints the constraint buffers can hold. Default 256. */
+    jointCapacity?: number;
+    /**
+     * @deprecated Advanced escape hatch — tune only when profiling shows the broadphase grid is the
+     * bottleneck; most games never set this. Broadphase cell edge; ideally ≈ small-body diameter.
+     * Default 1.
+     */
+    cellSize?: number;
+    /** @deprecated Advanced escape hatch — prefer `precision`. Sequential-impulse velocity iterations per substep (higher = more stable stacks). */
     solverIterations?: number;
-    /** Baumgarte positional-correction fraction per substep, 0..1. Default 0.2. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Baumgarte positional-correction fraction per substep, 0..1. */
     correctionFactor?: number;
-    /** Penetration tolerated before correction kicks in. Default 0.005. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Penetration tolerated before correction kicks in. Default 0.005. */
     slop?: number;
-    /** Speed at or below which a body counts as still. Default 0.08. */
-    sleepLinearVelocity?: number;
-    /** Consecutive still substeps before a body sleeps. Default 30. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Consecutive still substeps before a body sleeps. */
     sleepThresholdSteps?: number;
-    /** Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). Default 0.5. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Approach speed a contact must exceed to wake a sleeping body (resting contacts don't). */
     wakeThreshold?: number;
-    /** Maximum simultaneous joints the constraint buffers can hold. Default 256. */
-    jointCapacity?: number;
-    /** Baumgarte fraction applied to hard-joint positional error per iteration, 0..1. Default 0.5. */
+    /** @deprecated Advanced escape hatch — prefer `precision`. Baumgarte fraction applied to hard-joint positional error per iteration, 0..1. */
     jointCorrection?: number;
 }
 export interface PhysicsStats {

package/dist/physics/physicsWorld.js

@@ -1,3 +1,8 @@
+const PHYSICS_PRECISION_PRESETS = {
+    low: { solverIterations: 2, correctionFactor: 0.15, sleepThresholdSteps: 15, wakeThreshold: 0.75, jointCorrection: 0.35 },
+    standard: { solverIterations: 4, correctionFactor: 0.2, sleepThresholdSteps: 30, wakeThreshold: 0.5, jointCorrection: 0.5 },
+    high: { solverIterations: 8, correctionFactor: 0.3, sleepThresholdSteps: 45, wakeThreshold: 0.35, jointCorrection: 0.65 },
+};
 export const SHAPE_BOX = 0;
 export const SHAPE_SPHERE = 1;
 export const JOINT_FIXED = 0;
@@ -119,6 +124,7 @@ export class PhysicsWorld {
         stepMs: 0,
     };
     constructor(config) {
+        const preset = PHYSICS_PRECISION_PRESETS[config.precision ?? "standard"];
         this.capacity = config.capacity;
         this.bounds = { min: config.bounds.min, max: config.bounds.max };
         this.gravity = config.gravity ?? -20;
@@ -129,16 +135,16 @@ export class PhysicsWorld {
         this.restitutionThreshold = config.restitutionThreshold ?? 1;
         this.friction = config.friction ?? 0.4;
         this.linearDamping = config.linearDamping ?? 0.2;
-        this.solverIterations = Math.max(1, config.solverIterations ?? 4);
-        this.correctionFactor = config.correctionFactor ?? 0.2;
+        this.solverIterations = Math.max(1, config.solverIterations ?? preset.solverIterations);
+        this.correctionFactor = config.correctionFactor ?? preset.correctionFactor;
         this.slop = config.slop ?? 0.005;
         const sleepV = config.sleepLinearVelocity ?? 0.08;
         const sleepMoveEps = sleepV * this.fixedDt;
         this.sleepMove2 = sleepMoveEps * sleepMoveEps;
-        this.sleepSteps = config.sleepThresholdSteps ?? 30;
-        this.wakeThreshold = config.wakeThreshold ?? 0.5;
+        this.sleepSteps = config.sleepThresholdSteps ?? preset.sleepThresholdSteps;
+        this.wakeThreshold = config.wakeThreshold ?? preset.wakeThreshold;
         this.jointCapacity = Math.max(0, config.jointCapacity ?? 256);
-        this.jointCorrection = config.jointCorrection ?? 0.5;
+        this.jointCorrection = config.jointCorrection ?? preset.jointCorrection;
         const cap = config.capacity;
         this.posX = new Float32Array(cap);
         this.posY = new Float32Array(cap);

package/dist/physics/radialImpulse.d.ts

@@ -0,0 +1,25 @@
+/** How a radial impulse fades from the blast center to its edge. */
+export type RadialFalloff = "linear" | "quadratic" | "none";
+/** A radial push: the impulse vector plus the 0..1 falloff sampled at the target. */
+export interface RadialImpulse {
+    /** Impulse along the first axis (direction × magnitude). */
+    x: number;
+    /** Impulse along the second axis (direction × magnitude). */
+    y: number;
+    /** Impulse magnitude = `power` × `falloff`. */
+    magnitude: number;
+    /** Falloff weight at the target, 1 at the center down to 0 at the radius. */
+    falloff: number;
+}
+/** Options for {@link radialImpulse}. */
+export interface RadialImpulseOptions {
+    /** Falloff shape. Defaults to `"linear"` (`1 − d/r`). */
+    falloff?: RadialFalloff;
+}
+/**
+ * Point-source radial impulse pushing a `target` away from a blast `source`: full `power` at the center
+ * fading to zero at `radius`. Returns `null` when the target sits at or beyond the radius (unaffected),
+ * so callers can early-out. At the exact center the direction is zero. This is the explosion/knockback/
+ * shockwave push — every arena game hand-rolled the distance, falloff, and normalize.
+ */
+export declare function radialImpulse(source: readonly [number, number], target: readonly [number, number], radius: number, power: number, options?: RadialImpulseOptions): RadialImpulse | null;

package/dist/physics/radialImpulse.js

@@ -0,0 +1,27 @@
+function falloffAt(distance, radius, shape) {
+    const linear = 1 - distance / radius;
+    if (shape === "none")
+        return 1;
+    if (shape === "quadratic")
+        return linear * linear;
+    return linear;
+}
+/**
+ * Point-source radial impulse pushing a `target` away from a blast `source`: full `power` at the center
+ * fading to zero at `radius`. Returns `null` when the target sits at or beyond the radius (unaffected),
+ * so callers can early-out. At the exact center the direction is zero. This is the explosion/knockback/
+ * shockwave push — every arena game hand-rolled the distance, falloff, and normalize.
+ */
+export function radialImpulse(source, target, radius, power, options = {}) {
+    if (radius <= 0)
+        return null;
+    const dx = target[0] - source[0];
+    const dy = target[1] - source[1];
+    const distance = Math.hypot(dx, dy);
+    if (distance >= radius)
+        return null;
+    const falloff = falloffAt(distance, radius, options.falloff ?? "linear");
+    const magnitude = power * falloff;
+    const invLen = distance > 1e-6 ? 1 / distance : 0;
+    return { x: dx * invLen * magnitude, y: dy * invLen * magnitude, magnitude, falloff };
+}

package/dist/procedural.d.ts

@@ -0,0 +1,3 @@
+export { createDecayMeterSet, type DecayMeterSet } from "./survival/decayMeter.js";
+export { createMoodleStack, stackMoodles, type Moodle, type MoodleStack } from "./survival/moodle.js";
+export { createMultiRegionHealth, type MultiRegionHealth } from "./survival/regionHealth.js";

package/dist/procedural.js

@@ -0,0 +1,3 @@
+export { createDecayMeterSet } from "./survival/decayMeter.js";
+export { createMoodleStack, stackMoodles } from "./survival/moodle.js";
+export { createMultiRegionHealth } from "./survival/regionHealth.js";

package/dist/progression/statGraph.d.ts

@@ -0,0 +1,116 @@
+import type { StatModifierSet } from "../stats/statModifiers.js";
+/**
+ * A game-owned named input value. The engine ships no attribute vocabulary — ids,
+ * bounds, defaults, and metadata are entirely caller data, so the same graph can
+ * model STR/AGI/INT, SPECIAL scores, skills, difficulty knobs, or anything else.
+ */
+export interface StatInputDef {
+    id: string;
+    /** Default base value a fresh sheet starts at. Defaults to `min ?? 0`. */
+    base?: number;
+    /** Lower bound applied to the resolved value. */
+    min?: number;
+    /** Upper bound applied to the resolved value. */
+    max?: number;
+    /** Free-form, engine-ignored metadata (labels, descriptions, UI hints). */
+    meta?: Readonly<Record<string, unknown>>;
+}
+/** How a single contribution folds into a running value. */
+export type StatOp = "add" | "mul" | "override" | "clampMin" | "clampMax";
+/**
+ * One folded contribution to a value, retained so a sheet can explain
+ * "why is this value 42?" — every step carries the source that produced it.
+ */
+export interface StatContribution {
+    /** Provenance label — who/what produced this contribution. */
+    source: string;
+    op: StatOp;
+    value: number;
+}
+/** A modifier entry targeting one stat: a single contribution or an ordered list. */
+export type StatModEntry = StatContribution | readonly StatContribution[];
+/** The read-only view a derived formula gets: resolved values of its declared dependencies. */
+export interface StatDeriveContext {
+    /** Resolved (fully modified) value of a declared dependency (input or derived). */
+    value(id: string): number;
+}
+/**
+ * A derived value whose formula and dependencies are caller-owned. `compute` may
+ * return a scalar (shorthand for a single `add`) or an ordered list of contributions
+ * folded left-to-right, so additive/multiplicative/clamped and conditional modifiers
+ * are all expressed as plain data or branches inside the function.
+ */
+export interface StatDerivedDef {
+    id: string;
+    /** ids (inputs or other derived) this formula reads — drives ordering, cycle detection, and selective recompute. */
+    deps?: readonly string[];
+    min?: number;
+    max?: number;
+    round?: "floor" | "ceil" | "round";
+    meta?: Readonly<Record<string, unknown>>;
+    compute(ctx: StatDeriveContext): number | readonly StatContribution[];
+}
+/** The full schema of a stat graph: its named inputs and caller-authored derived formulas. */
+export interface StatGraphDef {
+    inputs: readonly StatInputDef[];
+    derived?: readonly StatDerivedDef[];
+}
+/** Plain-data, JSON-safe sheet state: input base values plus registered modifier sources. */
+export interface StatSheetState {
+    base: Record<string, number>;
+    sources: Record<string, Record<string, StatContribution[]>>;
+}
+/** One line of a provenance trace: a contribution plus the running total after it folds in. */
+export interface StatContributionStep extends StatContribution {
+    /** Running total after this contribution folds in. */
+    subtotal: number;
+}
+/** A full provenance trace for one stat: the ordered steps that produced its value. */
+export interface StatExplanation {
+    id: string;
+    value: number;
+    steps: StatContributionStep[];
+}
+/** A live per-entity instance of a {@link StatGraph}: mutable base values and modifier sources over a shared schema. */
+export interface StatSheet {
+    /** Resolve the fully modified value of an input or derived stat. */
+    get(id: string): number;
+    /** The stored base of an input stat (before modifiers/clamping). */
+    getBase(id: string): number;
+    setBase(id: string, value: number): void;
+    /** Register (or replace) a named modifier source targeting one or more stats. */
+    addSource(sourceId: string, mods: Record<string, StatModEntry>): void;
+    removeSource(sourceId: string): boolean;
+    hasSource(sourceId: string): boolean;
+    sources(): string[];
+    /** Resolve every input and derived stat into a plain record. */
+    values(): Record<string, number>;
+    /** Ordered contribution trace explaining a stat's current value. */
+    explain(id: string): StatExplanation;
+    /** Resolve values under a proposed, uncommitted mutation (e.g. a previewed allocation). */
+    preview(mutate: (draft: StatSheet) => void): Record<string, number>;
+    toJSON(): StatSheetState;
+}
+/** A compiled, immutable stat-graph schema that mints per-entity {@link StatSheet}s from base values or saved state. */
+export interface StatGraph {
+    readonly inputIds: readonly string[];
+    readonly derivedIds: readonly string[];
+    create(base?: Record<string, number>): StatSheet;
+    restore(state: StatSheetState): StatSheet;
+}
+/**
+ * A data-driven stat graph: game-owned named inputs feed caller-authored derived
+ * formulas, with contribution provenance, uncommitted previews, cycle detection, and
+ * selective recomputation. Formula semantics and numeric tables stay entirely game-defined.
+ *
+ * @capability stat-graph derive game-defined stats from named inputs with provenance and preview
+ */
+export declare function createStatGraph(def: StatGraphDef): StatGraph;
+/**
+ * Bridge the shared {@link StatModifierSet} shape (add/multiply, used by talents, items,
+ * and buffs) into stat-graph contributions, so a ranked talent tree or gear roll feeds
+ * the graph as one named source instead of a parallel store.
+ *
+ * @capability stat-graph-bridge feed an existing StatModifierSet into a stat-graph source
+ */
+export declare function statModifierContributions<TStat extends string>(source: string, set: StatModifierSet<TStat>): Record<string, StatContribution[]>;