@jgengine/core 0.7.0 → 0.8.0

package/dist/behaviour/behaviour.js

@@ -0,0 +1,388 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 class Behaviour {
+    /** @internal */ _world = null;
+    /** @internal */ _nodeId = null;
+    /** @internal */ _awoken = false;
+    /** @internal */ _startedOnce = false;
+    /** @internal */ _isActive = false;
+    _enabled = true;
+    _destroyed = false;
+    /** The node this behaviour is attached to; available from `onAwake` onward, never in the constructor. */
+    get nodeId() {
+        if (this._nodeId === null)
+            throw new Error("behaviour is not attached to a node");
+        return this._nodeId;
+    }
+    get world() {
+        if (this._world === null)
+            throw new Error("behaviour is not attached to a world");
+        return this._world;
+    }
+    get modules() {
+        return this.world.modules;
+    }
+    /** Own enabled flag; effective activity also requires the node's hierarchy to be active. */
+    get enabled() {
+        return this._enabled;
+    }
+    /** Whether the lifecycle is currently in the active span (`onEnable` fired, `onDisable` not yet). */
+    get isActive() {
+        return this._isActive;
+    }
+    onAwake() { }
+    onEnable() { }
+    onStart() { }
+    onUpdate(_dt) { }
+    onDisable() { }
+    onDestroy() { }
+    enable() {
+        this.setEnabled(true);
+    }
+    disable() {
+        this.setEnabled(false);
+    }
+    /** 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) {
+        if (this._enabled === enabled)
+            return;
+        this._enabled = enabled;
+        const world = this._world;
+        const nodeId = this._nodeId;
+        if (world === null || nodeId === null)
+            return;
+        if (!world.started() || !world._isEffectivelyActive(nodeId))
+            return;
+        if (enabled)
+            this._activate();
+        else
+            this._deactivate();
+    }
+    /** Detaches from the node and fires `onDisable` (if active) then `onDestroy`. */
+    destroy() {
+        if (this._world !== null)
+            this._world._detachBehaviour(this);
+        this._destroy();
+    }
+    /** @internal */
+    _activate() {
+        if (this._isActive)
+            return;
+        if (this._world === null)
+            return;
+        this._isActive = true;
+        if (!this._awoken) {
+            this._awoken = true;
+            this.onAwake();
+        }
+        this.onEnable();
+        if (!this._startedOnce) {
+            this._startedOnce = true;
+            this.onStart();
+        }
+        if (this.onUpdate !== Behaviour.prototype.onUpdate) {
+            this._world._subscribeUpdate(this);
+        }
+    }
+    /** @internal */
+    _deactivate() {
+        if (!this._isActive)
+            return;
+        this._isActive = false;
+        this._world?._unsubscribeUpdate(this);
+        this.onDisable();
+    }
+    /** @internal */
+    _destroy() {
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this._deactivate();
+        this.onDestroy();
+        this._world = null;
+        this._nodeId = null;
+    }
+}
+/**
+ * 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 class BehaviourModule {
+    /** @internal */ _world = null;
+    get world() {
+        if (this._world === null)
+            throw new Error("module is not registered with a world");
+        return this._world;
+    }
+    get modules() {
+        return this.world.modules;
+    }
+    onAwake() { }
+    onStart() { }
+    onUpdate(_dt) { }
+    /** @internal */
+    _subscribe() {
+        if (this._world === null)
+            return;
+        if (this.onUpdate !== BehaviourModule.prototype.onUpdate) {
+            this._world._subscribeUpdate(this);
+        }
+    }
+}
+export function createBehaviourWorld() {
+    const nodes = new Map();
+    const roots = [];
+    const updateSubscribers = [];
+    const moduleRecord = {};
+    let started = false;
+    let bootstrapping = false;
+    function mustGet(id) {
+        const node = nodes.get(id);
+        if (node === undefined)
+            throw new Error(`unknown behaviour node "${id}"`);
+        return node;
+    }
+    function ensureNode(id, parentId) {
+        const existing = nodes.get(id);
+        if (existing !== undefined) {
+            if (parentId !== undefined && existing.parent?.id !== parentId)
+                world.setParent(id, parentId);
+            return existing;
+        }
+        const parent = parentId === undefined ? null : ensureNode(parentId);
+        const node = { id, parent, children: [], activeSelf: true, behaviours: [] };
+        nodes.set(id, node);
+        if (parent === null)
+            roots.push(node);
+        else
+            parent.children.push(node);
+        return node;
+    }
+    function parentChainActive(node) {
+        let ancestor = node.parent;
+        while (ancestor !== null) {
+            if (!ancestor.activeSelf)
+                return false;
+            ancestor = ancestor.parent;
+        }
+        return true;
+    }
+    function isEffectivelyActive(node) {
+        return node.activeSelf && parentChainActive(node);
+    }
+    function traverseActiveSelf(node, visit) {
+        if (!node.activeSelf)
+            return;
+        visit(node);
+        for (const child of [...node.children])
+            traverseActiveSelf(child, visit);
+    }
+    function activateNode(node) {
+        if (!started)
+            return;
+        if (!isEffectivelyActive(node))
+            return;
+        for (const behaviour of [...node.behaviours]) {
+            if (behaviour.enabled)
+                behaviour._activate();
+        }
+    }
+    function deactivateNode(node) {
+        for (const behaviour of [...node.behaviours]) {
+            if (behaviour._isActive)
+                behaviour._deactivate();
+        }
+    }
+    function deactivateSubtree(node) {
+        deactivateNode(node);
+        for (const child of [...node.children])
+            traverseActiveSelf(child, deactivateNode);
+    }
+    function unlink(node) {
+        const siblings = node.parent === null ? roots : node.parent.children;
+        const index = siblings.indexOf(node);
+        if (index !== -1)
+            siblings.splice(index, 1);
+    }
+    function collectSubtree(node, into) {
+        into.push(node);
+        for (const child of node.children)
+            collectSubtree(child, into);
+    }
+    const world = {
+        add(id, parentId) {
+            ensureNode(id, parentId);
+        },
+        has: (id) => nodes.has(id),
+        parentOf: (id) => mustGet(id).parent?.id ?? null,
+        childrenOf: (id) => mustGet(id).children.map((child) => child.id),
+        setParent(id, parentId) {
+            const node = mustGet(id);
+            const nextParent = parentId === null ? null : mustGet(parentId);
+            if (node.parent === nextParent)
+                return;
+            for (let ancestor = nextParent; ancestor !== null; ancestor = ancestor.parent) {
+                if (ancestor === node)
+                    throw new Error(`cannot parent "${parentId}" under its own descendant "${id}"`);
+            }
+            const wasEffective = isEffectivelyActive(node);
+            unlink(node);
+            node.parent = nextParent;
+            if (nextParent === null)
+                roots.push(node);
+            else
+                nextParent.children.push(node);
+            const nowEffective = isEffectivelyActive(node);
+            if (!started || wasEffective === nowEffective)
+                return;
+            if (nowEffective)
+                traverseActiveSelf(node, activateNode);
+            else
+                deactivateSubtree(node);
+        },
+        attach(nodeId, behaviour) {
+            if (behaviour._world !== null)
+                throw new Error("behaviour is already attached");
+            const node = ensureNode(nodeId);
+            behaviour._world = world;
+            behaviour._nodeId = nodeId;
+            node.behaviours.push(behaviour);
+            if (started && !bootstrapping && behaviour.enabled && isEffectivelyActive(node)) {
+                behaviour._activate();
+            }
+            return behaviour;
+        },
+        behavioursOf: (nodeId) => [...(nodes.get(nodeId)?.behaviours ?? [])],
+        setActive(id, active) {
+            const node = ensureNode(id);
+            if (node.activeSelf === active)
+                return;
+            node.activeSelf = active;
+            if (!parentChainActive(node))
+                return;
+            if (active)
+                traverseActiveSelf(node, activateNode);
+            else
+                deactivateSubtree(node);
+        },
+        isActiveSelf: (id) => nodes.get(id)?.activeSelf ?? true,
+        isActive(id) {
+            const node = nodes.get(id);
+            return node === undefined ? true : isEffectivelyActive(node);
+        },
+        addModules(modules) {
+            if (started)
+                throw new Error("cannot add modules after start()");
+            for (const [key, module] of Object.entries(modules)) {
+                if (module === undefined)
+                    continue;
+                if (moduleRecord[key] !== undefined)
+                    throw new Error(`module "${key}" is already registered`);
+                const instance = module;
+                instance._world = world;
+                moduleRecord[key] = instance;
+            }
+        },
+        modules: moduleRecord,
+        start() {
+            if (started)
+                return;
+            started = true;
+            bootstrapping = true;
+            const modules = Object.values(moduleRecord);
+            for (const module of modules)
+                module.onAwake();
+            for (const module of modules)
+                module.onStart();
+            for (const module of modules)
+                module._subscribe();
+            bootstrapping = false;
+            for (const root of [...roots]) {
+                traverseActiveSelf(root, (node) => {
+                    for (const behaviour of [...node.behaviours]) {
+                        if (!behaviour._awoken) {
+                            behaviour._awoken = true;
+                            behaviour.onAwake();
+                        }
+                    }
+                });
+            }
+            for (const root of [...roots]) {
+                traverseActiveSelf(root, activateNode);
+            }
+        },
+        started: () => started,
+        update(dt) {
+            for (const subscriber of [...updateSubscribers])
+                subscriber.onUpdate(dt);
+        },
+        destroyNode(id) {
+            const node = nodes.get(id);
+            if (node === undefined)
+                return false;
+            const subtree = [];
+            collectSubtree(node, subtree);
+            for (const member of subtree) {
+                for (const behaviour of [...member.behaviours])
+                    behaviour._destroy();
+                member.behaviours.length = 0;
+            }
+            unlink(node);
+            for (const member of subtree)
+                nodes.delete(member.id);
+            return true;
+        },
+        destroy() {
+            for (const root of [...roots])
+                world.destroyNode(root.id);
+            updateSubscribers.length = 0;
+        },
+        _subscribeUpdate(subscriber) {
+            if (!updateSubscribers.includes(subscriber))
+                updateSubscribers.push(subscriber);
+        },
+        _unsubscribeUpdate(subscriber) {
+            const index = updateSubscribers.indexOf(subscriber);
+            if (index !== -1)
+                updateSubscribers.splice(index, 1);
+        },
+        _isEffectivelyActive: (nodeId) => {
+            const node = nodes.get(nodeId);
+            return node === undefined ? true : isEffectivelyActive(node);
+        },
+        _detachBehaviour(behaviour) {
+            const nodeId = behaviour._nodeId;
+            if (nodeId === null)
+                return;
+            const node = nodes.get(nodeId);
+            if (node === undefined)
+                return;
+            const index = node.behaviours.indexOf(behaviour);
+            if (index !== -1)
+                node.behaviours.splice(index, 1);
+        },
+    };
+    return world;
+}

package/dist/cards/cardPile.d.ts

@@ -6,6 +6,7 @@ export interface CardPileConfig {
     handZone?: ZoneName;
     handLimit?: number;
     reshuffleFrom?: ZoneName;
+    onChange?: () => void;
 }
 export interface CardPileState {
     readonly zones: Readonly<Record<ZoneName, readonly string[]>>;

package/dist/cards/cardPile.js

@@ -130,6 +130,7 @@ export function createCardPile(config, initial) {
         zoneOf: (cardId) => zoneOf(state, cardId),
         shuffle(zone, seed) {
             state = shuffleZone(state, zone ?? drawFrom, seed);
+            config.onChange?.();
         },
         draw(n, options) {
             const result = draw(state, n, {
@@ -139,28 +140,36 @@ export function createCardPile(config, initial) {
                 reshuffleFrom: config.reshuffleFrom,
             });
             state = result.state;
+            config.onChange?.();
             return result.drawn;
         },
         discard(ids, options) {
             const result = moveCards(state, ids, options?.from ?? handZone, options?.to ?? discardTo, "top");
-            if (result.status === "ok")
+            if (result.status === "ok") {
                 state = result.state;
+                config.onChange?.();
+            }
             return result;
         },
         exhaust(ids, exhaustZone, from) {
             const result = moveCards(state, ids, from ?? handZone, exhaustZone, "top");
-            if (result.status === "ok")
+            if (result.status === "ok") {
                 state = result.state;
+                config.onChange?.();
+            }
             return result;
         },
         move(ids, from, to, position) {
             const result = moveCards(state, ids, from, to, position);
-            if (result.status === "ok")
+            if (result.status === "ok") {
                 state = result.state;
+                config.onChange?.();
+            }
             return result;
         },
         reset(next) {
             state = next;
+            config.onChange?.();
         },
     };
 }

package/dist/combat/abilityKit.d.ts

@@ -21,6 +21,10 @@ export interface AbilitySlotSnapshot {
     ready: boolean;
 }
 export type AbilityCastReason = "unknown-slot" | "cooldown" | "no-resource";
+export interface AbilitySlotRetune {
+    cooldownMs?: number;
+    resourceCost?: number;
+}
 export type AbilityCastResult = {
     ok: true;
     slot: AbilitySlotSnapshot;
@@ -38,5 +42,6 @@ export interface AbilityKit {
     cast(slotId: string, resourceAvailable?: number): AbilityCastResult;
     tick(dtSeconds: number): void;
     reset(slotId?: string): void;
+    retuneSlot(slotId: string, patch: AbilitySlotRetune): boolean;
 }
 export declare function createAbilityKit(configs: readonly AbilitySlotConfig[]): AbilityKit;

package/dist/combat/abilityKit.js

@@ -125,5 +125,15 @@ export function createAbilityKit(configs) {
                 runtime.flashRemainingMs = 0;
             }
         },
+        retuneSlot(slotId, patch) {
+            const runtime = runtimes.get(slotId);
+            if (runtime === undefined)
+                return false;
+            if (patch.cooldownMs !== undefined)
+                runtime.config.cooldownMs = Math.max(0, patch.cooldownMs);
+            if (patch.resourceCost !== undefined)
+                runtime.config.resourceCost = Math.max(0, patch.resourceCost);
+            return true;
+        },
     };
 }

package/dist/combat/effects.d.ts

@@ -65,7 +65,7 @@ export interface EffectSystemDeps {
     onLethal?(instanceId: string, ctx: LethalContext): void;
 }
 export interface EffectSystem {
-    canReceive(instanceId: string, effect: string): string | null;
+    canReceive(instanceId: string, effect: string, magnitude?: number): string | null;
     preview(input: SingleTargetEffectInput): number;
     applyEffect(input: EffectInput): EffectResult[];
 }

package/dist/combat/effects.js

@@ -40,18 +40,21 @@ export function createEffectSystem(deps) {
         }
         return result;
     }
-    function canReceive(instanceId, effect) {
+    function canReceive(instanceId, effect, magnitude) {
         const rule = resolveRule(instanceId, effect);
         if (rule === null)
             return "not-receivable";
         const stats = deps.resolveStats(instanceId);
         if (stats === undefined)
             return "unknown-instance";
-        const anyPoolAboveMin = rule.order.some((statId) => {
+        const restorative = magnitude !== undefined && magnitude < 0;
+        const anyPoolHasHeadroom = rule.order.some((statId) => {
             const stat = stats[statId];
-            return stat !== undefined && stat.current > stat.min;
+            if (stat === undefined)
+                return false;
+            return restorative ? stat.current < stat.max : stat.current > stat.min;
         });
-        if (!anyPoolAboveMin)
+        if (!anyPoolHasHeadroom)
             return "pools-depleted";
         return null;
     }
@@ -80,13 +83,13 @@ export function createEffectSystem(deps) {
         return { instanceId, effect, applied, lethal };
     }
     function applyTo(instanceId, effect, via, from, scale) {
-        if (canReceive(instanceId, effect) !== null)
-            return null;
         const rule = resolveRule(instanceId, effect);
         const stats = deps.resolveStats(instanceId);
         if (rule === null || stats === undefined)
             return null;
         const drainMagnitude = modifiedDrainMagnitude(baseDrainMagnitude(effect, via) * scale, rule);
+        if (canReceive(instanceId, effect, drainMagnitude) !== null)
+            return null;
         const result = drainPools(instanceId, effect, rule, stats, drainMagnitude);
         if (result.lethal)
             deps.onLethal?.(instanceId, { from, via, effect });

package/dist/combat/projectiles.d.ts

@@ -1,3 +1,4 @@
+import type { BallisticSweep } from "../physics/ballisticSweep.js";
 import type { EntityPosition } from "../scene/entityStore.js";
 import type { Aim } from "../scene/spatial.js";
 import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
@@ -7,11 +8,22 @@ export interface ProjectileShotInput {
     aim: Aim;
     effect: string;
 }
-export interface RaycastHit {
+/** A raycast hit against a scene entity — the ray reached `instanceId` at `distance` along its length. */
+export interface EntityRaycastHit {
+    kind: "entity";
     instanceId: string;
     distance: number;
     at: EntityPosition;
 }
+/** A raycast hit against a placed scene object's bounding box — see `ProjectileObjectsDeps.halfExtents`. */
+export interface ObjectRaycastHit {
+    kind: "object";
+    instanceId: string;
+    catalogId: string;
+    distance: number;
+    at: EntityPosition;
+}
+export type RaycastHit = EntityRaycastHit | ObjectRaycastHit;
 export type Raycast = (from: string, aim: Aim, range: number) => RaycastHit[];
 export interface ProjectileSettleReport {
     from: string;
@@ -20,19 +32,44 @@ export interface ProjectileSettleReport {
     effect: string;
     hit: boolean;
 }
+/** Read-only scene object access for the default `raycast`; matches `ObjectStore.list()`/a catalog lookup structurally. */
+export interface ProjectileObjectsDeps {
+    list(): readonly {
+        instanceId: string;
+        catalogId: string;
+        position: [number, number, number];
+    }[];
+    /** Half-extents of the object's axis-aligned bounding box; `null`/omitted falls back to `[0.5, 0.5, 0.5]`. */
+    halfExtents?(catalogId: string): [number, number, number] | null;
+}
 export interface ProjectileSystemDeps {
     effects: EffectSystem;
     spatial: CombatSpatialDeps;
     getStat(itemId: string, stat: string): number | null;
     raycast?: Raycast;
+    /** Optional object awareness for the default `raycast`; when set, placed objects can block or absorb a shot. */
+    objects?: ProjectileObjectsDeps;
+    /**
+     * Optional collision-aware arc test for ballistic shots (see `createBallisticSweep` in
+     * `physics/ballisticSweep`). A hit settles the shot at the impact point; `null` or omission
+     * falls back to the closed-form landing.
+     */
+    sweepBallistic?: BallisticSweep;
     now?: () => number;
     onSettle?(report: ProjectileSettleReport): void;
 }
+export type ProjectileHit = {
+    kind: "entity";
+    instanceId: string;
+    distance: number;
+} | {
+    kind: "object";
+    instanceId: string;
+    catalogId: string;
+    distance: number;
+};
 export interface ProjectilePrediction {
-    hits: {
-        instanceId: string;
-        distance: number;
-    }[];
+    hits: ProjectileHit[];
     blocked?: boolean;
 }
 export type SettleResult = {