@jgengine/core 0.8.0 → 0.9.0

package/dist/game/quest.js

@@ -72,17 +72,20 @@ export function createQuestJournal(deps) {
         return null;
     }
     function applyRewards(userId, rewards) {
+        for (const entry of rewards.items ?? []) {
+            const fail = deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
+            if (fail !== null)
+                return fail;
+        }
         if (rewards.xp)
             deps.rewards.grantXp(userId, rewards.xp.amount);
         for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
             deps.rewards.grantEconomy(userId, currencyId, amount);
         }
-        for (const entry of rewards.items ?? []) {
-            deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
-        }
         for (const unlockId of rewards.unlocks ?? []) {
             deps.rewards.grantUnlock(userId, unlockId);
         }
+        return null;
     }
     function turnIn(userId, questId) {
         const denied = canTurnIn(userId, questId);
@@ -90,9 +93,12 @@ export function createQuestJournal(deps) {
             return denied;
         const def = catalog.get(questId);
         const state = users.get(userId).get(questId);
+        if (def.rewards) {
+            const fail = applyRewards(userId, def.rewards);
+            if (fail !== null)
+                return fail;
+        }
         state.status = "completed";
-        if (def.rewards)
-            applyRewards(userId, def.rewards);
         deps.events.emit("quest.completed", { userId, questId });
         for (const nextQuestId of def.rewards?.quests ?? []) {
             if (canAccept(userId, nextQuestId) === null)
@@ -227,17 +233,20 @@ export function createQuestJournal(deps) {
     };
 }
 export function applyQuestRewards(rewards, appliers) {
+    for (const entry of rewards.items ?? []) {
+        const fail = appliers.grantItem?.(entry.inventory, entry.item, entry.count);
+        if (fail != null && typeof fail === "object" && "reason" in fail)
+            return fail;
+    }
     if (rewards.xp)
         appliers.grantXp?.(rewards.xp.amount);
     for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
         appliers.grantEconomy?.(currencyId, amount);
     }
-    for (const entry of rewards.items ?? []) {
-        appliers.grantItem?.(entry.inventory, entry.item, entry.count);
-    }
     for (const unlockId of rewards.unlocks ?? []) {
         appliers.grantUnlock?.(unlockId);
     }
+    return null;
 }
 function toWorking(state) {
     const working = new Map();

package/dist/game/race.d.ts

@@ -3,18 +3,36 @@ export interface Checkpoint {
     center: readonly [number, number, number];
     half: readonly [number, number, number];
 }
+export interface RaceForkRoute {
+    id: string;
+    checkpoints: readonly Checkpoint[];
+}
+/**
+ * An alternate-route section (#286.3): after passing mainline checkpoint `afterIndex`, a racer commits
+ * to whichever route's first checkpoint they hit, runs its checkpoints in order, and rejoins at
+ * mainline `afterIndex + 1`. Every completed route contributes exactly one checkpoint of `progress`
+ * regardless of length, and each hit records a split — so route time accounting comes for free.
+ */
+export interface RaceFork {
+    id: string;
+    /** Mainline checkpoint index the fork opens after; must be before the finish line. */
+    afterIndex: number;
+    routes: readonly RaceForkRoute[];
+}
 export interface RaceTrackConfig {
     checkpoints: readonly Checkpoint[];
     laps?: number;
+    forks?: readonly RaceFork[];
 }
 export interface RaceTrack {
     readonly checkpoints: readonly Checkpoint[];
     readonly laps: number;
+    readonly forks: readonly RaceFork[];
 }
 /**
  * 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 declare function raceTrack(config: RaceTrackConfig): RaceTrack;
 export interface RacerProgress {
@@ -28,6 +46,13 @@ export interface RacerProgress {
     finishTime: number | null;
     eliminated: boolean;
     splits: readonly number[];
+    /** Fork id → route id last taken through it. */
+    routesTaken: Readonly<Record<string, string>>;
+    /** Route the racer is currently inside, or `null` on the mainline. */
+    activeRoute: {
+        forkId: string;
+        routeId: string;
+    } | null;
 }
 export type RaceEvent = {
     type: "checkpoint.hit";
@@ -35,6 +60,18 @@ export type RaceEvent = {
     checkpoint: number;
     lap: number;
     time: number;
+    /** Set when the hit is a fork-route checkpoint (`checkpoint` is then the fork's `afterIndex`). */
+    fork?: {
+        forkId: string;
+        routeId: string;
+        index: number;
+    };
+} | {
+    type: "fork.taken";
+    racerId: string;
+    forkId: string;
+    routeId: string;
+    time: number;
 } | {
     type: "lap.completed";
     racerId: string;
@@ -90,6 +127,7 @@ export declare class RaceState {
     progressOf(racerId: string): RacerProgress | null;
     private snapshot;
     standings(): readonly RacerProgress[];
+    private expectedCheckpoint;
     resetToCheckpoint(racerId: string): {
         position: [number, number, number];
         heading: number;

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,29 @@
+export interface RecordStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+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

@@ -4,3 +4,4 @@ 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

@@ -4,3 +4,4 @@ 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/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,25 @@ 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>;
+}
+export declare function createAxisChannel<TAxes extends string>(config: GenericAxisConfig<TAxes>): GenericAxisChannel<TAxes>;