@jgengine/core 0.5.0 → 0.7.0

package/dist/ai/jobBoard.js

@@ -0,0 +1,155 @@
+const DEFAULT_ARRIVE_RADIUS = 0.75;
+function idleWorker() {
+    return { jobId: null, phase: "idle", worked: 0, cycles: 0 };
+}
+export function createJobBoard() {
+    const jobs = new Map();
+    const workers = new Map();
+    let counter = 1;
+    function workerState(workerId) {
+        let state = workers.get(workerId);
+        if (state === undefined) {
+            state = idleWorker();
+            workers.set(workerId, state);
+        }
+        return state;
+    }
+    function begin(workerId, job) {
+        const state = workerState(workerId);
+        job.worker = workerId;
+        state.jobId = job.id;
+        state.phase = "travelling";
+        state.worked = 0;
+        state.cycles = 0;
+    }
+    function detach(workerId, requeue) {
+        const state = workers.get(workerId);
+        if (state === undefined || state.jobId === null)
+            return;
+        const job = jobs.get(state.jobId);
+        if (job !== undefined && job.worker === workerId)
+            job.worker = requeue ? null : job.worker;
+        state.jobId = null;
+        state.phase = "idle";
+        state.worked = 0;
+    }
+    return {
+        post(job) {
+            const id = job.id ?? `job-${counter++}`;
+            jobs.set(id, {
+                id,
+                station: job.station,
+                work: job.work,
+                priority: job.priority ?? 0,
+                arriveRadius: job.arriveRadius ?? DEFAULT_ARRIVE_RADIUS,
+                repeat: job.repeat ?? false,
+                worker: null,
+            });
+            return id;
+        },
+        cancel(jobId) {
+            const job = jobs.get(jobId);
+            if (job === undefined)
+                return false;
+            if (job.worker !== null)
+                detach(job.worker, false);
+            jobs.delete(jobId);
+            return true;
+        },
+        assign(workerId, jobId) {
+            const job = jobs.get(jobId);
+            if (job === undefined)
+                return false;
+            if (job.worker !== null && job.worker !== workerId)
+                detach(job.worker, true);
+            detach(workerId, true);
+            begin(workerId, job);
+            return true;
+        },
+        claim(workerId) {
+            const existing = workerState(workerId);
+            if (existing.jobId !== null && jobs.has(existing.jobId))
+                return existing.jobId;
+            let best = null;
+            for (const job of jobs.values()) {
+                if (job.worker !== null)
+                    continue;
+                if (best === null || job.priority > best.priority)
+                    best = job;
+            }
+            if (best === null) {
+                existing.phase = "idle";
+                return null;
+            }
+            begin(workerId, best);
+            return best.id;
+        },
+        release(workerId) {
+            detach(workerId, true);
+        },
+        advance(workerId, dt, ctx) {
+            const state = workerState(workerId);
+            if (state.jobId === null) {
+                state.phase = "idle";
+                return null;
+            }
+            const job = jobs.get(state.jobId);
+            if (job === undefined) {
+                state.jobId = null;
+                state.phase = "idle";
+                state.worked = 0;
+                return null;
+            }
+            if (state.phase === "travelling" || state.phase === "idle") {
+                state.phase = ctx.distanceToStation <= job.arriveRadius ? "working" : "travelling";
+            }
+            if (state.phase !== "working" || dt <= 0)
+                return null;
+            if (ctx.distanceToStation > job.arriveRadius) {
+                state.phase = "travelling";
+                return null;
+            }
+            state.worked += dt;
+            if (state.worked < job.work)
+                return null;
+            state.cycles += 1;
+            const report = { jobId: job.id, workerId, cycle: state.cycles };
+            if (job.repeat) {
+                state.worked -= job.work;
+                state.phase = "working";
+            }
+            else {
+                job.worker = null;
+                jobs.delete(job.id);
+                state.jobId = null;
+                state.phase = "done";
+                state.worked = 0;
+            }
+            return report;
+        },
+        worker(workerId) {
+            return { ...workerState(workerId) };
+        },
+        station(workerId) {
+            const state = workers.get(workerId);
+            if (state === undefined || state.jobId === null)
+                return null;
+            return jobs.get(state.jobId)?.station ?? null;
+        },
+        jobOf(workerId) {
+            return workers.get(workerId)?.jobId ?? null;
+        },
+        get(jobId) {
+            return jobs.get(jobId) ?? null;
+        },
+        queued() {
+            return [...jobs.values()].filter((job) => job.worker === null);
+        },
+        active() {
+            return [...jobs.values()].filter((job) => job.worker !== null);
+        },
+        list() {
+            return [...jobs.values()];
+        },
+    };
+}

package/dist/ai/spawnDirector.d.ts

@@ -0,0 +1,56 @@
+import type { NavPoint } from "../nav/navGrid.js";
+export interface SpawnEntry {
+    id: string;
+    cost: number;
+    weight?: number;
+    minWave?: number;
+}
+export interface WaveManifest {
+    budget: number;
+    entries: readonly SpawnEntry[];
+    duration?: number;
+    budgetPerSecond?: number;
+}
+export interface SpawnDirectorConfig {
+    waves: readonly WaveManifest[];
+    maxAlive?: number;
+    escalationPerSecond?: number;
+    alertBudgetPerSecond?: number;
+    alertDecayPerSecond?: number;
+    playerBudgetPerSecond?: number;
+    maxSpawnsPerTick?: number;
+    loop?: boolean;
+    seed?: number;
+}
+export interface SpawnDirectorState {
+    wave: number;
+    elapsed: number;
+    waveElapsed: number;
+    budget: number;
+    alert: number;
+    spawnedThisWave: number;
+    spawnedTotal: number;
+    rng: number;
+    done: boolean;
+}
+export interface DirectorContext {
+    alive: number;
+    players?: number;
+}
+export interface SpawnRequest {
+    entryId: string;
+    cost: number;
+    wave: number;
+}
+export interface DirectorStep {
+    state: SpawnDirectorState;
+    spawns: SpawnRequest[];
+}
+export declare function createSpawnDirectorState(config: SpawnDirectorConfig): SpawnDirectorState;
+export declare function raiseAlert(state: SpawnDirectorState, amount: number): SpawnDirectorState;
+export declare function advanceWave(config: SpawnDirectorConfig, state: SpawnDirectorState): SpawnDirectorState;
+export declare function advanceSpawnDirector(config: SpawnDirectorConfig, state: SpawnDirectorState, dt: number, ctx: DirectorContext): DirectorStep;
+export declare function pickSpawnPoint(points: readonly NavPoint[], players: readonly NavPoint[], options: {
+    roll: number;
+    bias?: number;
+}): NavPoint | null;

package/dist/ai/spawnDirector.js

@@ -0,0 +1,150 @@
+const DEFAULT_MAX_SPAWNS_PER_TICK = 64;
+const DEFAULT_ALERT_DECAY = 0.1;
+function nextRandom(seed) {
+    const next = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(next ^ (next >>> 15), 1 | next);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    return [value, next];
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+export function createSpawnDirectorState(config) {
+    const first = config.waves[0];
+    return {
+        wave: 0,
+        elapsed: 0,
+        waveElapsed: 0,
+        budget: first?.budget ?? 0,
+        alert: 0,
+        spawnedThisWave: 0,
+        spawnedTotal: 0,
+        rng: (config.seed ?? 1) | 0,
+        done: config.waves.length === 0,
+    };
+}
+export function raiseAlert(state, amount) {
+    return { ...state, alert: clamp01(state.alert + amount) };
+}
+export function advanceWave(config, state) {
+    const loop = config.loop ?? false;
+    const lastIndex = config.waves.length - 1;
+    if (state.wave >= lastIndex && !loop)
+        return { ...state, done: true };
+    const nextWave = state.wave >= lastIndex ? 0 : state.wave + 1;
+    const manifest = config.waves[nextWave];
+    return {
+        ...state,
+        wave: nextWave,
+        waveElapsed: 0,
+        spawnedThisWave: 0,
+        budget: state.budget + manifest.budget,
+        done: false,
+    };
+}
+function pickEntry(entries, wave, budget, rng) {
+    let total = 0;
+    const affordable = [];
+    for (const entry of entries) {
+        if (entry.cost > budget)
+            continue;
+        if ((entry.minWave ?? 0) > wave)
+            continue;
+        affordable.push(entry);
+        total += entry.weight ?? 1;
+    }
+    if (affordable.length === 0 || total <= 0)
+        return null;
+    const [roll, nextRng] = nextRandom(rng);
+    let cursor = roll * total;
+    for (const entry of affordable) {
+        cursor -= entry.weight ?? 1;
+        if (cursor <= 0)
+            return { entry, rng: nextRng };
+    }
+    return { entry: affordable[affordable.length - 1], rng: nextRng };
+}
+export function advanceSpawnDirector(config, state, dt, ctx) {
+    if (state.done || dt <= 0)
+        return { state, spawns: [] };
+    const maxAlive = config.maxAlive ?? Number.POSITIVE_INFINITY;
+    const maxSpawns = config.maxSpawnsPerTick ?? DEFAULT_MAX_SPAWNS_PER_TICK;
+    const alertDecay = config.alertDecayPerSecond ?? DEFAULT_ALERT_DECAY;
+    const players = ctx.players ?? 0;
+    let wave = state.wave;
+    let elapsed = state.elapsed + dt;
+    let waveElapsed = state.waveElapsed + dt;
+    let budget = state.budget;
+    let spawnedThisWave = state.spawnedThisWave;
+    let done = state.done;
+    const alert = Math.max(0, state.alert - alertDecay * dt);
+    const trickle = config.waves[wave]?.budgetPerSecond ?? 0;
+    const escalation = (config.escalationPerSecond ?? 0) * elapsed;
+    const alertBonus = (config.alertBudgetPerSecond ?? 0) * alert;
+    const playerBonus = (config.playerBudgetPerSecond ?? 0) * players;
+    budget += (trickle + escalation + alertBonus + playerBonus) * dt;
+    const lastIndex = config.waves.length - 1;
+    const loop = config.loop ?? false;
+    let guard = config.waves.length + 1;
+    while (guard > 0) {
+        guard -= 1;
+        const manifest = config.waves[wave];
+        if (manifest?.duration === undefined || waveElapsed < manifest.duration)
+            break;
+        if (wave >= lastIndex && !loop) {
+            done = true;
+            break;
+        }
+        waveElapsed -= manifest.duration;
+        wave = wave >= lastIndex ? 0 : wave + 1;
+        spawnedThisWave = 0;
+        budget += config.waves[wave].budget;
+    }
+    const spawns = [];
+    let rng = state.rng;
+    let spawnedTotal = state.spawnedTotal;
+    let alive = ctx.alive;
+    const entries = config.waves[wave]?.entries ?? [];
+    while (spawns.length < maxSpawns && alive < maxAlive) {
+        const picked = pickEntry(entries, wave, budget, rng);
+        if (picked === null)
+            break;
+        rng = picked.rng;
+        budget -= picked.entry.cost;
+        spawns.push({ entryId: picked.entry.id, cost: picked.entry.cost, wave });
+        spawnedThisWave += 1;
+        spawnedTotal += 1;
+        alive += 1;
+    }
+    return {
+        state: { wave, elapsed, waveElapsed, budget, alert, spawnedThisWave, spawnedTotal, rng, done },
+        spawns,
+    };
+}
+export function pickSpawnPoint(points, players, options) {
+    if (points.length === 0)
+        return null;
+    const bias = options.bias ?? 1;
+    const weights = [];
+    let total = 0;
+    for (const point of points) {
+        let nearest = Number.POSITIVE_INFINITY;
+        for (const player of players) {
+            const d = Math.hypot(point[0] - player[0], point[1] - player[1]);
+            if (d < nearest)
+                nearest = d;
+        }
+        const distance = nearest === Number.POSITIVE_INFINITY ? 0 : nearest;
+        const weight = Math.max(1e-6, (1 + distance) ** -bias);
+        weights.push(weight);
+        total += weight;
+    }
+    let cursor = clamp01(options.roll) * total;
+    for (let i = 0; i < points.length; i += 1) {
+        cursor -= weights[i];
+        if (cursor <= 0)
+            return points[i];
+    }
+    return points[points.length - 1];
+}

package/dist/ai/threat.d.ts

@@ -0,0 +1,25 @@
+export interface ThreatTableConfig {
+    decayPerSecond?: number;
+    max?: number;
+    forgetBelow?: number;
+}
+export interface ThreatEntry {
+    sourceId: string;
+    threat: number;
+}
+export interface HighestThreatOptions {
+    current?: string | null;
+    stickiness?: number;
+}
+export interface ThreatTable {
+    add(sourceId: string, amount: number): number;
+    set(sourceId: string, amount: number): void;
+    threatOf(sourceId: string): number;
+    decay(dt: number): void;
+    highest(options?: HighestThreatOptions): string | null;
+    ranked(): ThreatEntry[];
+    remove(sourceId: string): void;
+    clear(): void;
+    size(): number;
+}
+export declare function createThreatTable(config?: ThreatTableConfig): ThreatTable;

package/dist/ai/threat.js

@@ -0,0 +1,67 @@
+const DEFAULT_FORGET_BELOW = 0;
+export function createThreatTable(config = {}) {
+    const decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
+    const max = config.max ?? Number.POSITIVE_INFINITY;
+    const forgetBelow = config.forgetBelow ?? DEFAULT_FORGET_BELOW;
+    const table = new Map();
+    function store(sourceId, value) {
+        const clamped = Math.min(max, value);
+        if (clamped <= forgetBelow) {
+            table.delete(sourceId);
+            return 0;
+        }
+        table.set(sourceId, clamped);
+        return clamped;
+    }
+    return {
+        add(sourceId, amount) {
+            return store(sourceId, (table.get(sourceId) ?? 0) + amount);
+        },
+        set(sourceId, amount) {
+            store(sourceId, amount);
+        },
+        threatOf(sourceId) {
+            return table.get(sourceId) ?? 0;
+        },
+        decay(dt) {
+            if (decayPerSecond <= 0 || dt <= 0)
+                return;
+            const loss = decayPerSecond * dt;
+            for (const [sourceId, value] of [...table])
+                store(sourceId, value - loss);
+        },
+        highest(options = {}) {
+            let bestId = null;
+            let bestThreat = Number.NEGATIVE_INFINITY;
+            for (const [sourceId, value] of table) {
+                if (value > bestThreat) {
+                    bestThreat = value;
+                    bestId = sourceId;
+                }
+            }
+            if (bestId === null)
+                return null;
+            const current = options.current ?? null;
+            if (current !== null && current !== bestId && table.has(current)) {
+                const stickiness = options.stickiness ?? 1;
+                if (bestThreat < table.get(current) * stickiness)
+                    return current;
+            }
+            return bestId;
+        },
+        ranked() {
+            return [...table]
+                .map(([sourceId, threat]) => ({ sourceId, threat }))
+                .sort((a, b) => b.threat - a.threat || a.sourceId.localeCompare(b.sourceId));
+        },
+        remove(sourceId) {
+            table.delete(sourceId);
+        },
+        clear() {
+            table.clear();
+        },
+        size() {
+            return table.size;
+        },
+    };
+}

package/dist/audio/audioFalloff.d.ts

@@ -0,0 +1,38 @@
+export type AudioBusId = string;
+export type FalloffCurve = "linear" | "inverse" | "none";
+export interface AudioFalloffConfig {
+    /** Distance (world units) at/under which gain is 1. Default 1. */
+    minDistance?: number;
+    /** Distance at/beyond which gain is 0. Default 24. */
+    maxDistance?: number;
+    /** "linear" ramps 1→0 between min/max; "inverse" is an inverse-square-style rolloff clamped to the same range; "none" is always 1 (no distance attenuation). Default "linear". */
+    curve?: FalloffCurve;
+}
+export interface AudioBusDef {
+    id: AudioBusId;
+    /** Bus volume multiplier, 0..1+. Default 1. */
+    gain?: number;
+}
+export interface SoundDef {
+    id: string;
+    /** Playable source — a URL/data URI the shell's Web Audio glue fetches and decodes. */
+    url: string;
+    bus: AudioBusId;
+    /** Base gain before bus/falloff multipliers. Default 1. */
+    gain?: number;
+    loop?: boolean;
+    /** Positional emitters attenuate by distance from the listener; non-positional sounds (UI, music) play at flat gain. Default true. */
+    positional?: boolean;
+    falloff?: AudioFalloffConfig;
+}
+export declare function computeFalloffGain(distance: number, config?: AudioFalloffConfig): number;
+export declare function resolveEmitterGain(distance: number, sound: Pick<SoundDef, "gain" | "positional" | "falloff">, busGain: number): number;
+export declare function distance3(a: {
+    x: number;
+    y: number;
+    z: number;
+}, b: {
+    x: number;
+    y: number;
+    z: number;
+}): number;

package/dist/audio/audioFalloff.js

@@ -0,0 +1,32 @@
+const DEFAULT_MIN_DISTANCE = 1;
+const DEFAULT_MAX_DISTANCE = 24;
+export function computeFalloffGain(distance, config = {}) {
+    const curve = config.curve ?? "linear";
+    if (curve === "none")
+        return 1;
+    const min = Math.max(0, config.minDistance ?? DEFAULT_MIN_DISTANCE);
+    const max = Math.max(min + Number.EPSILON, config.maxDistance ?? DEFAULT_MAX_DISTANCE);
+    const clamped = Math.max(0, distance);
+    if (clamped <= min)
+        return 1;
+    if (clamped >= max)
+        return 0;
+    const t = (clamped - min) / (max - min);
+    if (curve === "inverse") {
+        const inv = min / clamped;
+        const invAtMax = min / max;
+        return Math.min(1, Math.max(0, (inv - invAtMax) / (1 - invAtMax)));
+    }
+    return 1 - t;
+}
+export function resolveEmitterGain(distance, sound, busGain) {
+    const base = sound.gain ?? 1;
+    const spatial = sound.positional === false ? 1 : computeFalloffGain(distance, sound.falloff);
+    return base * spatial * busGain;
+}
+export function distance3(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    const dz = a.z - b.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}

package/dist/board/laneBoard.d.ts

@@ -0,0 +1,63 @@
+export type Side = string;
+export interface LaneRuleInput<C> {
+    lane: number;
+    side: Side;
+    cards: readonly C[];
+    subtotal: number;
+}
+export interface LaneRule<C> {
+    id: string;
+    apply: (input: LaneRuleInput<C>) => number;
+}
+export interface LaneBoardConfig<C> {
+    laneCount: number;
+    sides: readonly Side[];
+    power: (card: C) => number;
+    laneRules?: readonly (LaneRule<C> | null | undefined)[];
+}
+export interface LaneCells<C> {
+    readonly [side: Side]: readonly C[];
+}
+export interface LaneBoardState<C> {
+    readonly lanes: readonly LaneCells<C>[];
+}
+export interface LaneAggregate {
+    lane: number;
+    side: Side;
+    subtotal: number;
+    total: number;
+    count: number;
+}
+export interface LaneOutcome {
+    lane: number;
+    totals: Readonly<Record<Side, number>>;
+    winner: Side | null;
+}
+export type LaneRejection = "invalid-lane" | "invalid-side";
+export interface LanePlaceResult<C> {
+    status: "ok";
+    state: LaneBoardState<C>;
+}
+export interface LanePlaceRejected {
+    status: "rejected";
+    reason: LaneRejection;
+}
+export type LaneResult<C> = LanePlaceResult<C> | LanePlaceRejected;
+export declare function createLaneBoardState<C>(config: LaneBoardConfig<C>): LaneBoardState<C>;
+export declare function placeCard<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side, card: C): LaneResult<C>;
+export declare function removeCard<C>(state: LaneBoardState<C>, lane: number, side: Side, predicate: (card: C, index: number) => boolean): LaneResult<C>;
+export declare function laneAggregate<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side): LaneAggregate;
+export declare function laneOutcome<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number): LaneOutcome;
+export declare function boardTotals<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>;
+export declare function lanesWon<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>;
+export interface LaneBoard<C> {
+    state(): LaneBoardState<C>;
+    place(lane: number, side: Side, card: C): LaneResult<C>;
+    remove(lane: number, side: Side, predicate: (card: C, index: number) => boolean): LaneResult<C>;
+    aggregate(lane: number, side: Side): LaneAggregate;
+    outcome(lane: number): LaneOutcome;
+    totals(): Readonly<Record<Side, number>>;
+    lanesWon(): Readonly<Record<Side, number>>;
+    reset(next?: LaneBoardState<C>): void;
+}
+export declare function createLaneBoard<C>(config: LaneBoardConfig<C>): LaneBoard<C>;