@jgengine/core 0.7.0 → 0.9.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;
@@ -106,13 +106,25 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
     let spawnedTotal = state.spawnedTotal;
     let alive = ctx.alive;
     const entries = config.waves[wave]?.entries ?? [];
+    const spawnPoints = config.spawnPoints;
+    const playerPositions = ctx.playerPositions ?? [];
     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 });
+        const spawn = { entryId: picked.entry.id, cost: picked.entry.cost, wave };
+        if (spawnPoints !== undefined && spawnPoints.length > 0) {
+            const [roll, nextRng] = nextRandom(rng);
+            rng = nextRng;
+            const point = pickSpawnPoint(spawnPoints, playerPositions, { roll, bias: config.spawnPointBias });
+            if (point !== null) {
+                spawn.point = point;
+                spawn.laneId = spawnPoints.indexOf(point);
+            }
+        }
+        spawns.push(spawn);
         spawnedThisWave += 1;
         spawnedTotal += 1;
         alive += 1;

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/anim/easing.d.ts

@@ -0,0 +1,14 @@
+export type Easing = (t: number) => number;
+export declare function lerp(from: number, to: number, t: number): number;
+export declare function clamp01(t: number): number;
+export declare function smoothstep(t: number): number;
+export declare function easeInQuad(t: number): number;
+export declare function easeOutQuad(t: number): number;
+export declare function easeInOutQuad(t: number): number;
+export declare function easeInCubic(t: number): number;
+export declare function easeOutCubic(t: number): number;
+export declare function easeInOutCubic(t: number): number;
+export declare function easeOutBack(t: number): number;
+export declare function easeOutElastic(t: number): number;
+export declare function tween(from: number, to: number, t: number, easing?: Easing): number;
+export declare function timedProgress(startedAt: number, now: number, durationMs: number): number;

package/dist/anim/easing.js

@@ -0,0 +1,55 @@
+export function lerp(from, to, t) {
+    return from + (to - from) * t;
+}
+export function clamp01(t) {
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+export function smoothstep(t) {
+    const c = clamp01(t);
+    return c * c * (3 - 2 * c);
+}
+export function easeInQuad(t) {
+    const c = clamp01(t);
+    return c * c;
+}
+export function easeOutQuad(t) {
+    const c = clamp01(t);
+    return 1 - (1 - c) * (1 - c);
+}
+export function easeInOutQuad(t) {
+    const c = clamp01(t);
+    return c < 0.5 ? 2 * c * c : 1 - ((-2 * c + 2) ** 2) / 2;
+}
+export function easeInCubic(t) {
+    const c = clamp01(t);
+    return c * c * c;
+}
+export function easeOutCubic(t) {
+    const c = clamp01(t);
+    return 1 - (1 - c) ** 3;
+}
+export function easeInOutCubic(t) {
+    const c = clamp01(t);
+    return c < 0.5 ? 4 * c * c * c : 1 - ((-2 * c + 2) ** 3) / 2;
+}
+const BACK_OVERSHOOT = 1.70158;
+export function easeOutBack(t) {
+    const c = clamp01(t);
+    const s = BACK_OVERSHOOT + 1;
+    return 1 + s * (c - 1) ** 3 + BACK_OVERSHOOT * (c - 1) ** 2;
+}
+const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+export function easeOutElastic(t) {
+    const c = clamp01(t);
+    if (c === 0 || c === 1)
+        return c;
+    return 2 ** (-10 * c) * Math.sin((c * 10 - 0.75) * ELASTIC_PERIOD) + 1;
+}
+export function tween(from, to, t, easing = smoothstep) {
+    return lerp(from, to, easing(clamp01(t)));
+}
+export function timedProgress(startedAt, now, durationMs) {
+    if (durationMs <= 0)
+        return now >= startedAt ? 1 : 0;
+    return clamp01((now - startedAt) / durationMs);
+}

package/dist/behaviour/behaviour.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Unity-style behaviour lifecycle over a headless id-keyed node tree, ported from
+ * vladkrutenyuk/three-start (MIT) and adapted to run without three.js: nodes are plain
+ * string ids (use entity instance ids to pair with `entityStore`), and the shell binds
+ * render-side hooks separately.
+ *
+ * Lifecycle per behaviour: `onAwake` (once, first activation) → `onEnable` (every
+ * inactive→active transition) → `onStart` (once, after the first `onEnable`) →
+ * `onUpdate` (per `world.update` while active) → `onDisable` (every active→inactive
+ * transition) → `onDestroy` (once, always — even if never activated).
+ *
+ * `world.start()` bootstraps in passes: modules awake → modules start → modules join
+ * update dispatch → ALL behaviours on effectively-active nodes awake (even disabled
+ * ones) → enable/start/subscribe. Behaviours attached during the module pass are
+ * deferred to the behaviour passes, so module `onUpdate` always dispatches before any
+ * behaviour `onUpdate`.
+ */
+/**
+ * Declaration-merging registry games and adapters augment for typed access to
+ * world modules:
+ *
+ * ```ts
+ * declare module "@jgengine/core/behaviour/behaviour" {
+ *   interface JGEngineRegister {
+ *     modules: { physics: PhysicsModule; director: DirectorModule };
+ *   }
+ * }
+ * ```
+ */
+export interface JGEngineRegister {
+}
+export type RegisterField<TKey extends string, TFallback = unknown> = TKey extends keyof JGEngineRegister ? JGEngineRegister[TKey] : TFallback;
+/** Resolves to the augmented module map when `JGEngineRegister` declares one. */
+export type BehaviourModules = RegisterField<"modules", Record<string, BehaviourModule>>;
+interface UpdateSubscriber {
+    onUpdate(dt: number): void;
+}
+interface BehaviourWorldInternal extends BehaviourWorld {
+    _subscribeUpdate(subscriber: UpdateSubscriber): void;
+    _unsubscribeUpdate(subscriber: UpdateSubscriber): void;
+    _isEffectivelyActive(nodeId: string): boolean;
+    _detachBehaviour(behaviour: Behaviour): void;
+}
+/**
+ * Subclass and override the lifecycle hooks. A behaviour only joins the per-frame
+ * update dispatch if it actually overrides `onUpdate` (prototype-identity check at
+ * each activation), so hook-only behaviours cost nothing per frame.
+ */
+export declare class Behaviour {
+    /** @internal */ _world: BehaviourWorldInternal | null;
+    /** @internal */ _nodeId: string | null;
+    /** @internal */ _awoken: boolean;
+    /** @internal */ _startedOnce: boolean;
+    /** @internal */ _isActive: boolean;
+    private _enabled;
+    private _destroyed;
+    /** The node this behaviour is attached to; available from `onAwake` onward, never in the constructor. */
+    get nodeId(): string;
+    get world(): BehaviourWorld;
+    get modules(): BehaviourModules;
+    /** Own enabled flag; effective activity also requires the node's hierarchy to be active. */
+    get enabled(): boolean;
+    /** Whether the lifecycle is currently in the active span (`onEnable` fired, `onDisable` not yet). */
+    get isActive(): boolean;
+    onAwake(): void;
+    onEnable(): void;
+    onStart(): void;
+    onUpdate(_dt: number): void;
+    onDisable(): void;
+    onDestroy(): void;
+    enable(): void;
+    disable(): void;
+    /** Flips the flag only when the node is hierarchy-inactive or the world hasn't started; lifecycle catches up on the next activation. */
+    setEnabled(enabled: boolean): void;
+    /** Detaches from the node and fires `onDisable` (if active) then `onDestroy`. */
+    destroy(): void;
+    /** @internal */
+    _activate(): void;
+    /** @internal */
+    _deactivate(): void;
+    /** @internal */
+    _destroy(): void;
+}
+/**
+ * A world-lifetime service with typed sibling access via `this.modules`. Modules awake
+ * and start before any behaviour during `world.start()`, subscribe to update dispatch
+ * first (their `onUpdate` fires before every behaviour's), and have no disable/destroy —
+ * they live as long as the world.
+ */
+export declare class BehaviourModule {
+    /** @internal */ _world: BehaviourWorldInternal | null;
+    get world(): BehaviourWorld;
+    get modules(): BehaviourModules;
+    onAwake(): void;
+    onStart(): void;
+    onUpdate(_dt: number): void;
+    /** @internal */
+    _subscribe(): void;
+}
+export interface BehaviourWorld {
+    /** Creates the node if missing (parented under `parentId` when given, else a root); reparents an existing node when `parentId` differs. */
+    add(id: string, parentId?: string): void;
+    has(id: string): boolean;
+    parentOf(id: string): string | null;
+    childrenOf(id: string): readonly string[];
+    /** Moves `id` (and subtree) under `parentId` (`null` = root), firing enable/disable cascades when effective activity changes. Throws on cycles. */
+    setParent(id: string, parentId: string | null): void;
+    /** Attaches and immediately activates when the world has started, the node is effectively active, and the behaviour is enabled (deferred during bootstrap). */
+    attach<T extends Behaviour>(nodeId: string, behaviour: T): T;
+    behavioursOf(nodeId: string): readonly Behaviour[];
+    /**
+     * Sets the node's own flag and cascades activation/deactivation through the subtree,
+     * pruning at descendants whose own flag is false — so reactivating a parent restores
+     * exactly the per-child stored flags. A flip under an inactive ancestor changes only
+     * the flag.
+     */
+    setActive(id: string, active: boolean): void;
+    /** The node's own flag; unknown ids count active. */
+    isActiveSelf(id: string): boolean;
+    /** Own flag AND every ancestor's; unknown ids count active. */
+    isActive(id: string): boolean;
+    /** Registers modules by key. Throws on duplicate keys or after `start()`. */
+    addModules(modules: Partial<BehaviourModules>): void;
+    readonly modules: BehaviourModules;
+    /** Bootstraps: modules awake/start/subscribe, then all behaviours on effectively-active nodes awake, then enable+start+subscribe. Idempotent. */
+    start(): void;
+    started(): boolean;
+    /** Dispatches `onUpdate(dt)` to modules then behaviours, over a snapshot — subscribers added mid-dispatch first fire next update. */
+    update(dt: number): void;
+    /** Destroys every behaviour in the subtree (parent-first) and removes the nodes. */
+    destroyNode(id: string): boolean;
+    /** Destroys all nodes and behaviours and clears update dispatch. */
+    destroy(): void;
+}
+export declare function createBehaviourWorld(): BehaviourWorld;
+export {};