@jgengine/core 0.8.0 → 0.10.0

package/dist/ai/spawnDirector.js

@@ -80,7 +80,7 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
     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 escalation = config.escalationPerSecond ?? 0;
     const alertBonus = (config.alertBudgetPerSecond ?? 0) * alert;
     const playerBonus = (config.playerBudgetPerSecond ?? 0) * players;
     budget += (trickle + escalation + alertBonus + playerBonus) * dt;
@@ -118,7 +118,14 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         if (spawnPoints !== undefined && spawnPoints.length > 0) {
             const [roll, nextRng] = nextRandom(rng);
             rng = nextRng;
-            const point = pickSpawnPoint(spawnPoints, playerPositions, { roll, bias: config.spawnPointBias });
+            const bias = config.spawnPointBias ?? 1;
+            const point = pickSpawnPoint({
+                candidates: spawnPoints,
+                avoid: playerPositions,
+                random: () => roll,
+                distanceBias: bias < 0 ? "far" : bias > 0 ? "near" : "none",
+                biasStrength: Math.abs(bias),
+            });
             if (point !== null) {
                 spawn.point = point;
                 spawn.laneId = spawnPoints.indexOf(point);
@@ -134,29 +141,46 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         spawns,
     };
 }
-export function pickSpawnPoint(points, players, options) {
-    if (points.length === 0)
+export function pickSpawnPoint(optionsOrPoints, legacyPlayers = [], legacyOptions = { roll: 0 }) {
+    let options;
+    if (Array.isArray(optionsOrPoints)) {
+        const legacyBias = legacyOptions.bias ?? 1;
+        options = {
+            candidates: optionsOrPoints,
+            avoid: legacyPlayers,
+            random: () => legacyOptions.roll,
+            distanceBias: legacyBias < 0 ? "far" : legacyBias > 0 ? "near" : "none",
+            biasStrength: Math.abs(legacyBias),
+        };
+    }
+    else {
+        options = optionsOrPoints;
+    }
+    const { candidates, avoid = [], random, distanceBias = "near", biasStrength = 1 } = options;
+    if (candidates.length === 0)
         return null;
-    const bias = options.bias ?? 1;
+    if (distanceBias === "none" || avoid.length === 0 || biasStrength === 0) {
+        return candidates[Math.min(candidates.length - 1, Math.floor(clamp01(random()) * candidates.length))];
+    }
+    const exponent = distanceBias === "far" ? biasStrength : -biasStrength;
     const weights = [];
     let total = 0;
-    for (const point of points) {
+    for (const point of candidates) {
         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;
+        for (const avoidedPoint of avoid) {
+            const distance = Math.hypot(point[0] - avoidedPoint[0], point[1] - avoidedPoint[1]);
+            if (distance < nearest)
+                nearest = distance;
         }
-        const distance = nearest === Number.POSITIVE_INFINITY ? 0 : nearest;
-        const weight = Math.max(1e-6, (1 + distance) ** -bias);
+        const weight = Math.max(1e-6, (1 + nearest) ** exponent);
         weights.push(weight);
         total += weight;
     }
-    let cursor = clamp01(options.roll) * total;
-    for (let i = 0; i < points.length; i += 1) {
-        cursor -= weights[i];
+    let cursor = clamp01(random()) * total;
+    for (let index = 0; index < candidates.length; index += 1) {
+        cursor -= weights[index];
         if (cursor <= 0)
-            return points[i];
+            return candidates[index];
     }
-    return points[points.length - 1];
+    return candidates[candidates.length - 1];
 }

package/dist/ai/spawnPoint.d.ts

@@ -0,0 +1,5 @@
+import type { NavPoint } from "../nav/navGrid.js";
+import { type SpawnPointDistanceBias, type SpawnPointSelectionOptions } from "./spawnDirector.js";
+export type { SpawnPointDistanceBias, SpawnPointSelectionOptions };
+/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+export declare function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;

package/dist/ai/spawnPoint.js

@@ -0,0 +1,5 @@
+import { pickSpawnPoint, } from "./spawnDirector.js";
+/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+export function selectSpawnPoint(options) {
+    return pickSpawnPoint(options);
+}

package/dist/ai/threat.d.ts

@@ -18,6 +18,8 @@ export interface ThreatTable {
     decay(dt: number): void;
     highest(options?: HighestThreatOptions): string | null;
     ranked(): ThreatEntry[];
+    taunt(sourceId: string, durationSeconds: number): void;
+    forcedTarget(): string | null;
     remove(sourceId: string): void;
     clear(): void;
     size(): number;

package/dist/ai/threat.js

@@ -4,6 +4,8 @@ export function createThreatTable(config = {}) {
     const max = config.max ?? Number.POSITIVE_INFINITY;
     const forgetBelow = config.forgetBelow ?? DEFAULT_FORGET_BELOW;
     const table = new Map();
+    let forcedSource = null;
+    let forcedRemaining = 0;
     function store(sourceId, value) {
         const clamped = Math.min(max, value);
         if (clamped <= forgetBelow) {
@@ -13,6 +15,16 @@ export function createThreatTable(config = {}) {
         table.set(sourceId, clamped);
         return clamped;
     }
+    function topThreat() {
+        let best = 0;
+        for (const value of table.values())
+            if (value > best)
+                best = value;
+        return best;
+    }
+    function forcedTarget() {
+        return forcedRemaining > 0 ? forcedSource : null;
+    }
     return {
         add(sourceId, amount) {
             return store(sourceId, (table.get(sourceId) ?? 0) + amount);
@@ -24,6 +36,13 @@ export function createThreatTable(config = {}) {
             return table.get(sourceId) ?? 0;
         },
         decay(dt) {
+            if (dt > 0 && forcedRemaining > 0) {
+                forcedRemaining -= dt;
+                if (forcedRemaining <= 0) {
+                    forcedRemaining = 0;
+                    forcedSource = null;
+                }
+            }
             if (decayPerSecond <= 0 || dt <= 0)
                 return;
             const loss = decayPerSecond * dt;
@@ -31,6 +50,9 @@ export function createThreatTable(config = {}) {
                 store(sourceId, value - loss);
         },
         highest(options = {}) {
+            const forced = forcedTarget();
+            if (forced !== null)
+                return forced;
             let bestId = null;
             let bestThreat = Number.NEGATIVE_INFINITY;
             for (const [sourceId, value] of table) {
@@ -54,11 +76,23 @@ export function createThreatTable(config = {}) {
                 .map(([sourceId, threat]) => ({ sourceId, threat }))
                 .sort((a, b) => b.threat - a.threat || a.sourceId.localeCompare(b.sourceId));
         },
+        taunt(sourceId, durationSeconds) {
+            store(sourceId, Math.max(table.get(sourceId) ?? 0, topThreat()));
+            forcedSource = sourceId;
+            forcedRemaining = Math.max(0, durationSeconds);
+        },
+        forcedTarget,
         remove(sourceId) {
             table.delete(sourceId);
+            if (forcedSource === sourceId) {
+                forcedSource = null;
+                forcedRemaining = 0;
+            }
         },
         clear() {
             table.clear();
+            forcedSource = null;
+            forcedRemaining = 0;
         },
         size() {
             return table.size;

package/dist/audio/audioFalloff.d.ts

@@ -1,3 +1,4 @@
+import type { SynthPatch } from "./synth.js";
 export type AudioBusId = string;
 export type FalloffCurve = "linear" | "inverse" | "none";
 export interface AudioFalloffConfig {
@@ -15,8 +16,10 @@ export interface AudioBusDef {
 }
 export interface SoundDef {
     id: string;
-    /** Playable source — a URL/data URI the shell's Web Audio glue fetches and decodes. */
-    url: string;
+    /** Sample source — a URL/data URI the shell's Web Audio glue fetches and decodes. Provide exactly one of `url` or `synth`. */
+    url?: string;
+    /** Procedural source — a pure synth patch the shell realises on Web Audio, no file fetch. Provide exactly one of `url` or `synth`. */
+    synth?: SynthPatch;
     bus: AudioBusId;
     /** Base gain before bus/falloff multipliers. Default 1. */
     gain?: number;

package/dist/audio/music.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Named synthesised instrument. Each maps to a voice in the shell's instrument
+ * library (`@jgengine/shell/audio/musicVoices`); an unknown name falls back to a
+ * plain sine voice so a theme is never silent.
+ */
+export type MusicInstrument = "strings" | "flute" | "harp" | "horn" | "choir" | "bell" | "timpani" | "bass" | "stacc" | "pad" | "lute" | "dulcimer" | "frameDrum" | "warDrum" | "reed" | "pipe" | "squareLead" | "woodBlock" | "tinyBell" | "piano" | "shaker" | "brassStab" | "cymSwell" | "oboe";
+/** One scheduled note in a theme, positioned on the loop's quarter-note grid. */
+export interface NoteEvent {
+    /** Quarter-note position within the loop (0-based). */
+    beat: number;
+    /** MIDI note number (60 = middle C). */
+    midi: number;
+    /** Sounding length in quarter-note beats. */
+    dur: number;
+    /** Velocity 0..1. */
+    vel: number;
+    /** Which instrument voice plays it. */
+    inst: MusicInstrument;
+}
+/**
+ * A through-composed, looping music track. `events` need not be sorted; the
+ * director schedules them ahead against a fixed anchor so loops are seamless.
+ */
+export interface MusicTheme {
+    id: string;
+    /** Tempo in beats (quarter notes) per minute. */
+    bpm: number;
+    /** Loop length in 4/4 bars; the loop is `bars * 4` beats long. */
+    bars: number;
+    events: readonly NoteEvent[];
+    /**
+     * Per-theme loudness normalisation multiplied into the crossfade target, so
+     * dense and sparse themes sit at the same perceived level. Default 1.
+     */
+    trim?: number;
+}
+/** A resolved note occurrence: the source note plus its absolute onset in seconds. */
+export interface ScheduledNote {
+    event: NoteEvent;
+    /** Absolute onset in seconds, on the timeline of the `anchorSec`/window args. */
+    when: number;
+}
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export declare function mtof(midi: number): number;
+/** Loop length of a theme in seconds. */
+export declare function themeLoopSeconds(theme: MusicTheme): number;
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export declare function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[];

package/dist/audio/music.js

@@ -0,0 +1,34 @@
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export function mtof(midi) {
+    return 440 * 2 ** ((midi - 69) / 12);
+}
+/** Loop length of a theme in seconds. */
+export function themeLoopSeconds(theme) {
+    return (theme.bars * 4 * 60) / theme.bpm;
+}
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export function notesInWindow(theme, anchorSec, fromSec, toSec) {
+    const loop = themeLoopSeconds(theme);
+    if (loop <= 0 || toSec <= fromSec)
+        return [];
+    const spb = 60 / theme.bpm;
+    const out = [];
+    for (const event of theme.events) {
+        const onset = event.beat * spb;
+        let k = Math.max(0, Math.floor((fromSec - anchorSec - onset) / loop));
+        for (;;) {
+            const when = anchorSec + onset + k * loop;
+            if (when > toSec)
+                break;
+            if (when > fromSec)
+                out.push({ event, when });
+            k += 1;
+        }
+    }
+    return out;
+}

package/dist/audio/synth.d.ts

@@ -0,0 +1,60 @@
+/** Oscillator waveform available to a pitched synth voice. */
+export type SynthWave = "sine" | "square" | "sawtooth" | "triangle";
+/** Biquad filter shape a noise voice is coloured through. */
+export type SynthFilter = "lowpass" | "highpass" | "bandpass";
+/**
+ * A pitched oscillator voice: a 12ms linear attack to `gain`, then an
+ * exponential decay to silence across `duration`, with an optional
+ * exponential pitch slide from `freq` to `slideTo`.
+ */
+export interface ToneVoice {
+    kind: "tone";
+    /** Start frequency in Hz. */
+    freq: number;
+    /** Total voice length in seconds (the decay spans this). */
+    duration: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Oscillator waveform. Default "sine". */
+    wave?: SynthWave;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+    /** When set, pitch ramps exponentially from `freq` to this Hz across `duration`. */
+    slideTo?: number;
+    /** Attack ramp in seconds. Default 0.012. */
+    attack?: number;
+}
+/**
+ * A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised
+ * from a shared 1s noise buffer at a randomised playback rate and start offset,
+ * decaying exponentially to silence at `duration * decay`.
+ */
+export interface NoiseVoice {
+    kind: "noise";
+    /** Total voice length in seconds. */
+    duration: number;
+    /** Biquad cutoff/centre in Hz. */
+    filterFreq: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Filter shape. Default "lowpass". */
+    filterType?: SynthFilter;
+    /** Fraction of `duration` over which the burst decays to silence. Default 0.9. */
+    decay?: number;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+}
+/** One layered voice of a synth cue. */
+export type SynthVoice = ToneVoice | NoiseVoice;
+/**
+ * A procedural sound cue: a set of voices triggered together, each with its own
+ * `delay`, summed into one one-shot. Pure serialisable data — the shell realises
+ * it on Web Audio, so the same catalog runs headless in tests with no `AudioContext`.
+ */
+export interface SynthPatch {
+    voices: readonly SynthVoice[];
+    /** Overall cue gain multiplier applied to every voice. Default 1. */
+    gain?: number;
+}
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export declare function patchDuration(patch: SynthPatch): number;

package/dist/audio/synth.js

@@ -0,0 +1,8 @@
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export function patchDuration(patch) {
+    let end = 0;
+    for (const voice of patch.voices) {
+        end = Math.max(end, (voice.delay ?? 0) + voice.duration);
+    }
+    return end;
+}

package/dist/authoring.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Task-first JGEngine authoring surface.
+ *
+ * Game code should begin here. Domain and runtime deep imports remain available for
+ * advanced composition, but this module intentionally exposes common authored
+ * concepts without requiring callers to understand the repository layout.
+ */
+export { defineGame, type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
+export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";
+export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, type WorldFeature, } from "./world/features.js";
+export { seededRng, seededStreams } from "./random/rng.js";
+export { selectSpawnPoint, type SpawnPointSelectionOptions, type SpawnPointDistanceBias, } from "./ai/spawnPoint.js";
+export { contextVerb } from "./interaction/contextMenu.js";
+export { type ActionCodesMap } from "./input/actionBindings.js";

package/dist/authoring.js

@@ -0,0 +1,14 @@
+/**
+ * Task-first JGEngine authoring surface.
+ *
+ * Game code should begin here. Domain and runtime deep imports remain available for
+ * advanced composition, but this module intentionally exposes common authored
+ * concepts without requiring callers to understand the repository layout.
+ */
+export { defineGame, } from "./game/defineGame.js";
+export { lootTable, } from "./game/lootTable.js";
+export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, } from "./world/features.js";
+export { seededRng, seededStreams } from "./random/rng.js";
+export { selectSpawnPoint, } from "./ai/spawnPoint.js";
+export { contextVerb } from "./interaction/contextMenu.js";
+export {} from "./input/actionBindings.js";

package/dist/cartridge/runtime.d.ts

@@ -0,0 +1,15 @@
+import { type AbilityKit } from "../combat/abilityKit.js";
+import type { GameLoop } from "../game/defineGame.js";
+import type { GameContext, GameContextContent } from "../runtime/gameContext.js";
+import { type CartridgeRun, type CartridgeSpec } from "./spec.js";
+export interface CartridgeRuntime {
+    content: GameContextContent;
+    loop: GameLoop<GameContext>;
+    run(ctx: GameContext): CartridgeRun;
+    weaponKit(ctx: GameContext): AbilityKit;
+    chooseUpgrade(ctx: GameContext, offerId: string): void;
+    begin(ctx: GameContext): void;
+    reset(ctx: GameContext): void;
+    spec: CartridgeSpec;
+}
+export declare function createCartridge(spec: CartridgeSpec): CartridgeRuntime;