@jgengine/core 0.10.0 → 0.12.0

package/dist/runtime/context/combatFx.js

@@ -0,0 +1,161 @@
+import { resolveHitReaction } from "../../combat/hitReaction.js";
+import { pointInTelegraph } from "../../combat/telegraph.js";
+/** @internal */
+export function createCombatFx(d) {
+    const { entities, events, time } = d;
+    function emitFloatText(input) {
+        const position = input.position ??
+            (input.instanceId === undefined ? undefined : entities.get(input.instanceId)?.position);
+        if (position === undefined)
+            return;
+        const text = input.text ?? (input.amount === undefined ? "" : String(Math.round(input.amount)));
+        const event = {
+            position: [position[0], position[1], position[2]],
+            text,
+            kind: input.kind ?? "info",
+        };
+        if (input.instanceId !== undefined)
+            event.instanceId = input.instanceId;
+        if (input.amount !== undefined)
+            event.amount = input.amount;
+        if (input.hitType !== undefined)
+            event.hitType = input.hitType;
+        if (input.element !== undefined)
+            event.element = input.element;
+        if (input.crit !== undefined)
+            event.crit = input.crit;
+        if (input.scale !== undefined)
+            event.scale = input.scale;
+        events.emit("entity.floatText", event);
+    }
+    const vfxDefaultDurationMs = {
+        projectile: 380,
+        beam: 260,
+        nova: 520,
+        glow: 700,
+        spark: 240,
+    };
+    let vfxSeq = 0;
+    function resolveVfxPoint(ref) {
+        if (ref === undefined)
+            return undefined;
+        if (typeof ref === "string") {
+            const entity = entities.get(ref);
+            if (entity === null)
+                return undefined;
+            return [entity.position[0], entity.position[1], entity.position[2]];
+        }
+        return [ref[0], ref[1], ref[2]];
+    }
+    function emitVfx(input) {
+        const to = resolveVfxPoint(input.to);
+        const from = resolveVfxPoint(input.from) ?? to;
+        if (from === undefined)
+            return;
+        const event = {
+            id: vfxSeq++,
+            kind: input.kind,
+            color: input.color,
+            from,
+            durationMs: input.durationMs ?? vfxDefaultDurationMs[input.kind],
+        };
+        if (to !== undefined)
+            event.to = to;
+        if (input.radius !== undefined)
+            event.radius = input.radius;
+        events.emit("combat.vfx", event);
+    }
+    let telegraphSeq = 0;
+    function fireTelegraph(input) {
+        const id = telegraphSeq++;
+        const telegraphEvent = {
+            id,
+            shape: input.shape,
+            position: [input.at[0], input.at[1], input.at[2]],
+            windupMs: input.windupMs,
+            kind: input.kind ?? "danger",
+        };
+        if (input.dir !== undefined)
+            telegraphEvent.dir = input.dir;
+        events.emit("combat.telegraph", telegraphEvent);
+        const cancelVisual = () => events.emit("combat.telegraphCancelled", { id });
+        const bound = input.effect;
+        if (bound === undefined)
+            return cancelVisual;
+        const config = { shape: input.shape, at: input.at, windupMs: input.windupMs };
+        if (input.dir !== undefined)
+            config.dir = input.dir;
+        const cancelEffect = time.after(input.windupMs / 1000, () => {
+            const targets = entities.list().filter((entity) => pointInTelegraph(config, entity.position));
+            for (const target of targets) {
+                applyEffectAndFloat({
+                    from: input.from,
+                    to: target.id,
+                    effect: bound.effect,
+                    ...(bound.via === undefined ? {} : { via: bound.via }),
+                });
+            }
+        });
+        return () => {
+            cancelEffect();
+            cancelVisual();
+        };
+    }
+    function applyHitReaction(input) {
+        const attacker = entities.get(input.from);
+        const target = entities.get(input.to);
+        if (target === null)
+            return null;
+        const attackerPos = attacker?.position ?? target.position;
+        const reaction = resolveHitReaction(input.config, {
+            attackerPos,
+            targetPos: target.position,
+            ...(input.power === undefined ? {} : { power: input.power }),
+        });
+        entities.setPose(input.to, {
+            position: [
+                target.position[0] + reaction.impulse[0],
+                target.position[1] + reaction.impulse[1],
+                target.position[2] + reaction.impulse[2],
+            ],
+            rotationY: target.rotationY,
+        });
+        const reactionEvent = {
+            instanceId: input.to,
+            position: [target.position[0], target.position[1], target.position[2]],
+            hitstopMs: reaction.hitstopMs,
+        };
+        if (reaction.shake !== null)
+            reactionEvent.shake = reaction.shake;
+        if (reaction.trauma !== null)
+            reactionEvent.trauma = reaction.trauma;
+        events.emit("combat.hitReaction", reactionEvent);
+        return reaction;
+    }
+    function applyEffectAndFloat(input) {
+        const positionsBefore = new Map();
+        for (const entity of entities.list())
+            positionsBefore.set(entity.id, entity.position);
+        const results = d.applyEffect(input);
+        for (const result of results) {
+            let total = 0;
+            for (const delta of result.applied)
+                total += delta.delta;
+            if (total === 0)
+                continue;
+            const position = entities.get(result.instanceId)?.position ?? positionsBefore.get(result.instanceId);
+            if (position === undefined)
+                continue;
+            const magnitude = Math.abs(total);
+            emitFloatText({
+                instanceId: result.instanceId,
+                position: [position[0], position[1], position[2]],
+                text: String(Math.round(magnitude)),
+                kind: total < 0 ? "damage" : "heal",
+                amount: magnitude,
+            });
+        }
+        return results;
+    }
+    return { emitFloatText, emitVfx, fireTelegraph, applyHitReaction, applyEffectAndFloat };
+}

package/dist/runtime/context/deathLoot.d.ts

@@ -0,0 +1,30 @@
+import { type EffectDeathContext, type OnDeathSpec } from "../../combat/death.js";
+import type { Drop } from "../../game/lootTable.js";
+import { type WorldItemSpawnInput } from "../../game/worldItem.js";
+import type { GameContextContent } from "../gameContext.js";
+/** @internal Inputs for routing a resolved lethal kill into bag grants and/or ground-item spawns. */
+export interface LethalLootInput {
+    /** Drops produced by the death system's resolution (already rolled). */
+    drops: readonly Drop[];
+    /** True when the killer is the local/host player this context is resolving loot for. */
+    grantToLocalPlayer: boolean;
+    /** Catalog `onDeath` for the dying entity (drop mode + scatter). */
+    onDeath: OnDeathSpec | undefined;
+    /** World position of the dying entity — required for `dropMode: "world"`. */
+    position: readonly [number, number, number] | undefined;
+    /** Catalog id of the dying entity — used as loot source tag when present. */
+    catalogId: string | undefined;
+    content: GameContextContent;
+    spawnWorldItem: (input: WorldItemSpawnInput) => void;
+    grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
+    localUserId: string;
+}
+/**
+ * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as
+ * world items (`dropMode: "world"`) or grant straight into bags. Extracted from `createGameContext`
+ * so combat install stays free of nested loot branching.
+ * @internal
+ */
+export declare function applyLethalLoot(input: LethalLootInput): void;
+/** @internal Build the grant-to-local-player flag from a lethal effect context + local user id. */
+export declare function isLocalPlayerKill(lethalCtx: EffectDeathContext, localUserId: string): boolean;

package/dist/runtime/context/deathLoot.js

@@ -0,0 +1,39 @@
+import { deathReasonFromEffect, normalizeOnDeath, } from "../../combat/death.js";
+import { DEFAULT_RARITY, resolveDeathDrops, } from "../../game/worldItem.js";
+/**
+ * Pure death→loot policy: when a kill yields drops for the local player, either scatter them as
+ * world items (`dropMode: "world"`) or grant straight into bags. Extracted from `createGameContext`
+ * so combat install stays free of nested loot branching.
+ * @internal
+ */
+export function applyLethalLoot(input) {
+    if (input.drops.length === 0 || !input.grantToLocalPlayer)
+        return;
+    const normalizedOnDeath = normalizeOnDeath(input.onDeath);
+    if (normalizedOnDeath.dropMode === "world" && input.position !== undefined) {
+        const resolved = resolveDeathDrops([...input.drops], {
+            mode: "world",
+            origin: input.position,
+            resolveRarity: (itemId) => input.content.itemById?.(itemId)?.rarity ?? DEFAULT_RARITY,
+            resolveBaseType: (itemId) => input.content.itemById?.(itemId)?.baseType ?? itemId,
+            scatter: normalizedOnDeath.scatter,
+            ...(input.catalogId !== undefined ? { source: input.catalogId } : {}),
+        });
+        for (const spawn of resolved.worldSpawns)
+            input.spawnWorldItem(spawn);
+        if (resolved.grants.length > 0) {
+            input.grantToPlayer(input.localUserId, resolved.grants, input.catalogId);
+        }
+    }
+    else {
+        input.grantToPlayer(input.localUserId, [...input.drops], input.catalogId);
+    }
+}
+/** @internal Build the grant-to-local-player flag from a lethal effect context + local user id. */
+export function isLocalPlayerKill(lethalCtx, localUserId) {
+    const reason = deathReasonFromEffect({
+        ...lethalCtx,
+        userIdOf: (id) => (id === localUserId ? localUserId : undefined),
+    });
+    return reason.kind === "player_kill" && reason.killerUserId === localUserId;
+}

package/dist/runtime/context/player.d.ts

@@ -0,0 +1,48 @@
+import { type WalletState } from "../../economy/wallet.js";
+import type { GameFeatures } from "../../game/defineGame.js";
+import type { InventoryDeclaration } from "../../game/defineGame.js";
+import type { GameEvents } from "../../game/events.js";
+import { type Loadouts } from "../../game/loadout.js";
+import { type InventoryLayout, type InventorySet } from "../../inventory/inventoryModel.js";
+import { type PoseState } from "../../movement/poseState.js";
+import { type Possession } from "../../scene/possession.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import { type StatValueMap } from "../../scene/entityStats.js";
+import { type Stats } from "../../stats/statModifiers.js";
+import { type MotionIntents } from "../motionIntents.js";
+import type { GameContextEconomy, GameContextEntityEntry } from "../gameContext.js";
+/** @internal Wiring player-owned state needs from the live context. */
+export interface PlayerSubsystemDeps {
+    signalNotify: () => void;
+    inventoryDeclarations: Record<string, InventoryDeclaration>;
+    entities: EntityStore;
+    events: GameEvents;
+    catalogEntry: (instanceId: string) => GameContextEntityEntry | null | undefined;
+    ensureInstanceStats: (instanceId: string) => StatValueMap;
+    /** Reads another feature after descriptor install (loadout → unlocks). */
+    feature: <T>(key: keyof GameFeatures) => T | undefined;
+}
+/** @internal Inventory, wallets, pose, motion, loadout — per-player state surfaces. */
+export interface PlayerSubsystem {
+    inventoryIds: readonly string[];
+    inventoryByUser: ReadonlyMap<string, InventorySet<string>>;
+    inventoryFor: (userId: string) => InventorySet<string>;
+    layouts: Record<string, InventoryLayout>;
+    wallets: Map<string, WalletState>;
+    walletOf: (userId: string) => WalletState;
+    economy: GameContextEconomy;
+    putIntoAnyInventory: (userId: string, itemId: string, count: number) => void;
+    playerStatsFor: (userId: string) => Stats<string>;
+    pose: PoseState;
+    possession: Possession;
+    motionByUser: ReadonlyMap<string, MotionIntents>;
+    motionFor: (userId: string) => MotionIntents;
+    loadouts: Loadouts;
+    seedUserPool: (userId: string, statId: string, pool: {
+        current: number;
+        max?: number;
+        min?: number;
+    }) => void;
+}
+/** @internal */
+export declare function createPlayerSubsystem(d: PlayerSubsystemDeps): PlayerSubsystem;

package/dist/runtime/context/player.js

@@ -0,0 +1,125 @@
+import { balance as walletBalance, charge as walletCharge, createEmptyWallet, grant as walletGrant, isOverdrawn as walletIsOverdrawn, } from "../../economy/wallet.js";
+import { createLoadouts } from "../../game/loadout.js";
+import { createInventorySet, putItem, } from "../../inventory/inventoryModel.js";
+import { createPoseState } from "../../movement/poseState.js";
+import { createPossession } from "../../scene/possession.js";
+import { setStatValue } from "../../scene/entityStats.js";
+import { createStats } from "../../stats/statModifiers.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+import { createMotionIntents } from "../motionIntents.js";
+/** @internal */
+export function createPlayerSubsystem(d) {
+    const { signalNotify, entities, events, catalogEntry, ensureInstanceStats, feature } = d;
+    const playerStatsByUser = new Map();
+    function playerStatsFor(userId) {
+        let stats = playerStatsByUser.get(userId);
+        if (stats === undefined) {
+            stats = createStats({});
+            playerStatsByUser.set(userId, stats);
+        }
+        return stats;
+    }
+    const pose = createPoseState((instanceId) => catalogEntry(instanceId)?.movement);
+    const possession = notifyAfter(createPossession({ entities, events }), ["possess", "own", "disown"], signalNotify);
+    const inventoryDeclarations = d.inventoryDeclarations;
+    const inventoryIds = Object.keys(inventoryDeclarations);
+    const layouts = {};
+    for (const [inventoryId, declaration] of Object.entries(inventoryDeclarations)) {
+        layouts[inventoryId] = { slots: declaration.slots, accepts: declaration.accepts };
+    }
+    const traits = Object.values(inventoryDeclarations).find((declaration) => declaration.traits !== undefined)
+        ?.traits ?? { stackLimit: () => Number.POSITIVE_INFINITY };
+    const inventoryByUser = new Map();
+    function inventoryFor(userId) {
+        let set = inventoryByUser.get(userId);
+        if (set === undefined) {
+            set = notifyAfter(createInventorySet(layouts, traits), ["put", "take", "move", "replaceState"], signalNotify);
+            inventoryByUser.set(userId, set);
+        }
+        return set;
+    }
+    const wallets = new Map();
+    const walletOf = (userId) => wallets.get(userId) ?? createEmptyWallet();
+    const economy = {
+        balance: (userId, currencyId) => walletBalance(walletOf(userId), currencyId),
+        grant(userId, currencyId, amount) {
+            wallets.set(userId, walletGrant(walletOf(userId), currencyId, amount));
+            signalNotify();
+        },
+        charge(userId, currencyId, amount, options) {
+            const result = walletCharge(walletOf(userId), currencyId, amount, options);
+            if (result.status === "rejected")
+                return { reason: result.reason };
+            wallets.set(userId, result.state);
+            signalNotify();
+            return null;
+        },
+        isOverdrawn: (userId, currencyId) => walletIsOverdrawn(walletOf(userId), currencyId),
+    };
+    function putIntoAnyInventory(userId, itemId, count) {
+        const inventory = inventoryFor(userId);
+        for (const inventoryId of inventoryIds) {
+            if (inventory.put(inventoryId, itemId, count).status === "ok")
+                return;
+        }
+    }
+    function seedUserPool(userId, statId, pool) {
+        const map = ensureInstanceStats(userId);
+        const next = setStatValue(map, statId, pool);
+        map[statId] = next[statId];
+    }
+    const loadouts = notifyAfter(createLoadouts({
+        inventory: {
+            begin(userId) {
+                const inventory = inventoryFor(userId);
+                const staged = new Map();
+                return {
+                    put(inventoryId, itemId, count, slot) {
+                        const layout = layouts[inventoryId];
+                        if (layout === undefined)
+                            return { reason: `unknown inventory "${inventoryId}"` };
+                        const state = staged.get(inventoryId) ?? inventory.state(inventoryId);
+                        const result = putItem(state, layout, traits, itemId, count, slot === undefined ? undefined : { slot });
+                        if (result.status === "rejected")
+                            return { reason: result.reason };
+                        staged.set(inventoryId, result.state);
+                        return null;
+                    },
+                    commit() {
+                        for (const [inventoryId, state] of staged)
+                            inventory.replaceState(inventoryId, state);
+                    },
+                };
+            },
+        },
+        stats: { seed: seedUserPool },
+        economy: { grant: economy.grant },
+        unlocks: { grant: (userId, unlockId) => feature("unlocks")?.grant(userId, unlockId) },
+    }), ["applyLoadout"], signalNotify);
+    const motionByUser = new Map();
+    function motionFor(userId) {
+        let queue = motionByUser.get(userId);
+        if (queue === undefined) {
+            queue = createMotionIntents();
+            motionByUser.set(userId, queue);
+        }
+        return queue;
+    }
+    return {
+        inventoryIds,
+        inventoryByUser,
+        inventoryFor,
+        layouts,
+        wallets,
+        walletOf,
+        economy,
+        putIntoAnyInventory,
+        playerStatsFor,
+        pose,
+        possession,
+        motionByUser,
+        motionFor,
+        loadouts,
+        seedUserPool,
+    };
+}

package/dist/runtime/context/registries.d.ts

@@ -0,0 +1,13 @@
+import { type CardPile, type CardPileConfig } from "../../cards/cardPile.js";
+import { RaceState, type RaceStateConfig } from "../../game/race.js";
+import { type TurnLoop, type TurnLoopConfig } from "../../turn/turnLoop.js";
+/** @internal Lazily-created, id-keyed card-pile / turn-loop / race registries shared by `ctx.game.cards|turn|race` and their save modules. */
+export interface ContextRegistries {
+    pile(id: string, config?: CardPileConfig): CardPile;
+    loop(id: string, config?: TurnLoopConfig): TurnLoop;
+    raceState(id: string, config?: RaceStateConfig): RaceState;
+    cardPiles: ReadonlyMap<string, CardPile>;
+    turnLoops: ReadonlyMap<string, TurnLoop>;
+}
+/** @internal */
+export declare function createContextRegistries(signalNotify: () => void): ContextRegistries;

package/dist/runtime/context/registries.js

@@ -0,0 +1,84 @@
+import { createCardPile } from "../../cards/cardPile.js";
+import { RaceState } from "../../game/race.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+import { createTurnLoop } from "../../turn/turnLoop.js";
+/** @internal */
+export function createContextRegistries(signalNotify) {
+    const cardPiles = new Map();
+    function pile(id, config) {
+        const existing = cardPiles.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (config === undefined) {
+            throw new Error(`cardPile "${id}" has not been created yet; pass a config on first access`);
+        }
+        const created = notifyAfter(createCardPile(config), ["shuffle", "draw", "discard", "exhaust", "move", "reset"], signalNotify);
+        cardPiles.set(id, created);
+        return created;
+    }
+    const turnLoops = new Map();
+    function loop(id, config) {
+        const existing = turnLoops.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (config === undefined) {
+            throw new Error(`turn loop "${id}" has not been created yet; pass a config on first access`);
+        }
+        const raw = createTurnLoop(config);
+        const wrappedCommit = notifyAfter(raw.commit, ["submit", "expected", "commit", "discard", "clear"], signalNotify);
+        const wrapped = {
+            ...notifyAfter(raw, [
+                "setOrder",
+                "addParticipant",
+                "removeParticipant",
+                "advancePhase",
+                "advanceTurn",
+                "advanceRound",
+                "spend",
+                "gain",
+                "refill",
+                "restore",
+            ], signalNotify),
+            commit: wrappedCommit,
+        };
+        turnLoops.set(id, wrapped);
+        return wrapped;
+    }
+    class NotifyingRaceState extends RaceState {
+        addRacer(racerId, startTime) {
+            super.addRacer(racerId, startTime);
+            signalNotify();
+        }
+        removeRacer(racerId) {
+            super.removeRacer(racerId);
+            signalNotify();
+        }
+        reset() {
+            super.reset();
+            signalNotify();
+        }
+        eliminate(racerId) {
+            super.eliminate(racerId);
+            signalNotify();
+        }
+        update(now, positions) {
+            const raceEvents = super.update(now, positions);
+            if (raceEvents.length > 0)
+                signalNotify();
+            return raceEvents;
+        }
+    }
+    const raceStates = new Map();
+    function raceState(id, config) {
+        const existing = raceStates.get(id);
+        if (existing !== undefined)
+            return existing;
+        if (config === undefined) {
+            throw new Error(`race "${id}" has not been created yet; pass a config on first access`);
+        }
+        const created = new NotifyingRaceState(config);
+        raceStates.set(id, created);
+        return created;
+    }
+    return { pile, loop, raceState, cardPiles, turnLoops };
+}

package/dist/runtime/context/scene.d.ts

@@ -0,0 +1,59 @@
+import type { CombatSpatialDeps } from "../../combat/effects.js";
+import type { GameEvents } from "../../game/events.js";
+import { type BodyBind } from "../../scene/bodyBind.js";
+import { type EntityStatsApi, type StatValueMap } from "../../scene/entityStats.js";
+import { type EntityPosition, type EntityStore, type SceneEntity, type SpawnOptions } from "../../scene/entityStore.js";
+import { type Forms } from "../../scene/form.js";
+import { type EntityColliderSet } from "../../scene/colliders.js";
+import { type ObjectStore } from "../../scene/objectStore.js";
+import { type PaintLayer } from "../../scene/paintLayer.js";
+import { type SceneRaycastApi } from "../../scene/sceneRaycast.js";
+import { type SpatialApi } from "../../scene/spatial.js";
+import { type Targeting } from "../../scene/targeting.js";
+import type { TerrainField } from "../../world/terrain.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { GameContextContent, GameContextEntityEntry, GameContextModels, GameContextObjectEntry, MoveTowardCommitOptions, SceneObjectContext } from "../gameContext.js";
+/** @internal Live scene stores + spatial/collider/raycast wiring handed in by `createGameContext`. */
+export interface SceneSubsystemDeps {
+    content: GameContextContent;
+    signalNotify: () => void;
+    ground: TerrainField;
+    events: GameEvents;
+    /** Full sim clock — forms need `after` for timed shapeshift reversion. */
+    time: SimClock;
+    occluder?: (from: EntityPosition, to: EntityPosition) => boolean;
+    models?: GameContextModels;
+}
+/** @internal Always-on scene surface: entities, objects, colliders, spatial, raycast, targeting. */
+export interface SceneSubsystem {
+    entities: EntityStore;
+    objects: ObjectStore;
+    statsByInstance: Map<string, StatValueMap>;
+    entityStats: EntityStatsApi;
+    ensureInstanceStats: (instanceId: string) => StatValueMap;
+    catalogEntry: (instanceId: string) => GameContextEntityEntry | null | undefined;
+    catalogObject: (instanceId: string) => GameContextObjectEntry | null | undefined;
+    spatial: SpatialApi;
+    combatSpatial: CombatSpatialDeps;
+    sceneRaycast: SceneRaycastApi;
+    targeting: Targeting;
+    entityColliders: Map<string, EntityColliderSet>;
+    objectColliders: Map<string, EntityColliderSet>;
+    entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    entityVisualScaleOf: (instanceId: string) => number;
+    forms: Forms;
+    paintLayer: PaintLayer;
+    spawnEntity: (name: string, spawnOptions?: SpawnOptions) => string;
+    despawnEntity: (instanceId: string) => boolean;
+    moveEntityTowardCommit: (instanceId: string, target: EntityPosition | string, options: MoveTowardCommitOptions) => EntityPosition | null;
+    resetAllToSpawn: (filter?: (entity: SceneEntity) => boolean) => number;
+    bind: (key: string) => BodyBind;
+    sceneObjects: SceneObjectContext;
+    /** Install post-spawn side effects (death.revive) after combat is constructed. */
+    setOnAfterSpawn: (fn: (instanceId: string) => void) => void;
+    /** Install post-despawn side effects (pose.clear) after player is constructed. */
+    setOnAfterDespawn: (fn: (instanceId: string) => void) => void;
+}
+/** @internal */
+export declare function createSceneSubsystem(d: SceneSubsystemDeps): SceneSubsystem;