@jgengine/core 0.8.0 → 0.10.0

package/dist/game/race.js

@@ -1,10 +1,24 @@
 /**
  * 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.
+ * last one. `forks` splice alternate route segments between mainline checkpoints.
  */
 export function raceTrack(config) {
-    return { checkpoints: config.checkpoints, laps: Math.max(1, Math.floor(config.laps ?? 1)) };
+    const checkpoints = config.checkpoints;
+    const forks = config.forks ?? [];
+    for (const fork of forks) {
+        if (fork.afterIndex < 0 || fork.afterIndex >= checkpoints.length - 1) {
+            throw new Error(`race fork "${fork.id}" afterIndex ${fork.afterIndex} must sit before the finish line`);
+        }
+        if (fork.routes.length < 2)
+            throw new Error(`race fork "${fork.id}" needs at least two routes`);
+        for (const route of fork.routes) {
+            if (route.checkpoints.length === 0) {
+                throw new Error(`race fork "${fork.id}" route "${route.id}" needs at least one checkpoint`);
+            }
+        }
+    }
+    return { checkpoints, laps: Math.max(1, Math.floor(config.laps ?? 1)), forks };
 }
 function rankIds(standings) {
     return standings.map((s) => s.racerId);
@@ -78,6 +92,10 @@ export class RaceState {
             eliminated: false,
             startTime,
             splits: [],
+            fork: null,
+            routesTaken: {},
+            forksDone: {},
+            lastHit: null,
         });
         this.order.push(racerId);
     }
@@ -116,6 +134,7 @@ export class RaceState {
         return r === null || r === undefined ? null : this.snapshot(r);
     }
     snapshot(r) {
+        const activeFork = r.fork === null ? null : this.track.forks[r.fork.forkIndex];
         return {
             racerId: r.racerId,
             lap: r.lap,
@@ -127,6 +146,10 @@ export class RaceState {
             finishTime: r.finishTime,
             eliminated: r.eliminated,
             splits: [...r.splits],
+            routesTaken: { ...r.routesTaken },
+            activeRoute: activeFork === null || r.fork === null
+                ? null
+                : { forkId: activeFork.id, routeId: activeFork.routes[r.fork.routeIndex].id },
         };
     }
     standings() {
@@ -136,16 +159,24 @@ export class RaceState {
             .sort((a, b) => this.compare(a, b, null))
             .map((r) => this.snapshot(r));
     }
+    expectedCheckpoint(r) {
+        if (r.fork !== null) {
+            const fork = this.track.forks[r.fork.forkIndex];
+            const route = fork.routes[r.fork.routeIndex];
+            return route.checkpoints[r.fork.nextRouteCheckpoint] ?? this.track.checkpoints[r.nextCheckpoint] ?? null;
+        }
+        return this.track.checkpoints[r.nextCheckpoint] ?? null;
+    }
     resetToCheckpoint(racerId) {
         const r = this.racers.get(racerId);
         if (r === undefined)
             return null;
-        const cps = this.track.checkpoints;
-        const idx = r.lastCheckpoint >= 0 ? r.lastCheckpoint : 0;
-        const cp = cps[idx];
+        const cp = r.lastHit ?? this.track.checkpoints[0];
         if (cp === undefined)
             return null;
-        const next = cps[(idx + 1) % cps.length];
+        let next = this.expectedCheckpoint(r) ?? cp;
+        if (next === cp)
+            next = this.track.checkpoints[1 % this.track.checkpoints.length] ?? cp;
         const heading = Math.atan2(next.center[0] - cp.center[0], next.center[2] - cp.center[2]);
         return { position: [cp.center[0], cp.center[1], cp.center[2]], heading };
     }
@@ -161,10 +192,11 @@ export class RaceState {
         if (positions !== null) {
             const pa = positions.get(a.racerId);
             const pb = positions.get(b.racerId);
-            const cps = this.track.checkpoints;
-            if (pa !== undefined && pb !== undefined && cps.length > 0) {
-                const da = distanceToNext(pa, cps[a.nextCheckpoint]);
-                const db = distanceToNext(pb, cps[b.nextCheckpoint]);
+            const ca = this.expectedCheckpoint(a);
+            const cb = this.expectedCheckpoint(b);
+            if (pa !== undefined && pb !== undefined && ca !== null && cb !== null) {
+                const da = distanceToNext(pa, ca);
+                const db = distanceToNext(pb, cb);
                 if (da !== db)
                     return da - db;
             }
@@ -177,6 +209,8 @@ export class RaceState {
         const cps = this.track.checkpoints;
         const count = cps.length;
         if (count > 0) {
+            const forks = this.track.forks;
+            const maxSteps = count + forks.reduce((sum, fork) => sum + Math.max(...fork.routes.map((route) => route.checkpoints.length)), 0) + 2;
             for (const id of this.order) {
                 const r = this.racers.get(id);
                 if (r.finished || r.eliminated)
@@ -185,10 +219,61 @@ export class RaceState {
                 if (pos === undefined)
                     continue;
                 let guard = 0;
-                while (guard < count && insideAabb(pos, cps[r.nextCheckpoint])) {
+                while (guard < maxSteps) {
                     guard += 1;
+                    if (r.fork !== null) {
+                        const fork = forks[r.fork.forkIndex];
+                        const route = fork.routes[r.fork.routeIndex];
+                        const cp = route.checkpoints[r.fork.nextRouteCheckpoint];
+                        if (!insideAabb(pos, cp))
+                            break;
+                        r.lastHit = cp;
+                        r.progress += 1 / route.checkpoints.length;
+                        r.splits.push(now - r.startTime);
+                        events.push({
+                            type: "checkpoint.hit",
+                            racerId: id,
+                            checkpoint: fork.afterIndex,
+                            lap: r.lap,
+                            time: now,
+                            fork: { forkId: fork.id, routeId: route.id, index: r.fork.nextRouteCheckpoint },
+                        });
+                        r.fork.nextRouteCheckpoint += 1;
+                        if (r.fork.nextRouteCheckpoint >= route.checkpoints.length) {
+                            r.forksDone[fork.id] = true;
+                            r.fork = null;
+                        }
+                        continue;
+                    }
+                    let tookRoute = false;
+                    for (let forkIndex = 0; forkIndex < forks.length; forkIndex += 1) {
+                        const fork = forks[forkIndex];
+                        if (fork.afterIndex !== r.lastCheckpoint || r.nextCheckpoint !== fork.afterIndex + 1)
+                            continue;
+                        if (r.forksDone[fork.id] === true)
+                            continue;
+                        for (let routeIndex = 0; routeIndex < fork.routes.length; routeIndex += 1) {
+                            const route = fork.routes[routeIndex];
+                            if (!insideAabb(pos, route.checkpoints[0]))
+                                continue;
+                            r.fork = { forkIndex, routeIndex, nextRouteCheckpoint: 0 };
+                            r.routesTaken[fork.id] = route.id;
+                            events.push({ type: "fork.taken", racerId: id, forkId: fork.id, routeId: route.id, time: now });
+                            tookRoute = true;
+                            break;
+                        }
+                        if (tookRoute)
+                            break;
+                    }
+                    if (tookRoute)
+                        continue;
+                    const cp = cps[r.nextCheckpoint];
+                    if (!insideAabb(pos, cp))
+                        break;
                     const hit = r.nextCheckpoint;
                     r.lastCheckpoint = hit;
+                    r.lastHit = cp;
+                    r.forksDone = {};
                     r.progress += 1;
                     r.splits.push(now - r.startTime);
                     events.push({ type: "checkpoint.hit", racerId: id, checkpoint: hit, lap: r.lap, time: now });

package/dist/game/recordBook.d.ts

@@ -0,0 +1,27 @@
+import type { KeyValueStorage } from "./keyValueStore.js";
+/** The structural storage backend a record book persists through — an alias of the shared {@link KeyValueStorage} seam (browser `localStorage`, a test stub, or `null`). */
+export type RecordStorage = KeyValueStorage;
+export type RecordDirection = "lower" | "higher";
+export interface RecordBookConfig<K extends string> {
+    readonly key: string;
+    readonly fields: Readonly<Record<K, RecordDirection>>;
+    readonly storage?: RecordStorage | null;
+}
+export interface RecordSubmission<K extends string> {
+    readonly improved: readonly K[];
+    readonly best: Readonly<Partial<Record<K, number>>>;
+}
+export interface RecordBook<K extends string> {
+    best(): Readonly<Partial<Record<K, number>>>;
+    bestOf(field: K): number | null;
+    submit(run: Readonly<Partial<Record<K, number>>>): RecordSubmission<K>;
+    clear(): void;
+}
+/**
+ * A personal-best record book: named numeric fields each racing toward "lower"
+ * (times) or "higher" (scores, streaks), persisted through a structural
+ * key-value storage (pass `localStorage` in a browser, a stub in tests, or
+ * `null` for in-memory only). Corrupt or unavailable storage degrades to an
+ * empty book — a record write never throws into a game tick.
+ */
+export declare function createRecordBook<K extends string>(config: RecordBookConfig<K>): RecordBook<K>;

package/dist/game/recordBook.js

@@ -0,0 +1,86 @@
+function loadStored(config, storage) {
+    if (storage === null)
+        return {};
+    let raw;
+    try {
+        raw = storage.getItem(config.key);
+    }
+    catch {
+        return {};
+    }
+    if (raw === null)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return {};
+    const best = {};
+    for (const field of Object.keys(config.fields)) {
+        const value = parsed[field];
+        if (typeof value === "number" && Number.isFinite(value))
+            best[field] = value;
+    }
+    return best;
+}
+/**
+ * A personal-best record book: named numeric fields each racing toward "lower"
+ * (times) or "higher" (scores, streaks), persisted through a structural
+ * key-value storage (pass `localStorage` in a browser, a stub in tests, or
+ * `null` for in-memory only). Corrupt or unavailable storage degrades to an
+ * empty book — a record write never throws into a game tick.
+ */
+export function createRecordBook(config) {
+    const storage = config.storage ?? null;
+    let best = loadStored(config, storage);
+    function persist() {
+        if (storage === null)
+            return;
+        try {
+            storage.setItem(config.key, JSON.stringify(best));
+        }
+        catch {
+            return;
+        }
+    }
+    return {
+        best() {
+            return { ...best };
+        },
+        bestOf(field) {
+            return best[field] ?? null;
+        },
+        submit(run) {
+            const improved = [];
+            for (const field of Object.keys(config.fields)) {
+                const value = run[field];
+                if (value === undefined || !Number.isFinite(value))
+                    continue;
+                const current = best[field];
+                const beats = current === undefined || (config.fields[field] === "lower" ? value < current : value > current);
+                if (beats) {
+                    best[field] = value;
+                    improved.push(field);
+                }
+            }
+            if (improved.length > 0)
+                persist();
+            return { improved, best: { ...best } };
+        },
+        clear() {
+            best = {};
+            if (storage === null)
+                return;
+            try {
+                storage.removeItem(config.key);
+            }
+            catch {
+                return;
+            }
+        },
+    };
+}

package/dist/game/talents.d.ts

@@ -0,0 +1,47 @@
+import type { StatModifierSet } from "../stats/statModifiers.js";
+export type TalentRequirement = string | {
+    nodeId: string;
+    rank: number;
+};
+export interface TalentNodeDef<TStat extends string = string> {
+    id: string;
+    branch?: string;
+    maxRank: number;
+    requires?: readonly TalentRequirement[];
+    requiresPointsInBranch?: number;
+    modifiersPerRank?: StatModifierSet<TStat>;
+    grantsAbilities?: readonly string[];
+}
+export type TalentAllocateReason = "unknown-node" | "max-rank" | "no-points" | "requires" | "branch-points";
+export type TalentAllocateResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: TalentAllocateReason;
+};
+export interface ResolvedTalents<TStat extends string = string> {
+    stats: StatModifierSet<TStat>;
+    abilities: readonly string[];
+}
+export interface TalentSnapshot {
+    points: number;
+    ranks: Record<string, number>;
+}
+export interface TalentTreeConfig<TStat extends string = string> {
+    nodes: readonly TalentNodeDef<TStat>[];
+    points?: number;
+}
+export interface TalentTree<TStat extends string = string> {
+    rank(nodeId: string): number;
+    pointsAvailable(): number;
+    pointsSpent(): number;
+    pointsInBranch(branch: string): number;
+    grantPoints(amount: number): void;
+    canAllocate(nodeId: string): TalentAllocateResult;
+    allocate(nodeId: string): TalentAllocateResult;
+    resolved(): ResolvedTalents<TStat>;
+    reset(): void;
+    snapshot(): TalentSnapshot;
+    hydrate(snapshot: TalentSnapshot): void;
+}
+export declare function createTalentTree<TStat extends string = string>(config: TalentTreeConfig<TStat>): TalentTree<TStat>;

package/dist/game/talents.js

@@ -0,0 +1,140 @@
+const DEFAULT_BRANCH = "";
+export function createTalentTree(config) {
+    const nodesById = new Map();
+    for (const node of config.nodes)
+        nodesById.set(node.id, node);
+    const ranks = new Map();
+    let points = Math.max(0, config.points ?? 0);
+    let cache = null;
+    function rank(nodeId) {
+        return ranks.get(nodeId) ?? 0;
+    }
+    function branchOf(node) {
+        return node.branch ?? DEFAULT_BRANCH;
+    }
+    function pointsInBranch(branch) {
+        let total = 0;
+        for (const node of nodesById.values()) {
+            if (branchOf(node) === branch)
+                total += rank(node.id);
+        }
+        return total;
+    }
+    function pointsSpent() {
+        let total = 0;
+        for (const value of ranks.values())
+            total += value;
+        return total;
+    }
+    function requirementUnmet(requirement) {
+        const reqNodeId = typeof requirement === "string" ? requirement : requirement.nodeId;
+        const reqRank = typeof requirement === "string" ? 1 : requirement.rank;
+        return rank(reqNodeId) < reqRank;
+    }
+    function canAllocate(nodeId) {
+        const node = nodesById.get(nodeId);
+        if (!node)
+            return { ok: false, reason: "unknown-node" };
+        const currentRank = rank(nodeId);
+        if (currentRank >= node.maxRank)
+            return { ok: false, reason: "max-rank" };
+        if (points < 1)
+            return { ok: false, reason: "no-points" };
+        for (const requirement of node.requires ?? []) {
+            if (requirementUnmet(requirement))
+                return { ok: false, reason: "requires" };
+        }
+        if (node.requiresPointsInBranch !== undefined) {
+            const inBranch = pointsInBranch(branchOf(node)) - currentRank;
+            if (inBranch < node.requiresPointsInBranch)
+                return { ok: false, reason: "branch-points" };
+        }
+        return { ok: true };
+    }
+    function resolve() {
+        const stats = {};
+        const abilities = [];
+        const seenAbilities = new Set();
+        for (const node of nodesById.values()) {
+            const nodeRank = rank(node.id);
+            if (nodeRank <= 0)
+                continue;
+            if (node.modifiersPerRank) {
+                for (const stat of Object.keys(node.modifiersPerRank)) {
+                    const modifier = node.modifiersPerRank[stat];
+                    if (!modifier)
+                        continue;
+                    const entry = stats[stat] ?? {};
+                    if (modifier.add !== undefined)
+                        entry.add = (entry.add ?? 0) + modifier.add * nodeRank;
+                    if (modifier.multiply !== undefined) {
+                        entry.multiply = (entry.multiply ?? 1) * Math.pow(modifier.multiply, nodeRank);
+                    }
+                    stats[stat] = entry;
+                }
+            }
+            if (node.grantsAbilities) {
+                for (const ability of node.grantsAbilities) {
+                    if (seenAbilities.has(ability))
+                        continue;
+                    seenAbilities.add(ability);
+                    abilities.push(ability);
+                }
+            }
+        }
+        return { stats, abilities };
+    }
+    return {
+        rank,
+        pointsAvailable() {
+            return points;
+        },
+        pointsSpent,
+        pointsInBranch,
+        grantPoints(amount) {
+            if (amount > 0)
+                points += amount;
+        },
+        canAllocate,
+        allocate(nodeId) {
+            const result = canAllocate(nodeId);
+            if (!result.ok)
+                return result;
+            points -= 1;
+            ranks.set(nodeId, rank(nodeId) + 1);
+            cache = null;
+            return { ok: true };
+        },
+        resolved() {
+            if (cache === null)
+                cache = resolve();
+            return cache;
+        },
+        reset() {
+            points += pointsSpent();
+            ranks.clear();
+            cache = null;
+        },
+        snapshot() {
+            const snapshotRanks = {};
+            for (const [nodeId, value] of ranks) {
+                if (value > 0)
+                    snapshotRanks[nodeId] = value;
+            }
+            return { points, ranks: snapshotRanks };
+        },
+        hydrate(snapshot) {
+            ranks.clear();
+            points = snapshot.points;
+            for (const [nodeId, value] of Object.entries(snapshot.ranks)) {
+                const node = nodesById.get(nodeId);
+                if (!node)
+                    continue;
+                const clamped = Math.max(0, Math.min(value, node.maxRank));
+                if (clamped > 0)
+                    ranks.set(nodeId, clamped);
+            }
+            cache = null;
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,14 @@
 export * from "./runtime/save.js";
 export * from "./runtime/snapshot.js";
+export * from "./runtime/worldSnapshot.js";
+export * from "./runtime/worldReplication.js";
+export * from "./game/connectedPlayers.js";
+export * from "./runtime/hostedGameRunner.js";
+export * from "./runtime/hostedWorldSession.js";
+export * from "./runtime/worldMirror.js";
+export * from "./runtime/worldChannel.js";
 export * from "./runtime/commandRunner.js";
 export * from "./runtime/gameRuntime.js";
 export * from "./runtime/adapter.js";
 export * from "./runtime/transport.js";
+export * from "./runtime/visibility.js";

package/dist/index.js

@@ -1,6 +1,14 @@
 export * from "./runtime/save.js";
 export * from "./runtime/snapshot.js";
+export * from "./runtime/worldSnapshot.js";
+export * from "./runtime/worldReplication.js";
+export * from "./game/connectedPlayers.js";
+export * from "./runtime/hostedGameRunner.js";
+export * from "./runtime/hostedWorldSession.js";
+export * from "./runtime/worldMirror.js";
+export * from "./runtime/worldChannel.js";
 export * from "./runtime/commandRunner.js";
 export * from "./runtime/gameRuntime.js";
 export * from "./runtime/adapter.js";
 export * from "./runtime/transport.js";
+export * from "./runtime/visibility.js";

package/dist/input/actionBindings.d.ts

@@ -29,6 +29,7 @@ export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
     toggle?: readonly TCode[];
     repeatMs?: number;
 };
+/** Maps each game action name to the input codes (hold/toggle keys, repeat rate) that trigger it. */
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
 export declare function actionRepeatMs(codes: ActionCodes | undefined): number | undefined;
 export interface ShouldDispatchActionInput {
@@ -53,6 +54,7 @@ export declare function isHotbarSlotAction(action: string): boolean;
  * yield null so the shell can handle them itself.
  */
 export declare function resolveActionCommand(action: string, has: (command: string) => boolean, reserved: ReadonlySet<string>): string | null;
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
 export declare function bindingLabel(code: string): string;
 /** Short display label for an action's first bound code, or null when unbound. */
 export declare function actionLabel(map: ActionCodesMap, action: string): string | null;

package/dist/input/actionBindings.js

@@ -127,6 +127,7 @@ const CODE_LABELS = {
     ArrowLeft: "←",
     ArrowRight: "→",
 };
+/** Short display label for a raw key/button code (e.g. `"KeyW"` → `"W"`). */
 export function bindingLabel(code) {
     const direct = CODE_LABELS[code];
     if (direct !== undefined)

package/dist/input/axisInput.d.ts

@@ -1,3 +1,4 @@
+import { type PointerAxisBinding, type PointerAxisState } from "./pointerAxis.js";
 export interface AxisInput {
     throttle: number;
     brake: number;
@@ -9,6 +10,8 @@ export type AxisName = keyof AxisInput;
 export interface AxisBinding {
     positive: readonly string[];
     negative?: readonly string[];
+    /** Pointer-position source for this axis (#293) — takes over from the key lists whenever a pointer is active. */
+    pointer?: PointerAxisBinding;
 }
 export type AxisBindingMap = Record<AxisName, AxisBinding>;
 export interface AxisChannelConfig {
@@ -25,8 +28,9 @@ export declare function rampToward(current: number, target: number, rate: number
 /**
  * Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake
  * are continuous values ramped from held keys (a keyboard feels like a pedal) or driven directly from
- * a gamepad axis via `setAnalog`. `sample(dt, isDown)` folds the current held-key state into the
- * smoothed value; a `setAnalog` override replaces the digital target for that axis until cleared.
+ * a gamepad axis via `setAnalog`. `sample(dt, isDown, pointer?)` folds the current held-key state into
+ * the smoothed value; a binding's `pointer` source takes over from its keys while a pointer is active,
+ * and a `setAnalog` override replaces both for that axis until cleared.
  */
 export declare class AxisChannel {
     private readonly bindings;
@@ -38,6 +42,32 @@ export declare class AxisChannel {
     clearAnalog(axis: AxisName): void;
     reset(): void;
     get value(): AxisInput;
-    sample(dt: number, isDown: (code: string) => boolean): AxisInput;
+    sample(dt: number, isDown: (code: string) => boolean, pointer?: PointerAxisState | null): AxisInput;
 }
 export declare const DRIVE_AXIS_BINDINGS: AxisBindingMap;
+export interface GenericAxisConfig<TAxes extends string> {
+    bindings: Record<TAxes, AxisBinding>;
+    /** Per-axis value range; unlisted axes default to bipolar `[-1, 1]` (use `{ min: 0, max: 1 }` for pedals). */
+    ranges?: Partial<Record<TAxes, AxisRange>>;
+    smoothing?: number;
+}
+/**
+ * The held-key-ramping analog channel for any axis schema (#282.7) — drones (pitch/roll/strafe),
+ * boats, mechs — not just the four car axes `AxisChannel` hardcodes. Same semantics: keys ramp,
+ * `setAnalog` overrides, a binding's `pointer` source takes over while a pointer is active.
+ */
+export interface GenericAxisChannel<TAxes extends string> {
+    sample(dt: number, isDown: (code: string) => boolean, pointer?: PointerAxisState | null): Record<TAxes, number>;
+    setAnalog(axis: TAxes, value: number): void;
+    clearAnalog(axis: TAxes): void;
+    reset(): void;
+    readonly value: Record<TAxes, number>;
+}
+/**
+ * Instantaneous (unsmoothed) analog sample of an axis binding map — the per-frame target an
+ * `AxisChannel` ramps toward, exposed as a pure read for `ctx.input.axis` and headless sampling.
+ * Each axis is its binding's positive-minus-negative held state (or its pointer source while a pointer
+ * is active), clamped to the axis range; axes without a listed range default to bipolar `[-1, 1]`.
+ */
+export declare function sampleAxisBindings<TAxes extends string>(bindings: Record<TAxes, AxisBinding>, isDown: (code: string) => boolean, pointer?: PointerAxisState | null, ranges?: Partial<Record<TAxes, AxisRange>>): Record<TAxes, number>;
+export declare function createAxisChannel<TAxes extends string>(config: GenericAxisConfig<TAxes>): GenericAxisChannel<TAxes>;