@jgengine/core 0.6.0 → 0.8.0

package/dist/movement/voxelController.js

@@ -0,0 +1,229 @@
+/**
+ * Voxel character controller (pure model).
+ *
+ * The base first-person controller in `movementModel.ts` assumes flat ground at
+ * y=0 — it integrates gravity into a `jumpOffset` and never asks the world how
+ * tall the ground is. That is fine for a plaza demo but wrong for any game where
+ * the player walks on placed blocks and digs down into the world: they float on
+ * an invisible floor, clip through walls, and can never descend.
+ *
+ * This module resolves the player as an axis-aligned box against a set of solid
+ * unit cells (a `SolidQuery`), so the same held-keys → intent pipeline drives a
+ * body that stands on blocks, falls into holes, is stopped by walls, and steps
+ * up single-block ledges. Keeping it renderer-free means the shell can drive it
+ * from live scene objects while the descent/landing/step-up behaviour stays unit
+ * testable without three.js.
+ *
+ * Cell convention matches the shell's object rendering and the voxel raycast:
+ * cell (x,y,z) is the solid box X∈[x-0.5,x+0.5], Y∈[y,y+1], Z∈[z-0.5,z+0.5]. A
+ * block at cell y therefore has its top face at world y+1, so a player standing
+ * on the surface layer (cell y=-1) rests with their feet at y=0.
+ */
+import { MOVEMENT_TUNING } from "./movementModel.js";
+export const DEFAULT_VOXEL_DIMS = {
+    halfWidth: 0.3,
+    height: 1.8,
+    stepHeight: 0.6,
+};
+export function createVoxelPlayerBody(x, y, z) {
+    return { x, y, z, velocityX: 0, velocityY: 0, velocityZ: 0, grounded: true, jumpHeld: false };
+}
+const SUPPORT_EPSILON = 0.02;
+const PENETRATION_EPSILON = 1e-4;
+function cellX(worldX) {
+    return Math.floor(worldX + 0.5);
+}
+function cellZ(worldZ) {
+    return Math.floor(worldZ + 0.5);
+}
+/** True if the player box centred at (x, y, z) overlaps any solid cell. */
+function overlapsSolid(x, y, z, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const minCellY = Math.floor(y + PENETRATION_EPSILON);
+    const maxCellY = Math.floor(y + dims.height - PENETRATION_EPSILON);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = minCellY; cy <= maxCellY; cy += 1) {
+                if (isSolid(cx, cy, cz))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+/** True if a solid cell sits directly beneath the feet, or terrain supports them (i.e. the player is supported). */
+function hasSupport(x, z, y, isSolid, dims, groundHeight) {
+    const cy = Math.floor(y - SUPPORT_EPSILON);
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            if (isSolid(cx, cy, cz))
+                return true;
+        }
+    }
+    if (groundHeight !== undefined && y <= groundHeight(x, z) + SUPPORT_EPSILON)
+        return true;
+    return false;
+}
+/**
+ * Highest solid-cell top under the footprint at (x, z) within the vertical
+ * window [fromY, toY]. Returns null when nothing supports the feet there — used
+ * both to snap a fall onto a block and to raise a step-up.
+ */
+function supportTopWithin(x, z, fromY, toY, isSolid, dims) {
+    const minCellX = cellX(x - dims.halfWidth);
+    const maxCellX = cellX(x + dims.halfWidth);
+    const minCellZ = cellZ(z - dims.halfWidth);
+    const maxCellZ = cellZ(z + dims.halfWidth);
+    const lowCellY = Math.floor(fromY - PENETRATION_EPSILON);
+    const highCellY = Math.floor(toY - PENETRATION_EPSILON);
+    let best = null;
+    for (let cx = minCellX; cx <= maxCellX; cx += 1) {
+        for (let cz = minCellZ; cz <= maxCellZ; cz += 1) {
+            for (let cy = lowCellY; cy <= highCellY; cy += 1) {
+                if (!isSolid(cx, cy, cz))
+                    continue;
+                const top = cy + 1;
+                if (best === null || top > best)
+                    best = top;
+            }
+        }
+    }
+    return best;
+}
+function targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed) {
+    if (!intent.moving)
+        return { x: 0, z: 0 };
+    let fx = forwardX;
+    let fz = forwardZ;
+    const lengthSq = fx * fx + fz * fz;
+    if (lengthSq < 1e-6) {
+        fx = 0;
+        fz = -1;
+    }
+    else {
+        const inv = 1 / Math.sqrt(lengthSq);
+        fx *= inv;
+        fz *= inv;
+    }
+    const rightX = -fz;
+    const rightZ = fx;
+    let vx = fx * intent.forward + rightX * intent.right;
+    let vz = fz * intent.forward + rightZ * intent.right;
+    const magSq = vx * vx + vz * vz;
+    if (magSq < 1e-6)
+        return { x: 0, z: 0 };
+    const speedMultiplier = intent.crouching
+        ? MOVEMENT_TUNING.crouchSpeedMultiplier
+        : intent.running
+            ? MOVEMENT_TUNING.runSpeedMultiplier
+            : 1;
+    const targetSpeed = baseSpeed * MOVEMENT_TUNING.walkSpeedMultiplier * speedMultiplier;
+    const scale = targetSpeed / Math.sqrt(magSq);
+    vx *= scale;
+    vz *= scale;
+    return { x: vx, z: vz };
+}
+/**
+ * Move the body along one horizontal axis, resolving collisions. Returns the
+ * component of the step that survived (0 when a wall stopped the move). When the
+ * move is blocked but the obstacle is a short ledge, the body steps up onto it.
+ */
+function moveAxis(body, axis, delta, isSolid, dims) {
+    if (delta === 0)
+        return 0;
+    const nextX = axis === "x" ? body.x + delta : body.x;
+    const nextZ = axis === "z" ? body.z + delta : body.z;
+    if (!overlapsSolid(nextX, body.y, nextZ, isSolid, dims)) {
+        body.x = nextX;
+        body.z = nextZ;
+        return delta;
+    }
+    if (body.grounded) {
+        const raised = supportTopWithin(nextX, nextZ, body.y, body.y + dims.stepHeight, isSolid, dims);
+        if (raised !== null &&
+            raised - body.y <= dims.stepHeight + PENETRATION_EPSILON &&
+            raised >= body.y &&
+            !overlapsSolid(nextX, raised, nextZ, isSolid, dims)) {
+            body.x = nextX;
+            body.z = nextZ;
+            body.y = raised;
+            return delta;
+        }
+    }
+    return 0;
+}
+/**
+ * Advance one frame of voxel-collided player kinematics. Mutates `body`
+ * (position, velocity, grounded) in place.
+ *
+ * `forwardX`/`forwardZ` are the camera heading projected onto the ground plane
+ * (need not be normalized). Pulling this out of the render loop is what lets us
+ * assert "dig the block underfoot and the player drops a level" in a unit test.
+ *
+ * `groundHeight`, when supplied, is an additional solid floor sampled at the
+ * body's (x, z): the player never sinks below it and standing on it counts as
+ * supported (resets jump state like landing on a solid cell). Where terrain and
+ * a solid cell's top disagree, the higher of the two wins.
+ */
+export function advanceVoxelPlayer(body, intent, forwardX, forwardZ, baseSpeed, rawDeltaSeconds, isSolid, dims = DEFAULT_VOXEL_DIMS, tuning, groundHeight) {
+    const dt = Math.min(rawDeltaSeconds, MOVEMENT_TUNING.maxFrameSeconds);
+    const gravityAcceleration = tuning?.gravityAcceleration ?? MOVEMENT_TUNING.gravityAcceleration;
+    const jumpVelocity = tuning?.jumpVelocity ?? MOVEMENT_TUNING.jumpVelocity;
+    const target = targetHorizontalVelocity(intent, forwardX, forwardZ, baseSpeed);
+    const acceleration = body.grounded
+        ? MOVEMENT_TUNING.groundAcceleration
+        : MOVEMENT_TUNING.airAcceleration;
+    const accelerationBlend = 1 - Math.exp(-acceleration * dt);
+    body.velocityX += (target.x - body.velocityX) * accelerationBlend;
+    body.velocityZ += (target.z - body.velocityZ) * accelerationBlend;
+    if (!intent.moving && body.grounded) {
+        const friction = Math.exp(-MOVEMENT_TUNING.groundFriction * dt);
+        body.velocityX *= friction;
+        body.velocityZ *= friction;
+    }
+    if (moveAxis(body, "x", body.velocityX * dt, isSolid, dims) === 0)
+        body.velocityX = 0;
+    if (moveAxis(body, "z", body.velocityZ * dt, isSolid, dims) === 0)
+        body.velocityZ = 0;
+    const supported = body.grounded && hasSupport(body.x, body.z, body.y, isSolid, dims, groundHeight);
+    body.grounded = supported;
+    const jumpPressed = intent.jumping;
+    if (jumpPressed && !body.jumpHeld && body.grounded && !intent.crouching) {
+        body.velocityY = jumpVelocity;
+        body.grounded = false;
+    }
+    body.jumpHeld = jumpPressed;
+    if (!body.grounded) {
+        body.velocityY -= gravityAcceleration * dt;
+        const nextY = body.y + body.velocityY * dt;
+        if (body.velocityY <= 0) {
+            const terrainFloor = groundHeight?.(body.x, body.z);
+            const solidBlocked = overlapsSolid(body.x, nextY, body.z, isSolid, dims);
+            const terrainBlocked = terrainFloor !== undefined && nextY <= terrainFloor;
+            if (solidBlocked || terrainBlocked) {
+                const solidTop = solidBlocked
+                    ? (supportTopWithin(body.x, body.z, nextY, body.y + dims.height, isSolid, dims) ?? Math.floor(body.y))
+                    : undefined;
+                body.y = Math.max(solidTop ?? -Infinity, terrainFloor ?? -Infinity);
+                body.velocityY = 0;
+                body.grounded = true;
+            }
+            else {
+                body.y = nextY;
+            }
+        }
+        else if (overlapsSolid(body.x, nextY, body.z, isSolid, dims)) {
+            body.velocityY = 0;
+        }
+        else {
+            body.y = nextY;
+        }
+    }
+}

package/dist/multiplayer/chatContract.d.ts

@@ -0,0 +1,42 @@
+import type { ChatMessage } from "../game/chat.js";
+export interface ChatSendArgs {
+    channelId: string;
+    body: string;
+}
+export interface ChatSendOutcome {
+    ok: boolean;
+    reason?: string;
+}
+export interface ChatActions {
+    sendMessage(args: ChatSendArgs): Promise<ChatSendOutcome>;
+}
+/**
+ * Backend seam for remote text chat, mirroring PresenceTransport: the use*
+ * members are called as React hooks by consumers, so a mounted transport must
+ * never change identity — remount the subtree to switch backends. useMessages
+ * returns undefined while the subscription is loading and the channel's recent
+ * history once live.
+ */
+export interface ChatTransport {
+    useMessages(channelId: string | "skip"): readonly ChatMessage[] | undefined;
+    useActions(): ChatActions;
+}
+/**
+ * Callback seam for backends that cannot host React hooks (e.g. the ws
+ * client): subscribe delivers the channel's recent history on every change;
+ * send resolves with the host's verdict. @jgengine/react's chatTransportFromSync
+ * lifts a ChatSync into a ChatTransport.
+ */
+export interface ChatSync {
+    subscribe(channelId: string, onChange: (messages: readonly ChatMessage[]) => void): () => void;
+    send(channelId: string, body: string): Promise<ChatSendOutcome>;
+}
+export declare function createLocalChatTransport(options?: {
+    userId?: string;
+    historyLimit?: number;
+    now?: () => number;
+}): {
+    transport: ChatTransport;
+    sync: ChatSync;
+    actions: ChatActions;
+};

package/dist/multiplayer/chatContract.js

@@ -0,0 +1,57 @@
+export function createLocalChatTransport(options) {
+    const userId = options?.userId ?? "local";
+    const historyLimit = options?.historyLimit ?? 100;
+    const now = options?.now ?? Date.now;
+    const messagesByChannel = new Map();
+    const listeners = new Map();
+    let counter = 0;
+    function snapshot(channelId) {
+        return (messagesByChannel.get(channelId) ?? []).slice();
+    }
+    const sync = {
+        subscribe(channelId, onChange) {
+            let set = listeners.get(channelId);
+            if (set === undefined) {
+                set = new Set();
+                listeners.set(channelId, set);
+            }
+            set.add(onChange);
+            onChange(snapshot(channelId));
+            return () => {
+                set.delete(onChange);
+                if (set.size === 0)
+                    listeners.delete(channelId);
+            };
+        },
+        send(channelId, body) {
+            const trimmed = body.trim();
+            if (trimmed.length === 0)
+                return Promise.resolve({ ok: false, reason: "empty message" });
+            counter += 1;
+            const message = {
+                id: `local_${counter}`,
+                channelId,
+                fromUserId: userId,
+                body: trimmed,
+                at: now(),
+            };
+            const ring = messagesByChannel.get(channelId) ?? [];
+            ring.push(message);
+            if (ring.length > historyLimit)
+                ring.splice(0, ring.length - historyLimit);
+            messagesByChannel.set(channelId, ring);
+            const current = snapshot(channelId);
+            for (const listener of listeners.get(channelId) ?? [])
+                listener(current);
+            return Promise.resolve({ ok: true });
+        },
+    };
+    const actions = {
+        sendMessage: (args) => sync.send(args.channelId, args.body),
+    };
+    const transport = {
+        useMessages: (channelId) => (channelId === "skip" ? undefined : snapshot(channelId)),
+        useActions: () => actions,
+    };
+    return { transport, sync, actions };
+}

package/dist/multiplayer/combatSnapshot.d.ts

@@ -0,0 +1,45 @@
+export interface SnapshotUnit {
+    id: string;
+    stats: Readonly<Record<string, number>>;
+}
+export interface BoardSnapshot {
+    ownerId: string;
+    units: readonly SnapshotUnit[];
+    stats: Readonly<Record<string, number>>;
+    seed: number;
+    capturedAt: number;
+}
+export interface SerializeBoardArgs {
+    ownerId: string;
+    units: readonly SnapshotUnit[];
+    stats?: Readonly<Record<string, number>>;
+    seed?: number;
+    capturedAt?: number;
+}
+export declare function serializeBoard(args: SerializeBoardArgs): BoardSnapshot;
+export declare function cloneSnapshot(snapshot: BoardSnapshot): BoardSnapshot;
+export interface CombatRules {
+    attackStat: string;
+    healthStat: string;
+    maxRounds?: number;
+    critChance?: number;
+    critMultiplier?: number;
+}
+export type CombatSide = "a" | "b" | "draw";
+export interface ReplayBlow {
+    round: number;
+    attacker: CombatSide;
+    attackerUnit: string;
+    defenderUnit: string;
+    damage: number;
+    crit: boolean;
+    defenderHealthAfter: number;
+}
+export interface ReplayResult {
+    winner: CombatSide;
+    rounds: number;
+    blows: readonly ReplayBlow[];
+    survivorsA: readonly string[];
+    survivorsB: readonly string[];
+}
+export declare function replayCombat(a: BoardSnapshot, b: BoardSnapshot, rules: CombatRules): ReplayResult;

package/dist/multiplayer/combatSnapshot.js

@@ -0,0 +1,89 @@
+function cloneStats(stats) {
+    return { ...stats };
+}
+export function serializeBoard(args) {
+    return {
+        ownerId: args.ownerId,
+        units: args.units.map((unit) => ({ id: unit.id, stats: cloneStats(unit.stats) })),
+        stats: cloneStats(args.stats ?? {}),
+        seed: args.seed ?? 0,
+        capturedAt: args.capturedAt ?? 0,
+    };
+}
+export function cloneSnapshot(snapshot) {
+    return serializeBoard({
+        ownerId: snapshot.ownerId,
+        units: snapshot.units,
+        stats: snapshot.stats,
+        seed: snapshot.seed,
+        capturedAt: snapshot.capturedAt,
+    });
+}
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function toLive(snapshot, rules) {
+    return snapshot.units.map((unit) => ({
+        id: unit.id,
+        attack: unit.stats[rules.attackStat] ?? 0,
+        health: unit.stats[rules.healthStat] ?? 0,
+    }));
+}
+export function replayCombat(a, b, rules) {
+    const maxRounds = rules.maxRounds ?? 100;
+    const critChance = rules.critChance ?? 0;
+    const critMultiplier = rules.critMultiplier ?? 2;
+    const prng = mulberry32((a.seed ^ (b.seed * 0x9e3779b1)) >>> 0);
+    const liveA = toLive(a, rules);
+    const liveB = toLive(b, rules);
+    const blows = [];
+    let indexA = 0;
+    let indexB = 0;
+    let rounds = 0;
+    const strike = (round, attacker, attackers, attackerIndex, defenders) => {
+        const source = attackers[attackerIndex];
+        const target = defenders[0];
+        const crit = critChance > 0 && prng() < critChance;
+        const damage = crit ? Math.round(source.attack * critMultiplier) : source.attack;
+        target.health -= damage;
+        blows.push({
+            round,
+            attacker,
+            attackerUnit: source.id,
+            defenderUnit: target.id,
+            damage,
+            crit,
+            defenderHealthAfter: target.health,
+        });
+        if (target.health <= 0)
+            defenders.shift();
+    };
+    while (liveA.length > 0 && liveB.length > 0 && rounds < maxRounds) {
+        rounds += 1;
+        strike(rounds, "a", liveA, indexA % liveA.length, liveB);
+        if (liveB.length === 0)
+            break;
+        strike(rounds, "b", liveB, indexB % liveB.length, liveA);
+        indexA += 1;
+        indexB += 1;
+    }
+    const winner = liveA.length > 0 && liveB.length === 0
+        ? "a"
+        : liveB.length > 0 && liveA.length === 0
+            ? "b"
+            : "draw";
+    return {
+        winner,
+        rounds,
+        blows,
+        survivorsA: liveA.map((u) => u.id),
+        survivorsB: liveB.map((u) => u.id),
+    };
+}

package/dist/multiplayer/identity.d.ts

@@ -0,0 +1,13 @@
+export interface AuthSession {
+    userId: string;
+    displayName?: string;
+    avatarUrl?: string;
+    email?: string;
+    isNew?: boolean;
+}
+export interface PlayerIdentity {
+    userId: string;
+    isNew: boolean;
+}
+export declare function sessionPlayer(session: AuthSession): PlayerIdentity;
+export declare function resolveGuestSession(seed?: string): AuthSession;

package/dist/multiplayer/identity.js

@@ -0,0 +1,20 @@
+export function sessionPlayer(session) {
+    return { userId: session.userId, isNew: session.isNew ?? false };
+}
+const DEFAULT_GUEST_SEED = "local";
+export function resolveGuestSession(seed) {
+    const normalized = seed === undefined || seed.trim().length === 0 ? DEFAULT_GUEST_SEED : seed.trim();
+    const hash = fnv1a(normalized);
+    return {
+        userId: `guest_${hash}`,
+        displayName: `Guest ${hash.slice(0, 4).toUpperCase()}`,
+    };
+}
+function fnv1a(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index += 1) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}

package/dist/multiplayer/lagCompensation.d.ts

@@ -0,0 +1,43 @@
+export interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface PositionSample extends Vec3 {
+    t: number;
+}
+export interface PositionHistoryConfig {
+    historyMs: number;
+    maxSamples?: number;
+}
+export declare class PositionHistory {
+    private readonly historyMs;
+    private readonly maxSamples;
+    private readonly tracks;
+    constructor(config: PositionHistoryConfig);
+    record(entityId: string, t: number, position: Vec3): void;
+    private trim;
+    entities(): string[];
+    samples(entityId: string): readonly PositionSample[];
+    sampleAt(entityId: string, t: number): Vec3 | null;
+    prune(now: number): void;
+    forget(entityId: string): void;
+}
+export declare function createPositionHistory(config: PositionHistoryConfig): PositionHistory;
+export declare function rewindTimestamp(nowMs: number, rttMs: number, interpDelayMs: number): number;
+export interface HitscanRay {
+    origin: Vec3;
+    direction: Vec3;
+    maxDistance?: number;
+}
+export interface HitscanTarget {
+    entityId: string;
+    radius: number;
+}
+export interface HitscanHit {
+    entityId: string;
+    distance: number;
+    point: Vec3;
+}
+export declare function raySphereDistance(ray: HitscanRay, center: Vec3, radius: number): number | null;
+export declare function resolveHitscan(history: PositionHistory, targets: readonly HitscanTarget[], ray: HitscanRay, atMs: number): HitscanHit | null;

package/dist/multiplayer/lagCompensation.js

@@ -0,0 +1,154 @@
+const DEFAULT_MAX_SAMPLES = 256;
+export class PositionHistory {
+    historyMs;
+    maxSamples;
+    tracks = new Map();
+    constructor(config) {
+        if (!(config.historyMs > 0)) {
+            throw new RangeError(`historyMs must be positive, got ${config.historyMs}`);
+        }
+        this.historyMs = config.historyMs;
+        this.maxSamples = config.maxSamples ?? DEFAULT_MAX_SAMPLES;
+    }
+    record(entityId, t, position) {
+        let track = this.tracks.get(entityId);
+        if (track === undefined) {
+            track = [];
+            this.tracks.set(entityId, track);
+        }
+        const sample = { t, x: position.x, y: position.y, z: position.z };
+        const last = track[track.length - 1];
+        if (last !== undefined && t <= last.t) {
+            if (t === last.t) {
+                track[track.length - 1] = sample;
+                return;
+            }
+            let index = track.length;
+            while (index > 0 && track[index - 1].t > t)
+                index -= 1;
+            track.splice(index, 0, sample);
+        }
+        else {
+            track.push(sample);
+        }
+        this.trim(track, t);
+    }
+    trim(track, newest) {
+        const cutoff = newest - this.historyMs;
+        let drop = 0;
+        while (drop < track.length - 1 && track[drop].t < cutoff)
+            drop += 1;
+        if (drop > 0)
+            track.splice(0, drop);
+        if (track.length > this.maxSamples) {
+            track.splice(0, track.length - this.maxSamples);
+        }
+    }
+    entities() {
+        return [...this.tracks.keys()];
+    }
+    samples(entityId) {
+        return this.tracks.get(entityId) ?? [];
+    }
+    sampleAt(entityId, t) {
+        const track = this.tracks.get(entityId);
+        if (track === undefined || track.length === 0)
+            return null;
+        const first = track[0];
+        const last = track[track.length - 1];
+        if (t <= first.t)
+            return { x: first.x, y: first.y, z: first.z };
+        if (t >= last.t)
+            return { x: last.x, y: last.y, z: last.z };
+        let lo = 0;
+        let hi = track.length - 1;
+        while (hi - lo > 1) {
+            const mid = (lo + hi) >> 1;
+            if (track[mid].t <= t)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        const a = track[lo];
+        const b = track[hi];
+        const span = b.t - a.t;
+        const alpha = span === 0 ? 0 : (t - a.t) / span;
+        return {
+            x: a.x + (b.x - a.x) * alpha,
+            y: a.y + (b.y - a.y) * alpha,
+            z: a.z + (b.z - a.z) * alpha,
+        };
+    }
+    prune(now) {
+        for (const [entityId, track] of this.tracks) {
+            this.trim(track, now);
+            if (track.length === 0)
+                this.tracks.delete(entityId);
+        }
+    }
+    forget(entityId) {
+        this.tracks.delete(entityId);
+    }
+}
+export function createPositionHistory(config) {
+    return new PositionHistory(config);
+}
+export function rewindTimestamp(nowMs, rttMs, interpDelayMs) {
+    return nowMs - rttMs / 2 - interpDelayMs;
+}
+function normalize(v) {
+    const len = Math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z);
+    if (len === 0)
+        return null;
+    return { x: v.x / len, y: v.y / len, z: v.z / len };
+}
+export function raySphereDistance(ray, center, radius) {
+    const dir = normalize(ray.direction);
+    if (dir === null)
+        return null;
+    const ox = ray.origin.x - center.x;
+    const oy = ray.origin.y - center.y;
+    const oz = ray.origin.z - center.z;
+    const b = ox * dir.x + oy * dir.y + oz * dir.z;
+    const c = ox * ox + oy * oy + oz * oz - radius * radius;
+    if (c > 0 && b > 0)
+        return null;
+    const disc = b * b - c;
+    if (disc < 0)
+        return null;
+    const sqrtDisc = Math.sqrt(disc);
+    const tNear = -b - sqrtDisc;
+    const t = tNear >= 0 ? tNear : -b + sqrtDisc;
+    if (t < 0)
+        return null;
+    const maxDistance = ray.maxDistance ?? Number.POSITIVE_INFINITY;
+    if (t > maxDistance)
+        return null;
+    return t;
+}
+export function resolveHitscan(history, targets, ray, atMs) {
+    const dir = normalize(ray.direction);
+    if (dir === null)
+        return null;
+    let best = null;
+    for (const target of targets) {
+        const center = history.sampleAt(target.entityId, atMs);
+        if (center === null)
+            continue;
+        const distance = raySphereDistance(ray, center, target.radius);
+        if (distance === null)
+            continue;
+        if (best === null || distance < best.distance) {
+            best = {
+                entityId: target.entityId,
+                distance,
+                point: {
+                    x: ray.origin.x + dir.x * distance,
+                    y: ray.origin.y + dir.y * distance,
+                    z: ray.origin.z + dir.z * distance,
+                },
+            };
+        }
+    }
+    return best;
+}