@jgengine/core 0.6.0 → 0.8.0

package/dist/tactics/surface.d.ts

@@ -0,0 +1,52 @@
+import type { Tile } from "./tacticalGrid.js";
+export interface SurfaceKindDef {
+    id: string;
+    duration?: number;
+}
+export interface SurfaceReaction {
+    when: readonly [string, string];
+    result: string | null;
+}
+export interface SurfaceLayerConfig {
+    kinds: readonly SurfaceKindDef[];
+    reactions?: readonly SurfaceReaction[];
+}
+export interface SurfacePatch {
+    duration?: number;
+}
+export type SurfaceEvent = {
+    kind: "apply";
+    tile: Tile;
+    surface: string;
+} | {
+    kind: "react";
+    tile: Tile;
+    consumed: readonly [string, string];
+    produced: string | null;
+} | {
+    kind: "expire";
+    tile: Tile;
+    surface: string;
+};
+export interface SurfaceCellKind {
+    surface: string;
+    remaining: number | null;
+}
+export interface SurfaceCell {
+    tile: Tile;
+    kinds: SurfaceCellKind[];
+}
+export type SurfaceLayerSnapshot = Record<string, Record<string, number | null>>;
+export interface SurfaceLayer {
+    apply(tile: Tile, surface: string, patch?: SurfacePatch): SurfaceEvent[];
+    has(tile: Tile, surface: string): boolean;
+    kindsAt(tile: Tile): string[];
+    remove(tile: Tile, surface: string): void;
+    clearTile(tile: Tile): void;
+    clear(): void;
+    tick(dt: number): SurfaceEvent[];
+    cells(): SurfaceCell[];
+    capture(): SurfaceLayerSnapshot;
+    restore(snapshot: SurfaceLayerSnapshot): void;
+}
+export declare function createSurfaceLayer(config: SurfaceLayerConfig): SurfaceLayer;

package/dist/tactics/surface.js

@@ -0,0 +1,135 @@
+function key(tile) {
+    return `${tile[0]},${tile[1]}`;
+}
+function parseKey(k) {
+    const [c, r] = k.split(",");
+    return [Number(c), Number(r)];
+}
+function pairKey(a, b) {
+    return `${a}|${b}`;
+}
+export function createSurfaceLayer(config) {
+    const durations = new Map();
+    for (const k of config.kinds)
+        durations.set(k.id, k.duration);
+    const reactions = new Map();
+    for (const reaction of config.reactions ?? []) {
+        const [a, b] = reaction.when;
+        reactions.set(pairKey(a, b), reaction.result);
+        reactions.set(pairKey(b, a), reaction.result);
+    }
+    const cells = new Map();
+    function cellOf(tile) {
+        const k = key(tile);
+        let cell = cells.get(k);
+        if (cell === undefined) {
+            cell = new Map();
+            cells.set(k, cell);
+        }
+        return cell;
+    }
+    function initialRemaining(surface, patch) {
+        if (patch?.duration !== undefined)
+            return patch.duration;
+        const configured = durations.get(surface);
+        return configured === undefined ? null : configured;
+    }
+    function resolveReactions(tile, events) {
+        const cell = cellOf(tile);
+        for (;;) {
+            const active = [...cell.keys()];
+            let matched = null;
+            outer: for (let i = 0; i < active.length; i += 1) {
+                for (let j = i + 1; j < active.length; j += 1) {
+                    const result = reactions.get(pairKey(active[i], active[j]));
+                    if (result !== undefined) {
+                        matched = { a: active[i], b: active[j], result };
+                        break outer;
+                    }
+                }
+            }
+            if (matched === null)
+                return;
+            cell.delete(matched.a);
+            cell.delete(matched.b);
+            if (matched.result !== null)
+                cell.set(matched.result, initialRemaining(matched.result));
+            events.push({ kind: "react", tile, consumed: [matched.a, matched.b], produced: matched.result });
+        }
+    }
+    return {
+        apply: (tile, surface, patch) => {
+            const events = [];
+            const cell = cellOf(tile);
+            cell.set(surface, initialRemaining(surface, patch));
+            events.push({ kind: "apply", tile, surface });
+            resolveReactions(tile, events);
+            if (cells.get(key(tile))?.size === 0)
+                cells.delete(key(tile));
+            return events;
+        },
+        has: (tile, surface) => cells.get(key(tile))?.has(surface) ?? false,
+        kindsAt: (tile) => [...(cells.get(key(tile))?.keys() ?? [])],
+        remove: (tile, surface) => {
+            const cell = cells.get(key(tile));
+            if (cell === undefined)
+                return;
+            cell.delete(surface);
+            if (cell.size === 0)
+                cells.delete(key(tile));
+        },
+        clearTile: (tile) => {
+            cells.delete(key(tile));
+        },
+        clear: () => cells.clear(),
+        tick: (dt) => {
+            const events = [];
+            for (const [k, cell] of [...cells]) {
+                for (const [surface, remaining] of [...cell]) {
+                    if (remaining === null)
+                        continue;
+                    const next = remaining - dt;
+                    if (next <= 0) {
+                        cell.delete(surface);
+                        events.push({ kind: "expire", tile: parseKey(k), surface });
+                    }
+                    else {
+                        cell.set(surface, next);
+                    }
+                }
+                if (cell.size === 0)
+                    cells.delete(k);
+            }
+            return events;
+        },
+        cells: () => {
+            const out = [];
+            for (const [k, cell] of cells) {
+                out.push({
+                    tile: parseKey(k),
+                    kinds: [...cell].map(([surface, remaining]) => ({ surface, remaining })),
+                });
+            }
+            return out;
+        },
+        capture: () => {
+            const snapshot = {};
+            for (const [k, cell] of cells) {
+                const entry = {};
+                for (const [surface, remaining] of cell)
+                    entry[surface] = remaining;
+                snapshot[k] = entry;
+            }
+            return snapshot;
+        },
+        restore: (snapshot) => {
+            cells.clear();
+            for (const [k, entry] of Object.entries(snapshot)) {
+                const cell = new Map();
+                for (const [surface, remaining] of Object.entries(entry))
+                    cell.set(surface, remaining);
+                cells.set(k, cell);
+            }
+        },
+    };
+}

package/dist/tactics/tacticalGrid.d.ts

@@ -0,0 +1,68 @@
+export type Tile = readonly [number, number];
+/** Maps abstract `[col, row]` tiles onto world-space `[x, z]`, mirroring `navGrid`'s bounds+cellSize convention. */
+export interface TacticalGridWorldConfig {
+    /** World-space `[x, z]` of the min corner of tile `[0, 0]`. */
+    origin: readonly [number, number];
+    tileSize: number;
+}
+export interface TacticalGridConfig {
+    width: number;
+    height: number;
+    blocked?: readonly Tile[];
+    diagonal?: boolean;
+    world?: TacticalGridWorldConfig;
+}
+export interface ReachableOptions {
+    passThrough?: readonly string[];
+    diagonal?: boolean;
+}
+export interface ReachableTile {
+    tile: Tile;
+    cost: number;
+}
+export type PushObstacle = "wall" | "edge";
+export interface PushCollision {
+    mover: string;
+    into: string | PushObstacle;
+    at: Tile;
+}
+export interface PushMove {
+    id: string;
+    from: Tile;
+    to: Tile;
+}
+export interface PushResult {
+    moves: PushMove[];
+    collisions: PushCollision[];
+}
+export interface PushOptions {
+    distance?: number;
+    chain?: boolean;
+}
+export interface TacticalGridSnapshot {
+    blocked: string[];
+    occupants: Record<string, string>;
+}
+export interface TacticalGrid {
+    readonly width: number;
+    readonly height: number;
+    inBounds(tile: Tile): boolean;
+    isBlocked(tile: Tile): boolean;
+    setBlocked(tile: Tile, blocked: boolean): void;
+    occupantAt(tile: Tile): string | null;
+    tileOf(id: string): Tile | null;
+    place(id: string, tile: Tile): boolean;
+    remove(id: string): void;
+    move(id: string, tile: Tile): boolean;
+    neighbors(tile: Tile, diagonal?: boolean): Tile[];
+    reachable(from: Tile, budget: number, options?: ReachableOptions): ReachableTile[];
+    path(from: Tile, to: Tile, options?: ReachableOptions): Tile[] | null;
+    push(id: string, direction: Tile, options?: PushOptions): PushResult;
+    capture(): TacticalGridSnapshot;
+    restore(snapshot: TacticalGridSnapshot): void;
+    /** World `[x, z]` to the containing tile, or `null` when outside the grid. Requires `config.world`. */
+    worldToTile(x: number, z: number): Tile | null;
+    /** A tile's world-space center. Requires `config.world`. */
+    tileToWorld(tile: Tile): readonly [number, number];
+}
+export declare function createTacticalGrid(config: TacticalGridConfig): TacticalGrid;

package/dist/tactics/tacticalGrid.js

@@ -0,0 +1,261 @@
+function key(tile) {
+    return `${tile[0]},${tile[1]}`;
+}
+function parseKey(k) {
+    const [c, r] = k.split(",");
+    return [Number(c), Number(r)];
+}
+export function createTacticalGrid(config) {
+    const width = config.width;
+    const height = config.height;
+    const defaultDiagonal = config.diagonal ?? false;
+    const blocked = new Set((config.blocked ?? []).map(key));
+    const occupants = new Map();
+    const tiles = new Map();
+    const world = config.world;
+    function inBounds(tile) {
+        return tile[0] >= 0 && tile[0] < width && tile[1] >= 0 && tile[1] < height;
+    }
+    function requireWorld() {
+        if (world === undefined)
+            throw new Error("tacticalGrid: worldToTile/tileToWorld require config.world.");
+        return world;
+    }
+    function worldToTile(x, z) {
+        const { origin, tileSize } = requireWorld();
+        const tile = [Math.floor((x - origin[0]) / tileSize), Math.floor((z - origin[1]) / tileSize)];
+        return inBounds(tile) ? tile : null;
+    }
+    function tileToWorld(tile) {
+        const { origin, tileSize } = requireWorld();
+        return [origin[0] + (tile[0] + 0.5) * tileSize, origin[1] + (tile[1] + 0.5) * tileSize];
+    }
+    function isBlocked(tile) {
+        return blocked.has(key(tile));
+    }
+    function occupantAt(tile) {
+        return occupants.get(key(tile)) ?? null;
+    }
+    function tileOf(id) {
+        const t = tiles.get(id);
+        return t === undefined ? null : [t[0], t[1]];
+    }
+    function place(id, tile) {
+        if (!inBounds(tile) || isBlocked(tile))
+            return false;
+        if (occupants.has(key(tile)))
+            return false;
+        const prev = tiles.get(id);
+        if (prev !== undefined)
+            occupants.delete(key(prev));
+        occupants.set(key(tile), id);
+        tiles.set(id, [tile[0], tile[1]]);
+        return true;
+    }
+    function remove(id) {
+        const t = tiles.get(id);
+        if (t === undefined)
+            return;
+        occupants.delete(key(t));
+        tiles.delete(id);
+    }
+    function move(id, tile) {
+        if (!tiles.has(id))
+            return false;
+        if (!inBounds(tile) || isBlocked(tile))
+            return false;
+        const holder = occupants.get(key(tile));
+        if (holder !== undefined && holder !== id)
+            return false;
+        const prev = tiles.get(id);
+        occupants.delete(key(prev));
+        occupants.set(key(tile), id);
+        tiles.set(id, [tile[0], tile[1]]);
+        return true;
+    }
+    function neighbors(tile, diagonal = defaultDiagonal) {
+        const orthogonal = [
+            [tile[0] + 1, tile[1]],
+            [tile[0] - 1, tile[1]],
+            [tile[0], tile[1] + 1],
+            [tile[0], tile[1] - 1],
+        ];
+        const diagonals = [
+            [tile[0] + 1, tile[1] + 1],
+            [tile[0] + 1, tile[1] - 1],
+            [tile[0] - 1, tile[1] + 1],
+            [tile[0] - 1, tile[1] - 1],
+        ];
+        return (diagonal ? [...orthogonal, ...diagonals] : orthogonal).filter(inBounds);
+    }
+    function enterable(tile, passThrough) {
+        if (!inBounds(tile) || isBlocked(tile))
+            return false;
+        const holder = occupants.get(key(tile));
+        return holder === undefined || passThrough.has(holder);
+    }
+    function reachable(from, budget, options) {
+        const diagonal = options?.diagonal ?? defaultDiagonal;
+        const passThrough = new Set(options?.passThrough ?? []);
+        const mover = occupantAt(from);
+        if (mover !== null)
+            passThrough.add(mover);
+        const best = new Map([[key(from), 0]]);
+        const frontier = [from];
+        while (frontier.length > 0) {
+            const current = frontier.shift();
+            const cost = best.get(key(current));
+            if (cost >= budget)
+                continue;
+            for (const next of neighbors(current, diagonal)) {
+                if (!enterable(next, passThrough))
+                    continue;
+                const nextCost = cost + 1;
+                const known = best.get(key(next));
+                if (known !== undefined && known <= nextCost)
+                    continue;
+                best.set(key(next), nextCost);
+                frontier.push(next);
+            }
+        }
+        const result = [];
+        for (const [k, cost] of best) {
+            if (k === key(from))
+                continue;
+            result.push({ tile: parseKey(k), cost });
+        }
+        return result.sort((a, b) => a.cost - b.cost || a.tile[0] - b.tile[0] || a.tile[1] - b.tile[1]);
+    }
+    function path(from, to, options) {
+        if (!inBounds(from) || !inBounds(to))
+            return null;
+        const diagonal = options?.diagonal ?? defaultDiagonal;
+        const passThrough = new Set(options?.passThrough ?? []);
+        const mover = occupantAt(from);
+        if (mover !== null)
+            passThrough.add(mover);
+        if (key(from) === key(to))
+            return [[from[0], from[1]]];
+        const cameFrom = new Map();
+        const visited = new Set([key(from)]);
+        const frontier = [from];
+        while (frontier.length > 0) {
+            const current = frontier.shift();
+            for (const next of neighbors(current, diagonal)) {
+                if (visited.has(key(next)))
+                    continue;
+                const isGoal = key(next) === key(to);
+                if (!isGoal && !enterable(next, passThrough))
+                    continue;
+                if (!isGoal && isBlocked(next))
+                    continue;
+                visited.add(key(next));
+                cameFrom.set(key(next), key(current));
+                if (isGoal) {
+                    const chain = [to];
+                    let step = key(to);
+                    while (step !== key(from)) {
+                        step = cameFrom.get(step);
+                        chain.push(parseKey(step));
+                    }
+                    return chain.reverse();
+                }
+                frontier.push(next);
+            }
+        }
+        return null;
+    }
+    function push(id, direction, options) {
+        const distance = options?.distance ?? 1;
+        const chain = options?.chain ?? false;
+        const result = { moves: [], collisions: [] };
+        const origins = new Map();
+        function record(unitId) {
+            const from = origins.get(unitId);
+            const to = tileOf(unitId);
+            if (from === undefined || to === null)
+                return;
+            if (from[0] === to[0] && from[1] === to[1])
+                return;
+            const existing = result.moves.find((m) => m.id === unitId);
+            if (existing !== undefined)
+                existing.to = to;
+            else
+                result.moves.push({ id: unitId, from, to });
+        }
+        function pushUnit(unitId, steps, depth) {
+            const start = tileOf(unitId);
+            if (start === null)
+                return;
+            if (!origins.has(unitId))
+                origins.set(unitId, start);
+            let taken = 0;
+            while (taken < steps) {
+                const cur = tileOf(unitId);
+                const next = [cur[0] + direction[0], cur[1] + direction[1]];
+                if (!inBounds(next)) {
+                    result.collisions.push({ mover: unitId, into: "edge", at: cur });
+                    break;
+                }
+                if (isBlocked(next)) {
+                    result.collisions.push({ mover: unitId, into: "wall", at: cur });
+                    break;
+                }
+                const occ = occupantAt(next);
+                if (occ !== null) {
+                    result.collisions.push({ mover: unitId, into: occ, at: cur });
+                    if (!chain || depth >= width * height)
+                        break;
+                    pushUnit(occ, steps - taken, depth + 1);
+                    if (occupantAt(next) !== null)
+                        break;
+                }
+                move(unitId, next);
+                taken += 1;
+            }
+            record(unitId);
+        }
+        pushUnit(id, distance, 0);
+        return result;
+    }
+    return {
+        width,
+        height,
+        inBounds,
+        isBlocked,
+        setBlocked: (tile, value) => {
+            if (value)
+                blocked.add(key(tile));
+            else
+                blocked.delete(key(tile));
+        },
+        occupantAt,
+        tileOf,
+        place,
+        remove,
+        move,
+        neighbors,
+        reachable,
+        path,
+        push,
+        worldToTile,
+        tileToWorld,
+        capture: () => {
+            const occ = {};
+            for (const [k, unitId] of occupants)
+                occ[k] = unitId;
+            return { blocked: [...blocked], occupants: occ };
+        },
+        restore: (snapshot) => {
+            blocked.clear();
+            for (const k of snapshot.blocked)
+                blocked.add(k);
+            occupants.clear();
+            tiles.clear();
+            for (const [k, unitId] of Object.entries(snapshot.occupants)) {
+                occupants.set(k, unitId);
+                tiles.set(unitId, parseKey(k));
+            }
+        },
+    };
+}

package/dist/time/beatClock.d.ts

@@ -0,0 +1,40 @@
+export interface BeatClockConfig {
+    bpm: number;
+    /** Beats per bar/measure, for bar-relative UI (rhythm-game combo windows). Default 4. */
+    beatsPerBar?: number;
+}
+export interface BeatSnapshot {
+    /** Fractional beat count since the clock started. */
+    beat: number;
+    beatIndex: number;
+    bar: number;
+    beatInBar: number;
+    /** 0..1 fractional position within the current beat. */
+    phase: number;
+}
+export interface BeatClock {
+    /** Advance by a game-time delta (already scaled by ctx.time — never wall-clock). Returns the resulting snapshot and fires onBeat once per newly crossed integer beat. */
+    advance(gameDt: number): BeatSnapshot;
+    snapshot(): BeatSnapshot;
+    /** Elapsed game-seconds since the clock started. */
+    now(): number;
+    beatDurationSec(): number;
+    bpm(): number;
+}
+export declare function createBeatClock(config: BeatClockConfig, onBeat?: (beatIndex: number) => void): BeatClock;
+/** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
+export declare function nextBeatTime(nowSec: number, beatDurationSec: number, epsilon?: number): number;
+export interface BufferedAction<T> {
+    action: T;
+    bufferedAtSec: number;
+    fireAtSec: number;
+}
+export interface BeatInputBuffer<T> {
+    /** Buffer an action; it quantizes to fire on the next beat tick (or immediately if `nowSec` is already on a beat). Returns the resolved fire time. */
+    buffer(action: T, nowSec: number): number;
+    /** Drain and return every action whose fire time has arrived, in the order they were buffered. */
+    advance(nowSec: number): T[];
+    pendingCount(): number;
+    clear(): void;
+}
+export declare function createBeatInputBuffer<T>(beatDurationSec: number): BeatInputBuffer<T>;

package/dist/time/beatClock.js

@@ -0,0 +1,73 @@
+const MAX_BEAT_FIRES = 10_000;
+export function createBeatClock(config, onBeat) {
+    const beatsPerBar = config.beatsPerBar !== undefined && config.beatsPerBar > 0 ? config.beatsPerBar : 4;
+    const beatDurationSec = 60 / config.bpm;
+    let elapsedSec = 0;
+    let lastBeatIndex = -1;
+    function toSnapshot() {
+        const beat = elapsedSec / beatDurationSec;
+        const beatIndex = Math.floor(beat);
+        return {
+            beat,
+            beatIndex,
+            bar: Math.floor(beatIndex / beatsPerBar),
+            beatInBar: ((beatIndex % beatsPerBar) + beatsPerBar) % beatsPerBar,
+            phase: beat - beatIndex,
+        };
+    }
+    function advance(gameDt) {
+        if (gameDt > 0)
+            elapsedSec += gameDt;
+        const snapshot = toSnapshot();
+        let fires = 0;
+        while (lastBeatIndex < snapshot.beatIndex && fires < MAX_BEAT_FIRES) {
+            lastBeatIndex += 1;
+            onBeat?.(lastBeatIndex);
+            fires += 1;
+        }
+        return snapshot;
+    }
+    return {
+        advance,
+        snapshot: toSnapshot,
+        now: () => elapsedSec,
+        beatDurationSec: () => beatDurationSec,
+        bpm: () => config.bpm,
+    };
+}
+const QUANTIZE_EPSILON = 1e-6;
+/** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
+export function nextBeatTime(nowSec, beatDurationSec, epsilon = QUANTIZE_EPSILON) {
+    const beatIndex = nowSec / beatDurationSec;
+    const rounded = Math.round(beatIndex);
+    if (Math.abs(beatIndex - rounded) <= epsilon)
+        return rounded * beatDurationSec;
+    return Math.ceil(beatIndex) * beatDurationSec;
+}
+export function createBeatInputBuffer(beatDurationSec) {
+    const pending = [];
+    return {
+        buffer(action, nowSec) {
+            const fireAtSec = nextBeatTime(nowSec, beatDurationSec);
+            pending.push({ action, bufferedAtSec: nowSec, fireAtSec });
+            return fireAtSec;
+        },
+        advance(nowSec) {
+            const due = [];
+            const remaining = [];
+            for (const entry of pending) {
+                if (entry.fireAtSec <= nowSec + QUANTIZE_EPSILON)
+                    due.push(entry.action);
+                else
+                    remaining.push(entry);
+            }
+            pending.length = 0;
+            pending.push(...remaining);
+            return due;
+        },
+        pendingCount: () => pending.length,
+        clear: () => {
+            pending.length = 0;
+        },
+    };
+}

package/dist/time/simClock.d.ts

@@ -9,6 +9,10 @@ export interface TimeConfig {
     start?: number;
     /** Boot with the clock paused. Default false. */
     startPaused?: boolean;
+    /** In-world days per year, driving `calendar().year`/`dayOfYear`/`yearFraction`. Default 365. */
+    daysPerYear?: number;
+    /** Named season segments spanning the year in equal shares; when set, `calendar().season` names the current one. */
+    seasons?: readonly string[];
 }
 export interface CalendarTime {
     /** Total game-seconds since the world started. */
@@ -20,14 +24,24 @@ export interface CalendarTime {
     second: number;
     /** Progress through the current day, 0..1. */
     dayFraction: number;
+    /** 0-based year index, using `daysPerYear` (default 365). */
+    year: number;
+    /** 0-based day index within the current year. */
+    dayOfYear: number;
+    /** Progress through the current year, 0..1. */
+    yearFraction: number;
+    /** Current season name, present only when `TimeConfig.seasons` is configured. */
+    season?: string;
 }
 export interface ClockSnapshot {
     now: number;
     paused: boolean;
-    /** Effective multiplier applied to real time — 0 while paused. */
+    /** Speed-control multiplier — 0 while paused. The full game-time rate is `speed × timescale × scale`. */
     speed: number;
     /** The non-zero multiplier `play()` resumes to. */
     playSpeed: number;
+    /** Global slow-motion/fast-forward multiplier; 1 unless `setTimescale` was called. */
+    timescale: number;
     scale: number;
     speeds: readonly number[];
     calendar: CalendarTime;
@@ -47,6 +61,16 @@ export interface SimClock {
     setSpeed(multiplier: number): void;
     /** Step to the next configured speed (wraps); always unpauses. */
     cycleSpeed(): void;
+    /** Current global timescale multiplier; 1 by default. */
+    timescale(): number;
+    /**
+     * Global slow-motion/fast-forward multiplier composed with the speed control —
+     * `advance` returns `realDt × scale × speed × timescale`. `0` freezes game time
+     * without flipping pause state (`0.08` = bullet time, `2` = fast-forward); negative
+     * or non-finite values clamp to 0. Timescale is host-authoritative: in multiplayer
+     * it belongs to the host simulation, never to an individual client.
+     */
+    setTimescale(multiplier: number): void;
     /** Run `callback` once, `seconds` of game-time from now. Returns a cancel handle. */
     after(seconds: number, callback: () => void): () => void;
     /** Run `callback` every `seconds` of game-time. Returns a cancel handle. */