@jgengine/core 0.6.0 → 0.7.0

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/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;
+}

package/dist/multiplayer/matchmaking.d.ts

@@ -0,0 +1,33 @@
+export type SessionVisibility = "public" | "private";
+export type SessionStatus = "open" | "running" | "closed";
+export interface SessionListing {
+    serverId: string;
+    gameId: string;
+    status: SessionStatus;
+    visibility: SessionVisibility;
+    memberCount: number;
+    slotsPerServer: number;
+    label?: string;
+    mode?: string;
+    joinCode?: string;
+    tags?: readonly string[];
+    updatedAt: number;
+}
+export interface MatchFilter {
+    mode?: string;
+    tags?: readonly string[];
+    query?: string;
+    notFull?: boolean;
+    status?: readonly SessionStatus[];
+    includePrivate?: boolean;
+}
+export interface BrowseOptions {
+    limit?: number;
+}
+export declare function normalizeJoinCode(code: string): string;
+export declare function generateJoinCode(random: () => number, length?: number): string;
+export declare function hasSpace(listing: SessionListing): boolean;
+export declare function matchesFilter(listing: SessionListing, filter: MatchFilter): boolean;
+export declare function browseSessions(listings: readonly SessionListing[], filter?: MatchFilter, options?: BrowseOptions): SessionListing[];
+export declare function findByJoinCode(listings: readonly SessionListing[], code: string): SessionListing | null;
+export declare function quickMatch(listings: readonly SessionListing[], filter?: MatchFilter): SessionListing | null;

package/dist/multiplayer/matchmaking.js

@@ -0,0 +1,60 @@
+export function normalizeJoinCode(code) {
+    return code.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+export function generateJoinCode(random, length = 6) {
+    let code = "";
+    for (let i = 0; i < length; i += 1) {
+        const index = Math.min(CODE_ALPHABET.length - 1, Math.floor(random() * CODE_ALPHABET.length));
+        code += CODE_ALPHABET[index];
+    }
+    return code;
+}
+export function hasSpace(listing) {
+    return listing.memberCount < listing.slotsPerServer;
+}
+export function matchesFilter(listing, filter) {
+    if (listing.visibility === "private" && filter.includePrivate !== true)
+        return false;
+    const statuses = filter.status ?? ["open", "running"];
+    if (!statuses.includes(listing.status))
+        return false;
+    if (filter.mode !== undefined && listing.mode !== filter.mode)
+        return false;
+    if (filter.notFull === true && !hasSpace(listing))
+        return false;
+    if (filter.tags !== undefined && filter.tags.length > 0) {
+        const owned = new Set(listing.tags ?? []);
+        if (!filter.tags.every((tag) => owned.has(tag)))
+            return false;
+    }
+    if (filter.query !== undefined && filter.query.length > 0) {
+        const haystack = (listing.label ?? "").toLowerCase();
+        if (!haystack.includes(filter.query.toLowerCase()))
+            return false;
+    }
+    return true;
+}
+export function browseSessions(listings, filter = {}, options = {}) {
+    const matched = listings
+        .filter((listing) => matchesFilter(listing, filter))
+        .sort((a, b) => b.memberCount - a.memberCount || b.updatedAt - a.updatedAt);
+    return options.limit !== undefined ? matched.slice(0, options.limit) : matched;
+}
+export function findByJoinCode(listings, code) {
+    const normalized = normalizeJoinCode(code);
+    if (normalized.length === 0)
+        return null;
+    for (const listing of listings) {
+        if (listing.joinCode !== undefined && normalizeJoinCode(listing.joinCode) === normalized) {
+            return listing;
+        }
+    }
+    return null;
+}
+export function quickMatch(listings, filter = {}) {
+    const candidates = listings
+        .filter((listing) => matchesFilter(listing, { ...filter, notFull: true }))
+        .sort((a, b) => b.memberCount - a.memberCount || a.updatedAt - b.updatedAt);
+    return candidates[0] ?? null;
+}

package/dist/multiplayer/simultaneousCommit.d.ts

@@ -0,0 +1,34 @@
+export type CommitPhase = "collecting" | "revealed";
+export interface SealedCommit<TAction> {
+    playerId: string;
+    action: TAction;
+    sealedAt: number;
+}
+export interface CommitRoundConfig {
+    participants: readonly string[];
+    allowReseal?: boolean;
+}
+export type SealResult = {
+    ok: true;
+    allSealed: boolean;
+} | {
+    ok: false;
+    reason: "unknown_participant" | "already_sealed" | "already_revealed";
+};
+export declare class CommitRound<TAction> {
+    private readonly order;
+    private readonly participants;
+    private readonly allowReseal;
+    private readonly sealed;
+    private revealedFlag;
+    constructor(config: CommitRoundConfig);
+    seal(playerId: string, action: TAction, at: number): SealResult;
+    hasSealed(playerId: string): boolean;
+    sealedCount(): number;
+    pending(): string[];
+    allSealed(): boolean;
+    get phase(): CommitPhase;
+    reveal(): readonly SealedCommit<TAction>[] | null;
+}
+export declare function createCommitRound<TAction>(config: CommitRoundConfig): CommitRound<TAction>;
+export declare function resolveCommits<TAction, TResult>(reveals: readonly SealedCommit<TAction>[], resolver: (ordered: readonly SealedCommit<TAction>[]) => TResult): TResult;

package/dist/multiplayer/simultaneousCommit.js

@@ -0,0 +1,53 @@
+export class CommitRound {
+    order;
+    participants;
+    allowReseal;
+    sealed = new Map();
+    revealedFlag = false;
+    constructor(config) {
+        if (config.participants.length === 0) {
+            throw new RangeError("a commit round needs at least one participant");
+        }
+        this.order = [...config.participants];
+        this.participants = new Set(config.participants);
+        this.allowReseal = config.allowReseal ?? false;
+    }
+    seal(playerId, action, at) {
+        if (this.revealedFlag)
+            return { ok: false, reason: "already_revealed" };
+        if (!this.participants.has(playerId))
+            return { ok: false, reason: "unknown_participant" };
+        if (this.sealed.has(playerId) && !this.allowReseal) {
+            return { ok: false, reason: "already_sealed" };
+        }
+        this.sealed.set(playerId, { playerId, action, sealedAt: at });
+        return { ok: true, allSealed: this.allSealed() };
+    }
+    hasSealed(playerId) {
+        return this.sealed.has(playerId);
+    }
+    sealedCount() {
+        return this.sealed.size;
+    }
+    pending() {
+        return this.order.filter((id) => !this.sealed.has(id));
+    }
+    allSealed() {
+        return this.sealed.size === this.participants.size;
+    }
+    get phase() {
+        return this.revealedFlag ? "revealed" : "collecting";
+    }
+    reveal() {
+        if (!this.allSealed())
+            return null;
+        this.revealedFlag = true;
+        return this.order.map((id) => this.sealed.get(id));
+    }
+}
+export function createCommitRound(config) {
+    return new CommitRound(config);
+}
+export function resolveCommits(reveals, resolver) {
+    return resolver(reveals);
+}

package/dist/nav/navGrid.d.ts

@@ -0,0 +1,46 @@
+import type { Aabb } from "../world/geometry.js";
+export type NavPoint = readonly [number, number];
+export interface NavGridConfig {
+    bounds: Aabb;
+    cellSize: number;
+    /** Allow 8-neighbour movement (no corner cutting). Default true. */
+    diagonal?: boolean;
+}
+export interface NavCell {
+    col: number;
+    row: number;
+}
+export interface FindPathOptions {
+    /** String-pull the raw grid path into straight runs where line-of-sight is clear. Default true. */
+    smooth?: boolean;
+    /** Diameter of the mover in world units — blocks cells within this margin of an obstacle. Default 0. */
+    clearance?: number;
+}
+export interface NavGrid {
+    readonly cols: number;
+    readonly rows: number;
+    readonly cellSize: number;
+    readonly bounds: Aabb;
+    readonly diagonal: boolean;
+    isWalkable(col: number, row: number): boolean;
+    setWalkable(col: number, row: number, walkable: boolean): void;
+    blockAabb(aabb: Aabb): void;
+    clearAabb(aabb: Aabb): void;
+    reset(walkable: boolean): void;
+    inBounds(col: number, row: number): boolean;
+    cellAt(point: NavPoint): NavCell;
+    center(col: number, row: number): NavPoint;
+    /** Nearest walkable cell to a point (spiral search); null if the whole grid is blocked. */
+    nearestWalkable(point: NavPoint): NavCell | null;
+    /** Unobstructed straight line between two world points (supercover cell walk). */
+    lineOfSight(from: NavPoint, to: NavPoint): boolean;
+}
+export declare function createNavGrid(config: NavGridConfig): NavGrid;
+/**
+ * A* over the walkable grid. Returns a polyline of world-space `[x, z]` waypoints
+ * from `from` to `to`, or `null` when no route exists. Blocked start/goal snap to
+ * the nearest walkable cell so a click on an obstacle still routes to its edge.
+ */
+export declare function findPath(grid: NavGrid, from: NavPoint, to: NavPoint, options?: FindPathOptions): NavPoint[] | null;
+/** Remove waypoints the mover can skip because it has clear line-of-sight past them. */
+export declare function smoothPath(grid: NavGrid, points: readonly NavPoint[]): NavPoint[];