@jgengine/core 0.26.0 → 0.28.0

package/dist/physics/kinematicVehicle.d.ts

@@ -44,6 +44,13 @@ export interface KinematicVehicleTuning {
     steering?: KinematicSteeringTuning;
     /** Optional aerodynamic drag/downforce and electronic driver assists. */
     dynamics?: KinematicDynamicsTuning;
+    /**
+     * Optional load-transfer handling: the tires' combined grip falls as weight moves off a corner, so a
+     * car on the brakes into a corner holds less slide than the same car coasting, and a hard corner
+     * itself costs grip. Bounded by the geometry (never diverges) and reported per tick as
+     * {@link KinematicVehicleStep.weightTransfer}. Omit to keep the flat-grip model.
+     */
+    weightTransfer?: KinematicWeightTransferTuning;
     /**
      * Optional mass-and-force chassis layer (#1051). When present it supersedes `engineAccel`/`brakeAccel`
      * with force/mass dynamics — a tire friction budget, lateral weight transfer, and engine braking — so
@@ -120,6 +127,23 @@ export interface KinematicDynamicsTuning {
     maxBodyRoll?: number;
     attitudeResponse?: number;
 }
+/**
+ * Load-transfer handling for the arcade model. Weight moves under braking, traction and cornering; the
+ * tire that goes light loses more grip than the loaded one gains (load sensitivity), so the axle's
+ * combined grip falls. Every term is bounded by the geometry, and `sensitivity` caps the loss, so the
+ * transfer can never drive grip negative or diverge. For per-axle balance from tire forces, use
+ * `createVehicleDynamics` (`physics/vehicleDynamics`) instead.
+ */
+export interface KinematicWeightTransferTuning {
+    /** Centre-of-mass height, m. */
+    comHeight: number;
+    /** Wheelbase, m; sets longitudinal transfer under braking and traction. */
+    wheelbase: number;
+    /** Track width, m; sets lateral transfer under cornering. */
+    trackWidth: number;
+    /** Grip lost per unit of total load transfer (default `0.35`); the tire load sensitivity. */
+    sensitivity?: number;
+}
 export interface KinematicVehicleOptions {
     position?: readonly [number, number, number];
     heading?: number;
@@ -157,6 +181,11 @@ export interface KinematicVehicleModifiers {
      * Separate from `accelScale` because stronger drive and stronger brakes are not the same upgrade.
      */
     brakeScale?: number;
+    /**
+     * Scale the tire grip curve this tick (damage, a low-grip zone, a temporary debuff). Mirrors the
+     * `gripScale` on `VehicleDynamicsModifiers`, so a damage layer's per-tick output drives either sim.
+     */
+    gripScale?: number;
 }
 export interface KinematicVehicleStep {
     position: readonly [number, number, number];
@@ -168,6 +197,13 @@ export interface KinematicVehicleStep {
     slip: number;
     /** The `surfaceFriction` sample used this tick (`< 1` = off the ideal surface). */
     surface: number;
+    /**
+     * Total load transfer this tick, `0..1`: longitudinal (braking/traction) plus lateral (cornering)
+     * weight movement as a fraction of the vehicle's weight. Always `0` without a `weightTransfer` block.
+     */
+    weightTransfer: number;
+    /** The grip multiplier the load transfer applied this tick (`1` = no loss); always `1` without the block. */
+    loadGrip: number;
     /** One-based forward gear, or `0` while reversing/neutral. */
     gear: number;
     rpm: number;

package/dist/physics/kinematicVehicle.js

@@ -188,7 +188,19 @@ export function createKinematicVehicle(initialTuning, options = {}) {
             const slip = Math.abs(lateralSpeed) / (Math.abs(forwardSpeed) + 1);
             const handbrakeFactor = 1 - axis.handbrake * (1 - tuning.handbrakeGrip);
             const downforce = 1 + (tuning.dynamics?.downforce ?? 0) * Math.min(1, Math.abs(forwardSpeed) / Math.max(1, topSpeed));
-            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor * downforce;
+            // Load transfer: longitudinal from the commanded accel, lateral from the cornering demand. Both are
+            // fractions of weight, so the same car on the brakes into a corner and coasting through it differ
+            // by this term alone. `loadGrip` is floored so the loss stays a feel change, never a black hole.
+            const transfer = tuning.weightTransfer;
+            let weightTransfer = 0;
+            let loadGrip = 1;
+            if (transfer !== undefined) {
+                const longitudinal = (Math.abs(accel) * transfer.comHeight) / (Math.max(0.1, transfer.wheelbase) * GRAVITY);
+                const lateral = (Math.abs(yawRate * forwardSpeed) * transfer.comHeight) / (Math.max(0.1, transfer.trackWidth) * GRAVITY);
+                weightTransfer = Math.min(1, longitudinal + lateral);
+                loadGrip = Math.max(0.3, 1 - (transfer.sensitivity ?? 0.35) * weightTransfer);
+            }
+            const gripValue = sampleGripCurve(grip, slip) * surface * handbrakeFactor * downforce * loadGrip * (modifiers?.gripScale ?? 1);
             const keep = Math.max(0, 1 - gripValue * tuning.gripStrength * dt);
             // ESC fights intentional slides — ease it off while the handbrake is held so drift stays steerable.
             const stability = (tuning.dynamics?.stabilityControl ?? 0) * (1 - 0.85 * axis.handbrake);
@@ -285,6 +297,8 @@ export function createKinematicVehicle(initialTuning, options = {}) {
                 lateralSpeed: -vx * fz + vz * fx,
                 slip,
                 surface,
+                weightTransfer,
+                loadGrip,
                 gear: speed < -0.2 ? 0 : gearIndex + 1,
                 rpm,
                 steerAngle,

package/dist/physics/vehicleDamage.d.ts

@@ -0,0 +1,136 @@
+import type { AxisInput } from "../input/axisInput.js";
+import type { KinematicVehicleModifiers, KinematicVehicleTuning } from "./kinematicVehicle.js";
+/**
+ * Handling change one damage zone applies at its *last* stage. Multiplier fields read `1` = undamaged,
+ * and a zone part-way through its stages gets the fraction between; `steerPull` and `drag` are additive
+ * and reach their full value only at the last stage.
+ */
+export interface VehicleDamageEffect {
+    /** Tire grip multiplier at full damage (`< 1` loses grip). */
+    gripScale?: number;
+    /** Drive-force multiplier at full damage. */
+    engineScale?: number;
+    brakeScale?: number;
+    topSpeedScale?: number;
+    /** Steering bias in radians at full damage — a bent frame that pulls one way. */
+    steerPull?: number;
+    /** Extra coast drag per second at full damage. */
+    drag?: number;
+}
+/**
+ * One damageable zone: a fixed local body point, the impulse thresholds that step it through its
+ * stages, the bounded dent it shows, and the handling it costs. There is no mesh editing — a zone's
+ * deformation is one displacement it can never exceed, so the visual can never grow without limit.
+ */
+export interface VehicleDamageZone {
+    id: string;
+    /** Local body point in metres (x right, y up, z forward); picks the zone nearest an impact and anchors the dent. */
+    at: readonly [number, number, number];
+    /** Impulse thresholds; the count is the zone's stage count, and the last stage is fully damaged. */
+    thresholds: readonly number[];
+    /** Dent displacement in metres at the last stage, scaled by stage. Omit for a zone that only changes handling. */
+    deform?: readonly [number, number, number];
+    /** Stage at which the part comes off (the renderer hides or drops it); omit to never detach. */
+    detachStage?: number;
+    /** Handling change at the last stage, reached proportionally across the stages. */
+    effect?: VehicleDamageEffect;
+}
+/** Live state of one zone, as a HUD or a save reads it. */
+export interface VehicleDamageZoneState {
+    id: string;
+    accumulated: number;
+    stage: number;
+    detached: boolean;
+}
+/** Serializable damage state: {@link VehicleDamage.restore} needs only this. */
+export interface VehicleDamageState {
+    zones: VehicleDamageZoneState[];
+    total: number;
+    disabled: boolean;
+}
+/** A zone crossing a threshold this tick — the event a HUD feed, a smoke puff or a camera shake keys off. */
+export interface VehicleDamageTransition {
+    zone: string;
+    stage: number;
+    previousStage: number;
+    detached: boolean;
+    disabled: boolean;
+    total: number;
+}
+/** A zone's current dent: a bounded local displacement and whether the part has come off. */
+export interface VehicleDeformation {
+    zoneId: string;
+    stage: number;
+    /** Local displacement in metres, never larger than the zone's `deform`. */
+    offset: readonly [number, number, number];
+    /** The part has come off — the renderer hides or drops it. */
+    detached: boolean;
+}
+/** Every zone's handling cost summed into one set of numbers (all fields present, defaults filled). */
+export interface VehicleDamageEffectResolved {
+    gripScale: number;
+    engineScale: number;
+    brakeScale: number;
+    topSpeedScale: number;
+    steerPull: number;
+    drag: number;
+}
+/** Everything {@link createVehicleDamage} needs. */
+export interface VehicleDamageConfig {
+    zones: readonly VehicleDamageZone[];
+    /** Total accumulated impulse across every zone that disables the vehicle; omit to never disable. */
+    disableAt?: number;
+    /** Called on each threshold crossing, for HUD/feed/audio. */
+    onTransition?: (transition: VehicleDamageTransition) => void;
+    /** Register a devtools probe under this name so the perf overlay shows the damage summary. */
+    devtoolsName?: string;
+}
+/**
+ * Fixed-zone crash damage for a vehicle: impacts accumulate into discrete stages, stages change handling
+ * and show a bounded dent, and a part can come off at a set stage. Data-driven and bounded by
+ * construction — the zone set is authored, each zone's deformation is one capped displacement, and no
+ * mesh is edited. Serializes through {@link snapshot}/{@link restore}, so a save, a replay or a host
+ * correction resumes mid-crash.
+ */
+export interface VehicleDamage {
+    /**
+     * Route an impulse to the zone nearest a local body hit point (x right, y up, z forward) and return
+     * the transitions it caused — empty when nothing crossed a threshold. The caller rotates a world
+     * impact into body space; this module never reads the world.
+     */
+    hit(local: readonly [number, number, number], impulse: number): readonly VehicleDamageTransition[];
+    /** Add impulse straight to a named zone; null for an unknown zone or a non-positive impulse. */
+    impact(zoneId: string, impulse: number): VehicleDamageTransition | null;
+    stageOf(zoneId: string): number;
+    zones(): readonly VehicleDamageZoneState[];
+    /** Summed handling change across every zone at its current stage. */
+    effect(): VehicleDamageEffectResolved;
+    /** Bounded visual deformation, one entry per zone that has taken a stage — the render hook. */
+    deformation(): readonly VehicleDeformation[];
+    total(): number;
+    disabled(): boolean;
+    /**
+     * Per-tick modifiers the sim applies for one frame. Use this for a scratch or a reset that should not
+     * rebuild the tuning; for lasting damage call {@link damagedTuning} and `retune` once per change.
+     */
+    modifiers(): KinematicVehicleModifiers;
+    snapshot(): VehicleDamageState;
+    restore(next: VehicleDamageState): void;
+    reset(): void;
+    /** Drop the devtools probe registered by `devtoolsName`. Safe to call twice. */
+    dispose(): void;
+}
+/**
+ * Fixed-zone crash damage (issue #86's stage model) wired to handling and visuals: see {@link VehicleDamage}.
+ *
+ * @capability vehicle-damage fixed-zone crash damage that changes handling and shows a bounded dent, serializable
+ */
+export declare function createVehicleDamage(config: VehicleDamageConfig): VehicleDamage;
+/**
+ * Bake a damage effect into a tuning — the lasting-damage path. Hand the result to the sim's `retune`,
+ * which keeps the vehicle's momentum; the base tuning is not mutated, so a repair is the same call with
+ * the undamaged base.
+ */
+export declare function damagedTuning(base: KinematicVehicleTuning, effect: VehicleDamageEffectResolved): KinematicVehicleTuning;
+/** Apply a damage `steerPull` to a steer axis, clamped to the input range — a bent frame pulling one way. */
+export declare function damagedAxis(axis: AxisInput, effect: VehicleDamageEffectResolved): AxisInput;

package/dist/physics/vehicleDamage.js

@@ -0,0 +1,214 @@
+import { devtools } from "../devtools/devtools.js";
+const NO_EFFECT = {
+    gripScale: 1,
+    engineScale: 1,
+    brakeScale: 1,
+    topSpeedScale: 1,
+    steerPull: 0,
+    drag: 0,
+};
+function stageFor(thresholds, accumulated) {
+    let stage = 0;
+    for (const threshold of thresholds) {
+        if (accumulated >= threshold)
+            stage += 1;
+        else
+            break;
+    }
+    return stage;
+}
+/**
+ * Fixed-zone crash damage (issue #86's stage model) wired to handling and visuals: see {@link VehicleDamage}.
+ *
+ * @capability vehicle-damage fixed-zone crash damage that changes handling and shows a bounded dent, serializable
+ */
+export function createVehicleDamage(config) {
+    const order = [];
+    const defs = new Map();
+    const states = new Map();
+    for (const zone of config.zones) {
+        if (defs.has(zone.id))
+            throw new Error(`duplicate damage zone: ${zone.id}`);
+        defs.set(zone.id, zone);
+        states.set(zone.id, { id: zone.id, accumulated: 0, stage: 0, detached: false });
+        order.push(zone.id);
+    }
+    const disableAt = config.disableAt ?? null;
+    let totalImpulse = 0;
+    let disabledFlag = false;
+    function absorb(zoneId, impulse) {
+        const def = defs.get(zoneId);
+        const state = states.get(zoneId);
+        if (def === undefined || state === undefined || !(impulse > 0))
+            return null;
+        const previousStage = state.stage;
+        const wasDisabled = disabledFlag;
+        state.accumulated += impulse;
+        totalImpulse += impulse;
+        state.stage = Math.min(def.thresholds.length, stageFor(def.thresholds, state.accumulated));
+        let detachedNow = false;
+        if (def.detachStage !== undefined && !state.detached && state.stage >= def.detachStage) {
+            state.detached = true;
+            detachedNow = true;
+        }
+        if (disableAt !== null && totalImpulse >= disableAt)
+            disabledFlag = true;
+        if (state.stage === previousStage && !detachedNow && disabledFlag === wasDisabled)
+            return null;
+        const transition = {
+            zone: zoneId,
+            stage: state.stage,
+            previousStage,
+            detached: state.detached,
+            disabled: disabledFlag,
+            total: totalImpulse,
+        };
+        config.onTransition?.(transition);
+        return transition;
+    }
+    function factorOf(def, stage) {
+        const maxStage = def.thresholds.length;
+        return maxStage <= 0 ? 0 : Math.min(1, stage / maxStage);
+    }
+    function resolveEffect() {
+        const out = { ...NO_EFFECT };
+        for (const id of order) {
+            const def = defs.get(id);
+            const effect = def.effect;
+            if (effect === undefined)
+                continue;
+            const factor = factorOf(def, states.get(id).stage);
+            if (factor <= 0)
+                continue;
+            out.gripScale *= 1 + ((effect.gripScale ?? 1) - 1) * factor;
+            out.engineScale *= 1 + ((effect.engineScale ?? 1) - 1) * factor;
+            out.brakeScale *= 1 + ((effect.brakeScale ?? 1) - 1) * factor;
+            out.topSpeedScale *= 1 + ((effect.topSpeedScale ?? 1) - 1) * factor;
+            out.steerPull += (effect.steerPull ?? 0) * factor;
+            out.drag += (effect.drag ?? 0) * factor;
+        }
+        return out;
+    }
+    const unregister = config.devtoolsName === undefined ? null : devtools.probes.register(config.devtoolsName, probeLine);
+    function probeLine() {
+        let worst = 0;
+        let detached = 0;
+        for (const id of order) {
+            const state = states.get(id);
+            if (state.stage > worst)
+                worst = state.stage;
+            if (state.detached)
+                detached += 1;
+        }
+        return `${order.length} zones ${worst} stages ${detached} detached ${totalImpulse.toFixed(0)} impulse${disabledFlag ? " disabled" : ""}`;
+    }
+    return {
+        hit(local, impulse) {
+            if (!(impulse > 0))
+                return [];
+            let best = null;
+            let bestSq = Number.POSITIVE_INFINITY;
+            for (const id of order) {
+                const at = defs.get(id).at;
+                const dx = local[0] - at[0];
+                const dy = local[1] - at[1];
+                const dz = local[2] - at[2];
+                const distSq = dx * dx + dy * dy + dz * dz;
+                if (distSq < bestSq) {
+                    bestSq = distSq;
+                    best = id;
+                }
+            }
+            if (best === null)
+                return [];
+            const transition = absorb(best, impulse);
+            return transition === null ? [] : [transition];
+        },
+        impact: (zoneId, impulse) => absorb(zoneId, impulse),
+        stageOf: (zoneId) => states.get(zoneId)?.stage ?? 0,
+        zones: () => order.map((id) => ({ ...states.get(id) })),
+        effect: resolveEffect,
+        deformation() {
+            const out = [];
+            for (const id of order) {
+                const def = defs.get(id);
+                const state = states.get(id);
+                if (state.stage <= 0)
+                    continue;
+                const factor = factorOf(def, state.stage);
+                const dent = def.deform;
+                out.push({
+                    zoneId: id,
+                    stage: state.stage,
+                    offset: dent === undefined
+                        ? [0, 0, 0]
+                        : [dent[0] * factor, dent[1] * factor, dent[2] * factor],
+                    detached: state.detached,
+                });
+            }
+            return out;
+        },
+        total: () => totalImpulse,
+        disabled: () => disabledFlag,
+        modifiers() {
+            const effect = resolveEffect();
+            return {
+                topSpeedScale: effect.topSpeedScale,
+                accelScale: effect.engineScale,
+                brakeScale: effect.brakeScale,
+                gripScale: effect.gripScale,
+            };
+        },
+        snapshot: () => ({
+            zones: order.map((id) => ({ ...states.get(id) })),
+            total: totalImpulse,
+            disabled: disabledFlag,
+        }),
+        restore(next) {
+            for (const saved of next.zones) {
+                const state = states.get(saved.id);
+                if (state === undefined)
+                    continue;
+                state.accumulated = saved.accumulated;
+                state.stage = Math.min(defs.get(saved.id).thresholds.length, Math.max(0, saved.stage));
+                state.detached = saved.detached;
+            }
+            totalImpulse = next.total;
+            disabledFlag = next.disabled;
+        },
+        reset() {
+            for (const id of order) {
+                const state = states.get(id);
+                state.accumulated = 0;
+                state.stage = 0;
+                state.detached = false;
+            }
+            totalImpulse = 0;
+            disabledFlag = false;
+        },
+        dispose() {
+            unregister?.();
+        },
+    };
+}
+/**
+ * Bake a damage effect into a tuning — the lasting-damage path. Hand the result to the sim's `retune`,
+ * which keeps the vehicle's momentum; the base tuning is not mutated, so a repair is the same call with
+ * the undamaged base.
+ */
+export function damagedTuning(base, effect) {
+    return {
+        ...base,
+        engineAccel: base.engineAccel * effect.engineScale,
+        brakeAccel: base.brakeAccel * effect.brakeScale,
+        topSpeed: base.topSpeed * effect.topSpeedScale,
+        gripStrength: base.gripStrength * effect.gripScale,
+        coastDeceleration: (base.coastDeceleration ?? 0) + effect.drag,
+    };
+}
+/** Apply a damage `steerPull` to a steer axis, clamped to the input range — a bent frame pulling one way. */
+export function damagedAxis(axis, effect) {
+    if (effect.steerPull === 0)
+        return axis;
+    return { ...axis, steer: Math.max(-1, Math.min(1, axis.steer + effect.steerPull)) };
+}

package/dist/physics/vehicleParts.d.ts

@@ -0,0 +1,62 @@
+import type { KinematicVehicleTuning } from "./kinematicVehicle.js";
+import { type GripCurve } from "./vehicleBody.js";
+/** A tunable vehicle number a part can move; each names a {@link KinematicVehicleTuning} field. */
+export type VehicleStat = "engineAccel" | "brakeAccel" | "topSpeed" | "reverseSpeed" | "turnRate" | "turnSpeedRef" | "gripStrength" | "handbrakeGrip" | "rollingResistance" | "coastDeceleration";
+/** How one part moves a stat: multiply the base by `scale`, then add `add`. Both default to no change. */
+export interface VehiclePartEffect {
+    scale?: number;
+    add?: number;
+}
+/**
+ * One installable part. `slot` is the caller's own grouping ("tires", "engine", "front-bumper") — the
+ * engine does not name slots, so a game's upgrade tree stays its own. Effects compose in install order,
+ * and a part's `gripCurve` replaces the base tire compound outright (last one installed wins).
+ */
+export interface VehiclePart {
+    id: string;
+    slot: string;
+    effects?: Partial<Record<VehicleStat, VehiclePartEffect>>;
+    /** Tire compound: replaces the base grip curve when installed. */
+    gripCurve?: GripCurve;
+}
+/**
+ * Comparable handling numbers derived from a tuning — what "the numbers and the feel" means to a shop
+ * screen, a HUD or a test. Grip is reported as the curve's own shape, so a compound change shows up as
+ * a moved peak rather than a single scalar.
+ */
+export interface VehicleFeel {
+    topSpeed: number;
+    engineAccel: number;
+    brakeAccel: number;
+    turnRate: number;
+    handbrakeGrip: number;
+    /** Grip available before the tire breaks away (the curve's highest point). */
+    peakGrip: number;
+    /** Slip where that peak sits — the far end of a flat plateau, so it reads as the breakaway slip. */
+    peakSlip: number;
+    /** Grip left once the tire is fully sliding (the curve at slip 1). */
+    slideGrip: number;
+}
+/** Read the handling numbers out of any tuning — base or parts-composed. */
+export declare function feelOf(tuning: KinematicVehicleTuning): VehicleFeel;
+/** A composed vehicle: the tuning to hand the sim, the feel it produces, and what was installed. */
+export interface VehicleSetup {
+    tuning: KinematicVehicleTuning;
+    feel: VehicleFeel;
+    /** Installed part ids, in install order. */
+    parts: readonly string[];
+}
+/**
+ * Fold parts onto a base tuning: every effect scales then adds onto the running value, in array order,
+ * so a setup is deterministic and a caller can reason about which part moved what. The base tuning is
+ * never mutated, so the same base can seed several builds.
+ *
+ * @capability vehicle-parts compose data-driven tuning parts (tires, engine, brakes) onto a vehicle tuning and read the resulting feel
+ */
+export declare function applyVehicleParts(base: KinematicVehicleTuning, parts: readonly VehiclePart[]): VehicleSetup;
+/**
+ * Swap a part into its slot: any part already in `next.slot` is removed and `next` takes its place in
+ * the same install position, so the order (and therefore the composed numbers) stays stable across an
+ * upgrade.
+ */
+export declare function withPart(parts: readonly VehiclePart[], next: VehiclePart): VehiclePart[];

package/dist/physics/vehicleParts.js

@@ -0,0 +1,65 @@
+import { DEFAULT_GRIP_CURVE, sampleGripCurve } from "./vehicleBody.js";
+/** Read the handling numbers out of any tuning — base or parts-composed. */
+export function feelOf(tuning) {
+    const curve = tuning.grip ?? DEFAULT_GRIP_CURVE;
+    let peakGrip = 0;
+    let peakSlip = 0;
+    for (const [slip, grip] of curve.points) {
+        if (grip >= peakGrip) {
+            peakGrip = grip;
+            peakSlip = slip;
+        }
+    }
+    return {
+        topSpeed: tuning.topSpeed,
+        engineAccel: tuning.engineAccel,
+        brakeAccel: tuning.brakeAccel,
+        turnRate: tuning.turnRate,
+        handbrakeGrip: tuning.handbrakeGrip,
+        peakGrip,
+        peakSlip,
+        slideGrip: sampleGripCurve(curve, 1),
+    };
+}
+function statOf(tuning, stat) {
+    return tuning[stat] ?? 0;
+}
+/**
+ * Fold parts onto a base tuning: every effect scales then adds onto the running value, in array order,
+ * so a setup is deterministic and a caller can reason about which part moved what. The base tuning is
+ * never mutated, so the same base can seed several builds.
+ *
+ * @capability vehicle-parts compose data-driven tuning parts (tires, engine, brakes) onto a vehicle tuning and read the resulting feel
+ */
+export function applyVehicleParts(base, parts) {
+    const tuning = { ...base };
+    const ids = [];
+    for (const part of parts) {
+        ids.push(part.id);
+        if (part.gripCurve !== undefined)
+            tuning.grip = part.gripCurve;
+        if (part.effects === undefined)
+            continue;
+        for (const stat of Object.keys(part.effects)) {
+            const effect = part.effects[stat];
+            if (effect === undefined)
+                continue;
+            const scaled = statOf(tuning, stat) * (effect.scale ?? 1) + (effect.add ?? 0);
+            tuning[stat] = scaled;
+        }
+    }
+    return { tuning, feel: feelOf(tuning), parts: ids };
+}
+/**
+ * Swap a part into its slot: any part already in `next.slot` is removed and `next` takes its place in
+ * the same install position, so the order (and therefore the composed numbers) stays stable across an
+ * upgrade.
+ */
+export function withPart(parts, next) {
+    const at = parts.findIndex((part) => part.slot === next.slot);
+    if (at < 0)
+        return [...parts, next];
+    const out = parts.slice();
+    out[at] = next;
+    return out;
+}

package/dist/progression/gearScore.d.ts

@@ -0,0 +1,56 @@
+import { type LootComparisonOptions } from "../loot/lootGen.js";
+/** The least a worn item must expose to be scored: its stat block, plus optional level and rarity for the gear-score terms. */
+export interface GearSlotItem {
+    stats: Readonly<Record<string, number>>;
+    /** Item level, added as `levelWeight × level` when the option is set. */
+    level?: number;
+    /** Rarity id, looked up in `rarityScore` when the option names one. */
+    rarity?: string;
+}
+/** Caller policy for a loadout score: stat weights, which stats read better small, and what level, rarity and an empty slot are worth. */
+export interface GearScoreOptions extends Pick<LootComparisonOptions, "weights" | "lowerIsBetter"> {
+    /** Points added per item level (default `0`, so level is ignored). */
+    levelWeight?: number;
+    /** Points added per rarity id (default none). */
+    rarityScore?: Readonly<Record<string, number>>;
+    /** Slot ids a complete loadout fills; named slots that are empty are reported and penalized. */
+    expectedSlots?: readonly string[];
+    /** Points removed per empty slot (default `0`). */
+    emptySlotPenalty?: number;
+}
+/** A scored loadout: the total, each slot's share, each stat's signed contribution, and how complete it is. */
+export interface GearScore {
+    /** `Σ slotScore - emptySlotPenalty × emptySlots`. */
+    score: number;
+    /** Score per filled slot id. */
+    bySlot: Readonly<Record<string, number>>;
+    /** Signed weighted contribution per stat, summed across items. */
+    byStat: Readonly<Record<string, number>>;
+    /** Number of filled slots. */
+    items: number;
+    /** `score / items`, or `0` for an empty loadout. */
+    average: number;
+    /** Filled slots over expected slots, `1` when no slots are expected. */
+    coverage: number;
+    /** Expected slot ids with no item. */
+    emptySlots: readonly string[];
+}
+/**
+ * Score a whole loadout with one documented formula:
+ *
+ * `slotScore = Σ_stat value × weight × (lowerIsBetter ? -1 : 1) + levelWeight × level + rarityScore[rarity]`
+ *
+ * `score = Σ slotScore - emptySlotPenalty × emptySlots`, and `byStat` sums the stat term alone. The
+ * stat term is `scoreLootStats`, the same weight policy `compareLootItems` uses, so an item swap and
+ * a loadout total agree. Ties are exact; nothing here reads a clock or RNG.
+ *
+ * @capability gear-score score a loadout from stat weights, level, rarity and slot coverage
+ */
+export declare function gearScore(set: Readonly<Record<string, GearSlotItem | null | undefined>>, options?: GearScoreOptions): GearScore;
+/** Compare two loadouts; negative means `a` scores lower. */
+export declare function compareGearSets(a: Readonly<Record<string, GearSlotItem | null | undefined>>, b: Readonly<Record<string, GearSlotItem | null | undefined>>, options?: GearScoreOptions): {
+    a: GearScore;
+    b: GearScore;
+    delta: number;
+    better: "a" | "b" | "equal";
+};