@jgengine/core 0.6.0 → 0.7.0

package/dist/game/lootFilter.d.ts

@@ -0,0 +1,33 @@
+export interface LootFilterItem {
+    rarity: string;
+    baseType: string;
+    affixTier?: number;
+}
+export interface LootFilterCondition {
+    rarity?: string | readonly string[];
+    baseType?: string | readonly string[];
+    minAffixTier?: number;
+    maxAffixTier?: number;
+}
+export interface LootFilterRule {
+    id: string;
+    when: LootFilterCondition;
+    hide?: boolean;
+    color?: string;
+    beam?: boolean;
+    label?: string;
+}
+export interface LootFilterOverride {
+    hidden?: boolean;
+    color?: string;
+    beam?: boolean;
+    label?: string;
+}
+/**
+ * First matching rule wins (PoE/Last Epoch block semantics) — later rules
+ * never override an earlier match. Returns overrides only; fields the rule
+ * doesn't set are left for the caller's baseline (rarity style) to fill in.
+ */
+export declare function evaluateLootFilter(rules: readonly LootFilterRule[], item: LootFilterItem): LootFilterOverride;
+/** Validating factory — rule ids must be unique so authoring mistakes fail loudly. */
+export declare function lootFilter(rules: readonly LootFilterRule[]): readonly LootFilterRule[];

package/dist/game/lootFilter.js

@@ -0,0 +1,48 @@
+function matchesOneOf(value, expected) {
+    if (expected === undefined)
+        return true;
+    return typeof expected === "string" ? expected === value : expected.includes(value);
+}
+function matchesCondition(when, item) {
+    if (!matchesOneOf(item.rarity, when.rarity))
+        return false;
+    if (!matchesOneOf(item.baseType, when.baseType))
+        return false;
+    if (when.minAffixTier !== undefined && (item.affixTier ?? 0) < when.minAffixTier)
+        return false;
+    if (when.maxAffixTier !== undefined && (item.affixTier ?? 0) > when.maxAffixTier)
+        return false;
+    return true;
+}
+/**
+ * First matching rule wins (PoE/Last Epoch block semantics) — later rules
+ * never override an earlier match. Returns overrides only; fields the rule
+ * doesn't set are left for the caller's baseline (rarity style) to fill in.
+ */
+export function evaluateLootFilter(rules, item) {
+    for (const rule of rules) {
+        if (!matchesCondition(rule.when, item))
+            continue;
+        const override = {};
+        if (rule.hide !== undefined)
+            override.hidden = rule.hide;
+        if (rule.color !== undefined)
+            override.color = rule.color;
+        if (rule.beam !== undefined)
+            override.beam = rule.beam;
+        if (rule.label !== undefined)
+            override.label = rule.label;
+        return override;
+    }
+    return {};
+}
+/** Validating factory — rule ids must be unique so authoring mistakes fail loudly. */
+export function lootFilter(rules) {
+    const seen = new Set();
+    for (const rule of rules) {
+        if (seen.has(rule.id))
+            throw new Error(`loot filter rule id "${rule.id}" is duplicated`);
+        seen.add(rule.id);
+    }
+    return rules;
+}

package/dist/game/ping.d.ts

@@ -0,0 +1,67 @@
+import type { PointerHit } from "../input/pointer.js";
+import type { MapMarker, MarkerPosition, MarkerSet } from "../world/markers.js";
+export type PingCategory = string;
+export interface PingCategoryDef {
+    id: PingCategory;
+    markerKind: string;
+    label: string;
+    callout: string;
+}
+/** Content-agnostic default ping wheel: enemy / loot / location / danger. */
+export declare const DEFAULT_PING_CATEGORIES: Record<PingCategory, PingCategoryDef>;
+export declare const PING_FEED_ACTION = "party.ping";
+export interface PingClassifyDeps {
+    roleOf?(entityId: string): string | null | undefined;
+    categoryOf?(objectId: string): PingCategory | null | undefined;
+}
+export interface PingClassifyOptions {
+    hostileRoles?: readonly string[];
+    enemyCategory?: PingCategory;
+    lootCategory?: PingCategory;
+    locationCategory?: PingCategory;
+    dangerCategory?: PingCategory;
+}
+/**
+ * Classify what a pointer/aim ray hit into a ping category. Entity hits resolve
+ * by catalog role (hostile → enemy, else location); object hits by an
+ * optional catalog category tag; open ground is a location ping.
+ */
+export declare function classifyPing(hit: PointerHit, deps?: PingClassifyDeps, options?: PingClassifyOptions): PingCategory;
+export interface PingPayload {
+    id: string;
+    from: string;
+    category: PingCategory;
+    position: MarkerPosition;
+    entityId: string | null;
+    objectId: string | null;
+    at: number;
+    callout: string;
+    /** Party members the broadcast targets; empty when solo or party unconfigured. */
+    recipients: readonly string[];
+}
+export interface PingFeedSink {
+    push(action: string, entry: unknown): void;
+}
+export interface PingParty {
+    membersOf(userId: string): string[];
+}
+export interface PingSystemDeps {
+    markers: MarkerSet;
+    feed: PingFeedSink;
+    party?: PingParty;
+    categories?: Record<PingCategory, PingCategoryDef>;
+    now?(): number;
+    /** Marker lifetime in ms; omit for permanent markers. */
+    ttlMs?: number;
+    feedAction?: string;
+    classify?: PingClassifyDeps;
+    classifyOptions?: PingClassifyOptions;
+}
+export interface PingSystem {
+    classify(hit: PointerHit): PingCategory;
+    buildPayload(from: string, hit: PointerHit, category?: PingCategory): PingPayload;
+    broadcast(payload: PingPayload): MapMarker;
+    /** Classify → build → broadcast in one call; the ping verb. */
+    ping(from: string, hit: PointerHit, category?: PingCategory): PingPayload;
+}
+export declare function createPingSystem(deps: PingSystemDeps): PingSystem;

package/dist/game/ping.js

@@ -0,0 +1,86 @@
+/** Content-agnostic default ping wheel: enemy / loot / location / danger. */
+export const DEFAULT_PING_CATEGORIES = {
+    enemy: { id: "enemy", markerKind: "enemy", label: "Enemy", callout: "Enemy spotted" },
+    loot: { id: "loot", markerKind: "loot", label: "Loot", callout: "Loot here" },
+    location: { id: "location", markerKind: "location", label: "Location", callout: "Going here" },
+    danger: { id: "danger", markerKind: "danger", label: "Danger", callout: "Watch out" },
+};
+export const PING_FEED_ACTION = "party.ping";
+const DEFAULT_HOSTILE_ROLES = ["enemy", "hostile"];
+/**
+ * Classify what a pointer/aim ray hit into a ping category. Entity hits resolve
+ * by catalog role (hostile → enemy, else location); object hits by an
+ * optional catalog category tag; open ground is a location ping.
+ */
+export function classifyPing(hit, deps = {}, options = {}) {
+    const hostileRoles = options.hostileRoles ?? DEFAULT_HOSTILE_ROLES;
+    const enemyCategory = options.enemyCategory ?? "enemy";
+    const locationCategory = options.locationCategory ?? "location";
+    if (hit.entity !== null) {
+        const role = deps.roleOf?.(hit.entity);
+        if (role !== null && role !== undefined && hostileRoles.includes(role))
+            return enemyCategory;
+        return locationCategory;
+    }
+    if (hit.object !== null) {
+        const category = deps.categoryOf?.(hit.object);
+        if (category !== null && category !== undefined)
+            return category;
+        return locationCategory;
+    }
+    return locationCategory;
+}
+function categoryDef(categories, category) {
+    return categories[category] ?? { id: category, markerKind: category, label: category, callout: category };
+}
+export function createPingSystem(deps) {
+    const now = deps.now ?? Date.now;
+    const categories = deps.categories ?? DEFAULT_PING_CATEGORIES;
+    const feedAction = deps.feedAction ?? PING_FEED_ACTION;
+    let counter = 0;
+    const system = {
+        classify(hit) {
+            return classifyPing(hit, deps.classify, deps.classifyOptions);
+        },
+        buildPayload(from, hit, category) {
+            const resolved = category ?? system.classify(hit);
+            const at = now();
+            counter += 1;
+            const def = categoryDef(categories, resolved);
+            const recipients = deps.party?.membersOf(from).filter((member) => member !== from) ?? [];
+            return {
+                id: `ping-${from}-${counter}`,
+                from,
+                category: resolved,
+                position: hit.point,
+                entityId: hit.entity,
+                objectId: hit.object,
+                at,
+                callout: def.callout,
+                recipients,
+            };
+        },
+        broadcast(payload) {
+            const def = categoryDef(categories, payload.category);
+            const markerInput = {
+                id: payload.id,
+                kind: def.markerKind,
+                position: payload.position,
+                label: def.label,
+                owner: payload.from,
+                createdAt: payload.at,
+                ...(deps.ttlMs !== undefined ? { expiresAt: payload.at + deps.ttlMs } : {}),
+                meta: { ping: true, category: payload.category, callout: payload.callout },
+            };
+            deps.markers.add(markerInput);
+            deps.feed.push(feedAction, payload);
+            return deps.markers.get(payload.id);
+        },
+        ping(from, hit, category) {
+            const payload = system.buildPayload(from, hit, category);
+            system.broadcast(payload);
+            return payload;
+        },
+    };
+    return system;
+}

package/dist/game/playableGame.d.ts

@@ -1,7 +1,31 @@
+import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { PositionedPrompt } from "../interaction/proximityPrompt.js";
 import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
 import type { ModelDims } from "../scene/assetCatalog.js";
 import type { GameDefinition, GameLoop } from "./defineGame.js";
+import type { LootFilterRule } from "./lootFilter.js";
+import type { RarityStyle } from "./worldItem.js";
+export interface PointerConfig {
+    /**
+     * Left-click on open ground runs this command with `{ point, entity, object }`
+     * (click-to-move / ground-target). Suppresses the default left-click hotbar fire.
+     */
+    moveCommand?: string;
+    /** Enable left-drag marquee + single-click box-select of entities (RTS unit command). */
+    select?: boolean;
+    /** Only entities matching this pass are selectable/orderable; default all non-local entities. */
+    selectFilter?: (entityId: string) => boolean;
+    /** Right-click on ground runs this command with `{ selection, point }` — order the selection. */
+    orderCommand?: string;
+    /** Right-click on an entity/object opens the target's catalog verb menu (#31). */
+    contextMenu?: boolean;
+    /** Route the primary ability's aim to the cursor world point instead of camera yaw/pitch (#22). */
+    aim?: boolean;
+    /** Left-click a `worldItem` within pickup radius grants it to the local player and despawns it (#32). */
+    grabWorldItems?: boolean;
+    /** Press the bound `ping` action → `worldHit()` → run this command with `{ point, entity, object, normal }` (contextual ping, #94). */
+    pingCommand?: string;
+}
 export interface CameraFollowState {
     entityId: string;
     target: {
@@ -28,11 +52,241 @@ export interface FirstPersonCameraConfig {
     /** Render a simple first-person weapon in view. Default true. */
     viewmodel?: boolean;
 }
+/**
+ * Which camera rig the shell mounts. Every rig accepts `followEntityId: null`
+ * (avatar-less games — city-builders, card games, auto-battlers — still get a
+ * camera). Rigs are tuned through their config block below, never by writing
+ * camera positions from `onTick`.
+ * - `orbit` — third-person chase (the historical default; `perspective: "third"`).
+ * - `first` — pointer-lock mouse-look (`perspective: "first"`).
+ * - `topDown` — fixed height/pitch/yaw with decoupled follow (ARPG iso, top-down).
+ * - `rts` — free-pan / edge-scroll / rotate / zoom, optional follow.
+ * - `shoulder` — over-the-shoulder with ADS transition + shoulder swap.
+ * - `lockOn` — yaw bound to the player→target vector; move axis becomes strafe.
+ * - `chase` — speed-reactive vehicle chase (speed→FOV, spring arm, shake) + cockpit/hood/rear views.
+ * - `observer` — detached spectator/photo cam bound to any entity or fixed point; never reads player input.
+ */
+export type CameraRigKind = "orbit" | "first" | "topDown" | "rts" | "shoulder" | "lockOn" | "chase" | "observer";
+/** Fixed top-down / isometric rig (#23) — height/pitch/yaw + decoupled follow. */
+export interface TopDownCameraConfig {
+    /** Camera height above the follow point. Default 18. */
+    height?: number;
+    /** Look-down angle in radians (0 = straight down, PI/2 = level). Default ~1.02 (~58°, ARPG iso). */
+    pitch?: number;
+    /** Fixed azimuth in radians; ~PI/4 reads as isometric, 0 as straight top-down. Default PI/4. */
+    yaw?: number;
+    /** Horizontal look offset applied to the follow point. */
+    targetOffset?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** Exponential follow smoothing (higher = snappier, decoupled from any orbit drag). Default 8. */
+    followSmoothing?: number;
+    /** Scroll zoom bounds as a height multiplier. */
+    zoom?: {
+        min?: number;
+        max?: number;
+        speed?: number;
+    };
+}
+/** Free-pan / edge-scroll RTS rig (#24) — pan/rotate/zoom independent of any avatar. */
+export interface RtsCameraConfig extends TopDownCameraConfig {
+    /** WASD / arrow pan speed in world units per second. Default 24. */
+    panSpeed?: number;
+    /** Edge-scroll when the pointer nears a screen edge; number sets the margin fraction. Default true. */
+    edgeScroll?: boolean | {
+        margin?: number;
+        speed?: number;
+    };
+    /** Yaw rotate speed (radians/sec) for rotate keys / middle-drag. Default 1.4. */
+    rotateSpeed?: number;
+    /** World-space clamp for the pan center. */
+    bounds?: {
+        minX?: number;
+        maxX?: number;
+        minZ?: number;
+        maxZ?: number;
+    };
+    /** Start centered on this world point when there is no follow target. */
+    start?: {
+        x?: number;
+        z?: number;
+    };
+}
+/** Over-the-shoulder combat rig (#25) — offset, ADS, shoulder swap, decoupled reticle. */
+export interface ShoulderCameraConfig {
+    /** Lateral shoulder offset (world units, sign flips on swap). Default 0.6. */
+    shoulderOffset?: number;
+    /** Vertical offset above the follow point. Default 1.6. */
+    heightOffset?: number;
+    /** Boom distance behind the shoulder. Default 3.2. */
+    distance?: number;
+    /** Starting shoulder side. Default "right". */
+    side?: "left" | "right";
+    /** Aim-down-sights framing, blended in while `aim` is held. */
+    ads?: {
+        distance?: number;
+        shoulderOffset?: number;
+        fov?: number;
+        heightOffset?: number;
+    };
+    /** ADS blend speed (higher = snappier). Default 10. */
+    adsTransitionSpeed?: number;
+    /** Screen-space reticle offset (fraction of viewport), decoupled from camera center. */
+    reticleOffset?: {
+        x?: number;
+        y?: number;
+    };
+    /** Mouse-look sensitivity (radians per pixel). Default 0.0025. */
+    sensitivity?: number;
+    /** Base field of view. Default 55. */
+    fov?: number;
+}
+/** Lock-on / strafe rig (#26) — yaw bound to player→target, move axis becomes strafe. */
+export interface LockOnCameraConfig {
+    /** Target instance id; when omitted the rig reads the follower's current `getTarget`. */
+    targetEntityId?: string;
+    /** Boom distance behind the player, away from the target. Default 5. */
+    distance?: number;
+    /** Camera height above the follow point. Default 2.4. */
+    height?: number;
+    /** Height of the framed look point above the midpoint. Default 1.2. */
+    lookHeight?: number;
+    /** 0 frames the player, 1 frames the target, 0.5 the midpoint. Default 0.5. */
+    framingBias?: number;
+    /** Exponential yaw smoothing toward the player→target vector. Default 9. */
+    yawSmoothing?: number;
+}
+/** Fixed interior view for the chase rig (#27). */
+export type ChaseView = "chase" | "cockpit" | "hood" | "rear";
+/** Speed-reactive vehicle chase rig (#27) — speed→FOV, spring arm, procedural shake, interior views. */
+export interface ChaseCameraConfig {
+    /** Boom distance behind the vehicle. Default 6. */
+    distance?: number;
+    /** Camera height above the follow point. Default 2.6. */
+    height?: number;
+    /** Height of the look point above the follow point. Default 1.2. */
+    lookHeight?: number;
+    /** Spring-arm damping (higher = stiffer, less lag). Default 6. */
+    springDamping?: number;
+    /** Speed→FOV curve: FOV lerps from `base` to `max` as speed climbs to `speedForMax`. */
+    fov?: {
+        base?: number;
+        max?: number;
+        speedForMax?: number;
+    };
+    /** Procedural shake amplitude per unit of speed (adds to the trauma channel). Default 0.0. */
+    shakePerSpeed?: number;
+    /** Which view to mount. Default "chase". */
+    view?: ChaseView;
+    /** Local offset for cockpit/hood/rear seats (relative to the vehicle, +z forward). */
+    seatOffsets?: {
+        cockpit?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        hood?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+        rear?: {
+            x?: number;
+            y?: number;
+            z?: number;
+        };
+    };
+}
+/** Detached spectator/photo cam (#120) — binds to any entity or fixed point, never reads player input. */
+export interface ObserverCameraConfig {
+    /** What the observer looks at. Omit to stay on a fixed point at the origin (or `point`, if given). */
+    bind?: {
+        kind: "entity";
+        entityId: string;
+    } | {
+        kind: "point";
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+    };
+    /** Orbit distance from the bound subject. Default 8. */
+    distance?: number;
+    /** Camera height above the bound subject. Default 3. */
+    height?: number;
+    /** Height of the look point above the subject. Default 1.2. */
+    lookHeight?: number;
+    /** Radians/second of automatic orbit around the subject (CCTV-style sweep); 0 holds a fixed angle. Default 0.2. */
+    orbitSpeed?: number;
+    /** Starting orbit angle in radians. Default 0. */
+    startAngle?: number;
+    fov?: number;
+}
+/** One stop on a scripted camera path (#29). */
+export interface CameraKeyframe {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    lookAt: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    fov?: number;
+    /** Seconds to travel from the previous keyframe to this one. Default 1. */
+    duration?: number;
+    /** Interpolation into this keyframe. Default "smooth" (smoothstep ease). */
+    ease?: "linear" | "smooth";
+}
+/** Scripted keyframe / path player (#29). When set it overrides the active rig. */
+export interface CinematicCameraConfig {
+    keyframes: readonly CameraKeyframe[];
+    /** Restart from the first keyframe after the last. Default false. */
+    loop?: boolean;
+}
+/** Camera-shake / trauma defaults (#28). Any rig reads the trauma channel; game systems feed it via `cameraShake()`. */
+export interface CameraShakeConfig {
+    /** Positional shake amplitude at full trauma (world units). Default 0.5. */
+    maxOffset?: number;
+    /** Rotational shake amplitude at full trauma (radians). Default 0.06. */
+    maxRoll?: number;
+    /** Trauma decay per second (fraction). Default 1.6. */
+    decayPerSecond?: number;
+    /** Trauma→shake exponent; 2 = quadratic falloff so small hits are subtle. Default 2. */
+    exponent?: number;
+    /** Noise frequency (Hz) of the shake oscillation. Default 24. */
+    frequency?: number;
+}
 export interface GameCameraConfig {
-    /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. */
+    /** Selects the rig. Overrides `perspective`; leave unset to fall back to `perspective`. */
+    rig?: CameraRigKind;
+    /** "third" mounts the orbit camera (default); "first" mounts pointer-lock mouse-look. Shorthand for `rig: "orbit" | "first"`. */
     perspective?: "third" | "first";
-    /** First-person tuning; only read when perspective is "first". */
+    /** First-person tuning; only read when the rig resolves to "first". */
     firstPerson?: FirstPersonCameraConfig;
+    /** Top-down / isometric tuning (#23); read when `rig: "topDown"`. */
+    topDown?: TopDownCameraConfig;
+    /** Free-pan / edge-scroll RTS tuning (#24); read when `rig: "rts"`. */
+    rts?: RtsCameraConfig;
+    /** Over-the-shoulder tuning (#25); read when `rig: "shoulder"`. */
+    shoulder?: ShoulderCameraConfig;
+    /** Lock-on / strafe tuning (#26); read when `rig: "lockOn"`. */
+    lockOn?: LockOnCameraConfig;
+    /** Vehicle chase tuning (#27); read when `rig: "chase"`. */
+    chase?: ChaseCameraConfig;
+    /** Detached spectator/photo cam tuning (#120); read when `rig: "observer"`. */
+    observer?: ObserverCameraConfig;
+    /** Camera-shake / trauma channel defaults (#28); read by every rig. */
+    shake?: CameraShakeConfig;
+    /** Scripted keyframe path (#29); when set, plays over the active rig. */
+    cinematic?: CinematicCameraConfig;
+    /** Seconds to cross-fade the camera when the rig changes (#29). 0 hard-cuts. Default 0.6. */
+    transitionSeconds?: number;
     minDistance?: number;
     maxDistance?: number;
     targetHeight?: number;
@@ -48,8 +302,8 @@ export interface GameCameraConfig {
     followLock?: boolean;
     /** When false, orbit target stays fixed (cinematic / debug). Default true. */
     followEnabled?: boolean;
-    /** Instance id to follow; defaults to local player in the dev shell. */
-    followEntityId?: string;
+    /** Instance id to follow, or null for an avatar-less free camera; defaults to local player in the dev shell. */
+    followEntityId?: string | null;
     /** Fired each frame after cameraFollow lock is applied. */
     onCameraFollow?: (state: CameraFollowState) => void;
     rotateSpeed?: number;
@@ -68,6 +322,16 @@ export interface EntitySpriteConfig {
     height: number;
     y: number;
 }
+export interface WorldItemRenderConfig {
+    /** Baseline rarity→color/beam/label render binding (#32); the game's rarity palette. */
+    rarityStyle?: Record<string, RarityStyle>;
+    /** Loot-filter rules layered over the rarity baseline (#33) — data the game supplies, first match wins. */
+    filter?: readonly LootFilterRule[];
+    /** World units within which a ground item is grabbable/highlighted. Default 2. */
+    pickupRadius?: number;
+    /** Beam height above the item's ground position. Default 2.5. */
+    beamHeight?: number;
+}
 export interface ModelConfig {
     url: string;
     scale?: number;
@@ -100,8 +364,21 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     prompts?: (ctx: GameContext) => readonly PositionedPrompt[];
     /** Camera tuning (perspective, orbit, first-person) for the dev game player shell. */
     camera?: GameCameraConfig;
+    /** Pointer-driven input: click-to-move, box-select, right-click verbs, cursor aim (#22/#30/#31). */
+    pointer?: PointerConfig;
     /** Opt in to world-space health bars floating over non-local entities that carry the stat. */
     worldHealthBars?: boolean | {
         statId?: string;
     };
+    /** Sound catalog + mix buses (music/sfx/ambient/…) the shell's Web Audio glue plays from. Catalog-first — no per-game audio wiring. */
+    audio?: {
+        sounds: Record<string, SoundDef>;
+        buses?: Record<string, AudioBusDef>;
+    };
+    /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
+    entitySounds?: Record<string, string>;
+    /** Same as `entitySounds` but keyed by placed-object catalog id (torches, machinery). */
+    objectSounds?: Record<string, string>;
+    /** Rarity render binding + loot filter for dropped-item ground presentation (#32/#33). */
+    worldItem?: WorldItemRenderConfig;
 }

package/dist/game/race.d.ts

@@ -0,0 +1,95 @@
+export interface Checkpoint {
+    id: string;
+    center: readonly [number, number, number];
+    half: readonly [number, number, number];
+}
+export interface RaceTrackConfig {
+    checkpoints: readonly Checkpoint[];
+    laps?: number;
+}
+export interface RaceTrack {
+    readonly checkpoints: readonly Checkpoint[];
+    readonly laps: number;
+}
+/**
+ * A race track is an ordered ring of checkpoint trigger volumes plus a lap count. The final checkpoint
+ * is the lap/finish line: a racer completes a lap by passing all checkpoints in order and hitting the
+ * last one.
+ */
+export declare function raceTrack(config: RaceTrackConfig): RaceTrack;
+export interface RacerProgress {
+    racerId: string;
+    lap: number;
+    nextCheckpoint: number;
+    lastCheckpoint: number;
+    progress: number;
+    position: number;
+    finished: boolean;
+    finishTime: number | null;
+    eliminated: boolean;
+    splits: readonly number[];
+}
+export type RaceEvent = {
+    type: "checkpoint.hit";
+    racerId: string;
+    checkpoint: number;
+    lap: number;
+    time: number;
+} | {
+    type: "lap.completed";
+    racerId: string;
+    lap: number;
+    time: number;
+} | {
+    type: "position.changed";
+    racerId: string;
+    position: number;
+    previous: number;
+} | {
+    type: "race.finished";
+    ranking: readonly string[];
+    time: number;
+};
+export type RaceWinCondition = (standings: readonly RacerProgress[], track: RaceTrack) => readonly string[] | null;
+/** Race ends when `count` racers have crossed the finish; ranking is the current standings order. */
+export declare function firstPastPost(count?: number): RaceWinCondition;
+/** Round-cut (Fall Guys): the first `k` finishers qualify; race resolves the moment `k` cross. */
+export declare function topK(k: number): RaceWinCondition;
+/** Every non-eliminated racer must finish. */
+export declare function everyoneFinishes(): RaceWinCondition;
+/** Destruction-derby last-man-standing: ends when at most one racer is left un-eliminated. */
+export declare function lastStanding(): RaceWinCondition;
+export interface RaceStateConfig {
+    track: RaceTrack;
+    win?: RaceWinCondition;
+}
+/**
+ * Race state machine (issue #87). Drive it each tick with `update(now, positions)` — `now` is game time
+ * (`ctx.time`), `positions` maps each racer to a world point tested against the ordered checkpoint
+ * volumes. It emits `checkpoint.hit` / `lap.completed` / `position.changed` / `race.finished`, keeps
+ * cumulative split times for PB deltas, resolves a pluggable win condition (first-past-post, round-cut,
+ * derby last-standing), and `resetToCheckpoint` hands back a respawn pose at the racer's last checkpoint.
+ */
+export declare class RaceState {
+    private readonly track;
+    private readonly win;
+    private readonly racers;
+    private readonly order;
+    private raceFinished;
+    private finalRanking;
+    constructor(config: RaceStateConfig);
+    addRacer(racerId: string, startTime?: number): void;
+    eliminate(racerId: string): void;
+    get finished(): boolean;
+    get ranking(): readonly string[];
+    progressOf(racerId: string): RacerProgress | null;
+    private snapshot;
+    standings(): readonly RacerProgress[];
+    resetToCheckpoint(racerId: string): {
+        position: [number, number, number];
+        heading: number;
+    } | null;
+    private compare;
+    update(now: number, positions: Record<string, readonly [number, number, number]> | Map<string, readonly [number, number, number]>): readonly RaceEvent[];
+}
+export declare function createRaceState(config: RaceStateConfig): RaceState;