@jgengine/core 0.10.0 → 0.11.0

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[]>;