@jgengine/core 0.14.0 → 0.15.0

package/dist/ai/difficulty.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Difficulty is decision *quality*, owned in one place: a serializable {@link DifficultyProfile}
+ * describing how fast, how accurately, and how far ahead an agent decides, plus appliers at the
+ * universal decision seams every opponent shares — reacting to new information, choosing among
+ * scored options, executing with error, spending abilities, and planning ahead. The same profile
+ * tunes an RTS grunt, a street enemy, a boss's special-ability discipline, or a turn-based
+ * lookahead player; the game supplies the domain (candidates, scores, moves) and this module
+ * degrades or sharpens the choice. Three canonical tiers ({@link DIFFICULTY_TIERS}) cover
+ * "kinda dumb / smart / super smart"; per-game overrides stay data.
+ *
+ * Everything is deterministic under an injected rng, work is bounded by the profile, and state
+ * (the reaction gate) is one small serializable object. Compose with the existing substrates
+ * rather than replacing them: scale `MobBrainConfig.aggroRadius` by {@link DifficultyProfile.perceptionScale},
+ * run `acquireTarget` candidates through {@link pickScored}, gate `advancePursuit` target swaps
+ * behind {@link advanceReactionGate}, and score ability windows into {@link shouldUseAbility}.
+ */
+/** The three canonical decision-quality tiers. */
+export type DifficultyTier = "easy" | "standard" | "expert";
+/**
+ * Serializable decision-quality data. All fields are plain numbers so a profile can live in a
+ * save, an encounter definition, or a per-entity spawn record.
+ */
+export interface DifficultyProfile {
+    /** Seconds before newly observed information takes effect (see {@link advanceReactionGate}). */
+    reactionSeconds: number;
+    /**
+     * `0..1` chance of a degraded pick in {@link pickScored}, and the amplitude of perceived-value
+     * noise in {@link shouldUseAbility} and {@link planLookahead}. `0` is optimal play.
+     */
+    decisionNoise: number;
+    /** `0..1` amplitude of execution error returned by {@link executionError} (aim, lead, timing). */
+    executionJitter: number;
+    /**
+     * `0..1` opportunity threshold for spending abilities: low values fire specials on weak
+     * moments, high values hold them for strong windows (see {@link shouldUseAbility}).
+     */
+    abilityDiscipline: number;
+    /** Multiplier games apply to sight/aggro/awareness radii (e.g. `aggroRadius * perceptionScale`). */
+    perceptionScale: number;
+    /** Lookahead plies for {@link planLookahead}; `1` is greedy. */
+    planDepth: number;
+    /** Candidate moves considered per ply in {@link planLookahead} (branching bound). */
+    planWidth: number;
+}
+/**
+ * The canonical easy/standard/expert profiles. Frozen — use {@link difficultyProfile} to derive
+ * a tweaked copy instead of mutating.
+ *
+ * @capability difficulty-tiers canonical easy/standard/expert decision-quality profiles for any opponent
+ */
+export declare const DIFFICULTY_TIERS: Readonly<Record<DifficultyTier, DifficultyProfile>>;
+/**
+ * A fresh profile from a canonical tier with optional per-game overrides — e.g. an "easy" boss
+ * that still reacts fast: `difficultyProfile("easy", { reactionSeconds: 0.2 })`.
+ *
+ * @capability difficulty-profile derive a per-game decision-quality profile from a canonical tier
+ */
+export declare function difficultyProfile(tier: DifficultyTier, overrides?: Partial<DifficultyProfile>): DifficultyProfile;
+/**
+ * Serializable reaction-gate state: the value the agent is currently acting on plus the newer
+ * value it has noticed but not yet committed to. `T` should be serializable (ids, positions as
+ * tuples) if the gate lives in saved state.
+ */
+export interface ReactionGateState<T> {
+    /** The value currently in effect — what the agent acts on this step. */
+    committed: T;
+    /** The newer observed value waiting out the reaction delay, or the committed value when idle. */
+    pending: T;
+    /** Seconds the pending value has been observed. */
+    pendingSeconds: number;
+}
+/**
+ * A fresh gate already committed to `initial`.
+ *
+ * @capability difficulty-reaction-gate-state fresh serializable reaction-gate state for one observed value
+ */
+export declare function createReactionGate<T>(initial: T): ReactionGateState<T>;
+/**
+ * Advance one reaction step and return the value to act on. `desired` is what a perfect agent
+ * would act on this frame (current best target, latest known player position); the gate holds the
+ * previously committed value until `desired` has been stable for `profile.reactionSeconds`,
+ * restarting the delay whenever `desired` changes again (compared with `Object.is`). Feed the
+ * returned value — not `desired` — into pursuit/aim/ability logic. Mutates `state` in place;
+ * allocation-free.
+ *
+ * @capability difficulty-reaction-gate delay acting on new information by the profile's reaction time
+ */
+export declare function advanceReactionGate<T>(state: ReactionGateState<T>, dt: number, desired: T, profile: DifficultyProfile): T;
+/** One candidate with a caller-computed score; higher is better. */
+export interface ScoredOption<T> {
+    option: T;
+    score: number;
+}
+/**
+ * Choose from a scored option list at the profile's quality: with probability
+ * `profile.decisionNoise` the pick is uniform over all options (the "wrong target / bad move"
+ * mistake), otherwise it is the best score (first wins ties). Works over any decision the game
+ * can score — acquisition candidates, ability choices, retreat routes, chess moves. Returns
+ * `null` for an empty list. Allocation-free scan; one rng draw plus one more on a noisy pick.
+ *
+ * @capability difficulty-pick noisy argmax over scored options; expert picks best, easy blunders
+ */
+export declare function pickScored<T>(options: readonly ScoredOption<T>[], profile: DifficultyProfile, rng: () => number): T | null;
+/**
+ * Symmetric execution error in `[-scale * executionJitter, +scale * executionJitter]` — add it to
+ * a yaw, a lead time, a throw power, or a release timestamp. `scale` maps the unitless jitter
+ * onto the caller's units (e.g. pass max miss radians).
+ *
+ * @capability difficulty-execution-error symmetric aim/lead/timing error scaled by the profile
+ */
+export declare function executionError(profile: DifficultyProfile, rng: () => number, scale?: number): number;
+/**
+ * Should the agent spend an ability now? `opportunity` is the caller-scored quality of this
+ * moment in `0..1` (targets clumped for the AoE, player mid-animation, burn phase). The perceived
+ * opportunity is fuzzed by `decisionNoise` and compared against `abilityDiscipline`: an easy
+ * profile (low discipline, high noise) wastes cooldowns on weak moments and sometimes sits on a
+ * perfect window; an expert profile fires exactly on strong windows. One rng draw when noisy.
+ *
+ * @capability difficulty-ability-gate spend-or-hold ability decision from a scored opportunity window
+ */
+export declare function shouldUseAbility(opportunity: number, profile: DifficultyProfile, rng: () => number): boolean;
+/**
+ * The game-owned decision domain {@link planLookahead} searches. States and moves are caller
+ * types; the planner never inspects them.
+ */
+export interface LookaheadDomain<S, M> {
+    /**
+     * Candidate moves from `state` with immediate scores (higher better for the player to move).
+     * The planner explores only the best `planWidth` of these per ply.
+     */
+    moves(state: S): readonly ScoredOption<M>[];
+    /** The successor state after the player to move plays `move`. Must not mutate `state`. */
+    apply(state: S, move: M): S;
+    /** Static evaluation of `state` from the perspective of the player to move in it. */
+    evaluate(state: S): number;
+    /**
+     * `true` (default) alternates perspective each ply — adversarial turn games (chess-like,
+     * duels). `false` keeps one perspective — planning the agent's own action sequence
+     * (rotations, build orders, multi-step routes).
+     */
+    adversarial?: boolean;
+}
+/**
+ * Pick the agent's next move by bounded lookahead: a depth-limited negamax (or single-perspective
+ * sequence search when `adversarial: false`) over the caller's {@link LookaheadDomain}, exploring
+ * at most `profile.planWidth` moves per ply to `profile.planDepth` plies, with the final root
+ * choice run through {@link pickScored} so `decisionNoise` still injects tier-appropriate
+ * blunders. Depth `1` is greedy — an easy profile literally cannot see the fork coming; an
+ * expert profile finds multi-ply tactics. Work is bounded by `planWidth ** planDepth` domain
+ * calls; run it at decision cadence (turns, ability windows, order re-evaluation), not per frame.
+ *
+ * @capability difficulty-lookahead depth/width-bounded deterministic planner for turn-based or sequential decisions
+ */
+export declare function planLookahead<S, M>(root: S, domain: LookaheadDomain<S, M>, profile: DifficultyProfile, rng: () => number): M | null;

package/dist/ai/difficulty.js

@@ -0,0 +1,194 @@
+/**
+ * Difficulty is decision *quality*, owned in one place: a serializable {@link DifficultyProfile}
+ * describing how fast, how accurately, and how far ahead an agent decides, plus appliers at the
+ * universal decision seams every opponent shares — reacting to new information, choosing among
+ * scored options, executing with error, spending abilities, and planning ahead. The same profile
+ * tunes an RTS grunt, a street enemy, a boss's special-ability discipline, or a turn-based
+ * lookahead player; the game supplies the domain (candidates, scores, moves) and this module
+ * degrades or sharpens the choice. Three canonical tiers ({@link DIFFICULTY_TIERS}) cover
+ * "kinda dumb / smart / super smart"; per-game overrides stay data.
+ *
+ * Everything is deterministic under an injected rng, work is bounded by the profile, and state
+ * (the reaction gate) is one small serializable object. Compose with the existing substrates
+ * rather than replacing them: scale `MobBrainConfig.aggroRadius` by {@link DifficultyProfile.perceptionScale},
+ * run `acquireTarget` candidates through {@link pickScored}, gate `advancePursuit` target swaps
+ * behind {@link advanceReactionGate}, and score ability windows into {@link shouldUseAbility}.
+ */
+const TIERS = {
+    easy: {
+        reactionSeconds: 0.9,
+        decisionNoise: 0.35,
+        executionJitter: 0.3,
+        abilityDiscipline: 0.2,
+        perceptionScale: 0.7,
+        planDepth: 1,
+        planWidth: 2,
+    },
+    standard: {
+        reactionSeconds: 0.35,
+        decisionNoise: 0.12,
+        executionJitter: 0.12,
+        abilityDiscipline: 0.55,
+        perceptionScale: 1,
+        planDepth: 2,
+        planWidth: 4,
+    },
+    expert: {
+        reactionSeconds: 0.08,
+        decisionNoise: 0,
+        executionJitter: 0.02,
+        abilityDiscipline: 0.85,
+        perceptionScale: 1.3,
+        planDepth: 4,
+        planWidth: 8,
+    },
+};
+for (const tier of Object.values(TIERS))
+    Object.freeze(tier);
+/**
+ * The canonical easy/standard/expert profiles. Frozen — use {@link difficultyProfile} to derive
+ * a tweaked copy instead of mutating.
+ *
+ * @capability difficulty-tiers canonical easy/standard/expert decision-quality profiles for any opponent
+ */
+export const DIFFICULTY_TIERS = Object.freeze(TIERS);
+/**
+ * A fresh profile from a canonical tier with optional per-game overrides — e.g. an "easy" boss
+ * that still reacts fast: `difficultyProfile("easy", { reactionSeconds: 0.2 })`.
+ *
+ * @capability difficulty-profile derive a per-game decision-quality profile from a canonical tier
+ */
+export function difficultyProfile(tier, overrides) {
+    return { ...DIFFICULTY_TIERS[tier], ...overrides };
+}
+/**
+ * A fresh gate already committed to `initial`.
+ *
+ * @capability difficulty-reaction-gate-state fresh serializable reaction-gate state for one observed value
+ */
+export function createReactionGate(initial) {
+    return { committed: initial, pending: initial, pendingSeconds: 0 };
+}
+/**
+ * Advance one reaction step and return the value to act on. `desired` is what a perfect agent
+ * would act on this frame (current best target, latest known player position); the gate holds the
+ * previously committed value until `desired` has been stable for `profile.reactionSeconds`,
+ * restarting the delay whenever `desired` changes again (compared with `Object.is`). Feed the
+ * returned value — not `desired` — into pursuit/aim/ability logic. Mutates `state` in place;
+ * allocation-free.
+ *
+ * @capability difficulty-reaction-gate delay acting on new information by the profile's reaction time
+ */
+export function advanceReactionGate(state, dt, desired, profile) {
+    if (Object.is(desired, state.committed)) {
+        state.pending = desired;
+        state.pendingSeconds = 0;
+        return state.committed;
+    }
+    if (!Object.is(desired, state.pending)) {
+        state.pending = desired;
+        state.pendingSeconds = 0;
+    }
+    state.pendingSeconds += dt;
+    if (state.pendingSeconds >= profile.reactionSeconds) {
+        state.committed = state.pending;
+        state.pendingSeconds = 0;
+    }
+    return state.committed;
+}
+/**
+ * Choose from a scored option list at the profile's quality: with probability
+ * `profile.decisionNoise` the pick is uniform over all options (the "wrong target / bad move"
+ * mistake), otherwise it is the best score (first wins ties). Works over any decision the game
+ * can score — acquisition candidates, ability choices, retreat routes, chess moves. Returns
+ * `null` for an empty list. Allocation-free scan; one rng draw plus one more on a noisy pick.
+ *
+ * @capability difficulty-pick noisy argmax over scored options; expert picks best, easy blunders
+ */
+export function pickScored(options, profile, rng) {
+    if (options.length === 0)
+        return null;
+    if (profile.decisionNoise > 0 && rng() < profile.decisionNoise) {
+        const index = Math.min(options.length - 1, Math.floor(rng() * options.length));
+        return options[index].option;
+    }
+    let best = options[0];
+    for (let i = 1; i < options.length; i++) {
+        const candidate = options[i];
+        if (candidate.score > best.score)
+            best = candidate;
+    }
+    return best.option;
+}
+/**
+ * Symmetric execution error in `[-scale * executionJitter, +scale * executionJitter]` — add it to
+ * a yaw, a lead time, a throw power, or a release timestamp. `scale` maps the unitless jitter
+ * onto the caller's units (e.g. pass max miss radians).
+ *
+ * @capability difficulty-execution-error symmetric aim/lead/timing error scaled by the profile
+ */
+export function executionError(profile, rng, scale = 1) {
+    if (profile.executionJitter <= 0)
+        return 0;
+    return (rng() * 2 - 1) * profile.executionJitter * scale;
+}
+/**
+ * Should the agent spend an ability now? `opportunity` is the caller-scored quality of this
+ * moment in `0..1` (targets clumped for the AoE, player mid-animation, burn phase). The perceived
+ * opportunity is fuzzed by `decisionNoise` and compared against `abilityDiscipline`: an easy
+ * profile (low discipline, high noise) wastes cooldowns on weak moments and sometimes sits on a
+ * perfect window; an expert profile fires exactly on strong windows. One rng draw when noisy.
+ *
+ * @capability difficulty-ability-gate spend-or-hold ability decision from a scored opportunity window
+ */
+export function shouldUseAbility(opportunity, profile, rng) {
+    const perceived = profile.decisionNoise > 0 ? opportunity + (rng() * 2 - 1) * profile.decisionNoise : opportunity;
+    return perceived >= profile.abilityDiscipline;
+}
+function rankedFrontier(domain, state, width) {
+    const moves = domain.moves(state);
+    if (moves.length <= width)
+        return moves;
+    return [...moves].sort((a, b) => b.score - a.score).slice(0, width);
+}
+function lookaheadValue(domain, state, depth, width) {
+    if (depth <= 0)
+        return domain.evaluate(state);
+    const frontier = rankedFrontier(domain, state, width);
+    if (frontier.length === 0)
+        return domain.evaluate(state);
+    const negate = domain.adversarial !== false;
+    let best = Number.NEGATIVE_INFINITY;
+    for (const candidate of frontier) {
+        const child = lookaheadValue(domain, domain.apply(state, candidate.option), depth - 1, width);
+        const value = negate ? -child : child;
+        if (value > best)
+            best = value;
+    }
+    return best;
+}
+/**
+ * Pick the agent's next move by bounded lookahead: a depth-limited negamax (or single-perspective
+ * sequence search when `adversarial: false`) over the caller's {@link LookaheadDomain}, exploring
+ * at most `profile.planWidth` moves per ply to `profile.planDepth` plies, with the final root
+ * choice run through {@link pickScored} so `decisionNoise` still injects tier-appropriate
+ * blunders. Depth `1` is greedy — an easy profile literally cannot see the fork coming; an
+ * expert profile finds multi-ply tactics. Work is bounded by `planWidth ** planDepth` domain
+ * calls; run it at decision cadence (turns, ability windows, order re-evaluation), not per frame.
+ *
+ * @capability difficulty-lookahead depth/width-bounded deterministic planner for turn-based or sequential decisions
+ */
+export function planLookahead(root, domain, profile, rng) {
+    const depth = Math.max(1, Math.floor(profile.planDepth));
+    const width = Math.max(1, Math.floor(profile.planWidth));
+    const negate = domain.adversarial !== false;
+    const frontier = rankedFrontier(domain, root, width);
+    if (frontier.length === 0)
+        return null;
+    const valued = [];
+    for (const candidate of frontier) {
+        const child = lookaheadValue(domain, domain.apply(root, candidate.option), depth - 1, width);
+        valued.push({ option: candidate.option, score: negate ? -child : child });
+    }
+    return pickScored(valued, profile, rng);
+}

package/dist/ai/driver.d.ts

@@ -0,0 +1,107 @@
+import type { AxisInput } from "../input/axisInput.js";
+import { type DifficultyProfile } from "./difficulty.js";
+/**
+ * A difficulty-aware driver brain: pose + goal in, the shared {@link AxisInput}
+ * (`throttle`/`brake`/`steer`/`handbrake`) out, ready for `tickDrivableVehicle` — the chase/traffic
+ * steering loop every game with AI cars hand-rolls as `steer = error * k, throttle = 1`. A
+ * {@link DifficultyProfile} decides how *well* it drives: reaction time trails the target, corners
+ * shed speed instead of orbiting at full throttle, obstacles are noticed late on low tiers, the
+ * wheel wobbles by `executionJitter`, and a stuck car backs out with counter-steer after grinding
+ * for a tier-scaled while. State is one small serializable object; randomness is injected; every
+ * step is allocation-light scalar math. The caller owns the sim, collision, and all spatial
+ * queries — this module never scans the world.
+ */
+/** The driver's own vehicle this step: world position, yaw heading, signed forward speed. */
+export interface DriverPose {
+    x: number;
+    z: number;
+    /** Yaw with the same convention as the kinematic vehicle sim: `atan2(dx, dz)`. */
+    heading: number;
+    /** Signed forward speed in world units/second (negative while reversing). */
+    speed: number;
+}
+/** Where the driver is trying to go this step. */
+export interface DriverGoal {
+    x: number;
+    z: number;
+    /** Brake to a halt inside `arriveRadius` instead of driving through; default `false`. */
+    stopAtGoal?: boolean;
+    /** Cap on desired speed for this goal (a speed limit, a formation speed); default unlimited. */
+    speedLimit?: number;
+}
+/** Vehicle-feel numbers the game supplies; everything has a sensible default except `maxSpeed`. */
+export interface DriverTuning {
+    /** Top desired speed on a straight, world units/second. */
+    maxSpeed: number;
+    /** Steering-output gain per radian of heading error; default `2`. */
+    steerGain?: number;
+    /** Fraction of speed shed at a right-angle heading error (`0` never slows for corners); default `0.75`. */
+    cornerSlowdown?: number;
+    /** Distance at which the goal counts as reached; default `4`. */
+    arriveRadius?: number;
+    /** Meters of clearance the driver tries to keep to an obstacle ahead; default `6`. */
+    brakeMargin?: number;
+    /** Seconds between steering-jitter resamples, so low tiers wobble instead of noise-shake; default `0.35`. */
+    jitterIntervalSeconds?: number;
+    /** Heading-error radians one full unit of `executionJitter` adds; default `0.35`. */
+    jitterScaleRadians?: number;
+    /** Below this |speed| while throttling the car counts as stuck; default `0.8`. */
+    stuckSpeed?: number;
+    /** Seconds of grinding (plus the profile's `reactionSeconds`) before reversing out; default `1.5`. */
+    stuckSeconds?: number;
+    /** How long a reverse-out lasts; default `1.1`. */
+    reverseSeconds?: number;
+}
+/** Serializable per-driver state advanced in place by {@link driveStep}. */
+export interface DriverState {
+    /** The reaction-committed target actually steered toward (the goal as of up to `reactionSeconds` ago). */
+    targetX: number;
+    targetZ: number;
+    /** Seconds until the next target resample. */
+    sampleCooldown: number;
+    /** Current steering-wobble offset (radians of heading error) and time until its next resample. */
+    jitter: number;
+    jitterCooldown: number;
+    /** Seconds spent throttling without moving. */
+    grindSeconds: number;
+    /** Seconds of reverse-out remaining; `> 0` means currently backing up. */
+    reverseRemaining: number;
+}
+/**
+ * Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn
+ * position itself).
+ *
+ * @capability ai-driver-state fresh serializable state for one difficulty-aware AI driver
+ */
+export declare function createDriverState(targetX?: number, targetZ?: number): DriverState;
+/** {@link driveStep}'s result: the axis sample to feed the vehicle sim, plus arrival. */
+export interface DriverStep extends AxisInput {
+    /** The vehicle is inside `arriveRadius` of the *actual* goal this step. */
+    arrived: boolean;
+}
+/**
+ * Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle
+ * sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving
+ * corridor this step (`null`/omitted when clear) — the driver perceives it late by
+ * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
+ * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
+ * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
+ * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
+ * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ *
+ * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
+ */
+export declare function driveStep(state: DriverState, dt: number, pose: DriverPose, goal: DriverGoal, profile: DifficultyProfile, tuning: DriverTuning, rng: () => number, obstacleAhead?: number | null): DriverStep;
+/** A 2D polyline point (`[x, z]`), structurally compatible with authored road path centerlines. */
+export type DrivePathPoint = readonly [number, number];
+/**
+ * The pure-pursuit target for street/route following: the point `lookahead` meters further along
+ * the polyline from wherever the vehicle currently projects onto it. Feed the result to
+ * {@link driveStep} as the goal each tick and the driver follows the road; `loop` wraps a circuit
+ * (traffic block, race lap) instead of pinning at the final point. Returns `null` for a
+ * degenerate path. Give sharper tiers a longer `lookahead` to cut corners cleanly and duller
+ * tiers a short one so they steer segment-to-segment.
+ *
+ * @capability ai-driver-path-target pure-pursuit lookahead target on a road/route polyline for street following
+ */
+export declare function pathTargetAhead(path: readonly DrivePathPoint[], x: number, z: number, lookahead: number, loop?: boolean): DrivePathPoint | null;

package/dist/ai/driver.js

@@ -0,0 +1,175 @@
+import { executionError } from "./difficulty.js";
+/**
+ * Fresh driver state committed to an initial target (usually the spawn-time goal or the spawn
+ * position itself).
+ *
+ * @capability ai-driver-state fresh serializable state for one difficulty-aware AI driver
+ */
+export function createDriverState(targetX = 0, targetZ = 0) {
+    return {
+        targetX,
+        targetZ,
+        sampleCooldown: 0,
+        jitter: 0,
+        jitterCooldown: 0,
+        grindSeconds: 0,
+        reverseRemaining: 0,
+    };
+}
+const wrapAngle = (angle) => {
+    let a = angle;
+    while (a > Math.PI)
+        a -= Math.PI * 2;
+    while (a < -Math.PI)
+        a += Math.PI * 2;
+    return a;
+};
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/**
+ * Advance one driving step, mutating `state`, and return the {@link AxisInput} to feed the vehicle
+ * sim. `obstacleAhead` is the caller-measured distance to the nearest blocker in the driving
+ * corridor this step (`null`/omitted when clear) — the driver perceives it late by
+ * `speed * reactionSeconds`, so easy tiers brake at the last moment and expert tiers with proper
+ * margin. The steering target is a delay-line over the goal — resampled every `reactionSeconds`,
+ * so it trails a moving goal by up to that long, which is what makes an easy chaser visibly cut
+ * toward where the target *was*. When throttle produces no motion for a tier-scaled while the
+ * driver reverses out with counter-steer (brake past standstill — the shared sim's reverse).
+ *
+ * @capability ai-driver difficulty-aware chase/route driving step producing throttle/brake/steer for the vehicle sim
+ */
+export function driveStep(state, dt, pose, goal, profile, tuning, rng, obstacleAhead = null) {
+    const arriveRadius = tuning.arriveRadius ?? 4;
+    // Delay-line target: resample the live goal every reactionSeconds, so the steering target is
+    // the goal as of up to that long ago and a moving goal is chased where it *was*.
+    state.sampleCooldown -= dt;
+    if (state.sampleCooldown <= 0) {
+        state.targetX = goal.x;
+        state.targetZ = goal.z;
+        state.sampleCooldown = profile.reactionSeconds;
+    }
+    const goalDistance = Math.hypot(goal.x - pose.x, goal.z - pose.z);
+    const arrived = goalDistance <= arriveRadius;
+    if (arrived && goal.stopAtGoal === true) {
+        state.grindSeconds = 0;
+        state.reverseRemaining = 0;
+        return { throttle: 0, brake: clamp01(Math.abs(pose.speed)), steer: 0, handbrake: 0, arrived };
+    }
+    const dx = state.targetX - pose.x;
+    const dz = state.targetZ - pose.z;
+    const headingError = wrapAngle(Math.atan2(dx, dz) - pose.heading);
+    // Steering wobble: resample on an interval so it reads as a loose wheel, not per-frame noise.
+    state.jitterCooldown -= dt;
+    if (state.jitterCooldown <= 0) {
+        state.jitter = executionError(profile, rng, tuning.jitterScaleRadians ?? 0.35);
+        state.jitterCooldown = tuning.jitterIntervalSeconds ?? 0.35;
+    }
+    // Reverse-out recovery: back up with counter-steer, nose swinging toward the target.
+    if (state.reverseRemaining > 0) {
+        state.reverseRemaining -= dt;
+        const steer = headingError >= 0 ? -1 : 1;
+        return { throttle: 0, brake: 1, steer, handbrake: 0, arrived };
+    }
+    const steerGain = tuning.steerGain ?? 2;
+    const steer = Math.max(-1, Math.min(1, (headingError + state.jitter) * steerGain));
+    // Corner-aware desired speed: shed speed into large heading errors instead of orbiting.
+    const cornerSlowdown = tuning.cornerSlowdown ?? 0.75;
+    const cornerFactor = 1 - cornerSlowdown * Math.min(1, Math.abs(headingError) / (Math.PI / 2));
+    let desiredSpeed = Math.min(tuning.maxSpeed, goal.speedLimit ?? Number.POSITIVE_INFINITY);
+    desiredSpeed *= cornerFactor;
+    if (goal.stopAtGoal === true) {
+        // Ease in over the last stretch so the stop lands inside the radius instead of overshooting.
+        desiredSpeed = Math.min(desiredSpeed, Math.max(2, goalDistance - arriveRadius));
+    }
+    // Obstacle response on perceived (reaction-late) distance.
+    let hardBrake = false;
+    if (obstacleAhead !== null && pose.speed > 0) {
+        const brakeMargin = tuning.brakeMargin ?? 6;
+        const perceived = obstacleAhead - pose.speed * profile.reactionSeconds;
+        if (perceived <= brakeMargin)
+            hardBrake = true;
+        else if (perceived <= brakeMargin + pose.speed * 0.9)
+            desiredSpeed = Math.min(desiredSpeed, pose.speed * 0.5);
+    }
+    let throttle = 0;
+    let brake = 0;
+    if (hardBrake) {
+        brake = 1;
+    }
+    else if (pose.speed > desiredSpeed + 1) {
+        brake = clamp01((pose.speed - desiredSpeed) / Math.max(4, desiredSpeed));
+    }
+    else if (pose.speed < desiredSpeed) {
+        throttle = clamp01((desiredSpeed - pose.speed) / 3);
+    }
+    // Stuck detection: throttling but not moving (wall, prop, another car).
+    const stuckSpeed = tuning.stuckSpeed ?? 0.8;
+    if (throttle > 0.3 && Math.abs(pose.speed) < stuckSpeed) {
+        state.grindSeconds += dt;
+        if (state.grindSeconds >= (tuning.stuckSeconds ?? 1.5) + profile.reactionSeconds) {
+            state.grindSeconds = 0;
+            state.reverseRemaining = tuning.reverseSeconds ?? 1.1;
+        }
+    }
+    else {
+        state.grindSeconds = 0;
+    }
+    return { throttle, brake, steer, handbrake: 0, arrived };
+}
+/**
+ * The pure-pursuit target for street/route following: the point `lookahead` meters further along
+ * the polyline from wherever the vehicle currently projects onto it. Feed the result to
+ * {@link driveStep} as the goal each tick and the driver follows the road; `loop` wraps a circuit
+ * (traffic block, race lap) instead of pinning at the final point. Returns `null` for a
+ * degenerate path. Give sharper tiers a longer `lookahead` to cut corners cleanly and duller
+ * tiers a short one so they steer segment-to-segment.
+ *
+ * @capability ai-driver-path-target pure-pursuit lookahead target on a road/route polyline for street following
+ */
+export function pathTargetAhead(path, x, z, lookahead, loop = false) {
+    if (path.length < 2)
+        return null;
+    let bestDistSq = Number.POSITIVE_INFINITY;
+    let bestSegment = 0;
+    let bestT = 0;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const lengthSq = abx * abx + abz * abz;
+        const t = lengthSq === 0 ? 0 : Math.max(0, Math.min(1, ((x - a[0]) * abx + (z - a[1]) * abz) / lengthSq));
+        const px = a[0] + abx * t;
+        const pz = a[1] + abz * t;
+        const distSq = (x - px) * (x - px) + (z - pz) * (z - pz);
+        if (distSq < bestDistSq) {
+            bestDistSq = distSq;
+            bestSegment = i;
+            bestT = t;
+        }
+    }
+    let remaining = lookahead;
+    let segment = bestSegment;
+    let t = bestT;
+    for (let hops = 0; hops <= path.length * 2; hops += 1) {
+        const a = path[segment];
+        const b = path[segment + 1];
+        const segLength = Math.hypot(b[0] - a[0], b[1] - a[1]);
+        const left = segLength * (1 - t);
+        if (remaining <= left || segLength === 0) {
+            const nt = segLength === 0 ? t : t + remaining / segLength;
+            return [a[0] + (b[0] - a[0]) * nt, a[1] + (b[1] - a[1]) * nt];
+        }
+        remaining -= left;
+        t = 0;
+        if (segment + 1 < path.length - 1) {
+            segment += 1;
+        }
+        else if (loop) {
+            segment = 0;
+        }
+        else {
+            return [b[0], b[1]];
+        }
+    }
+    return [path[path.length - 1][0], path[path.length - 1][1]];
+}