@jgengine/core 0.10.0 → 0.11.0

package/dist/runtime/adapter.js

@@ -1,9 +1,27 @@
+/**
+ * Convex transport. Omitting `authority` (or passing `"client"`) is **presence-only** — prefer
+ * `convexPresence()` to name that intent explicitly. Pass `{ authority: "server" }` for a shared,
+ * host-authoritative world — see `examples/HOSTED.md`.
+ */
 export function convex(config) {
     return { kind: "convex", topology: config?.topology ?? "shared", authority: config?.authority };
 }
+/** Presence-only Convex transport — each client runs its own `onTick`; only presence/feeds/chat sync. Sugar for `convex({ ...config, authority: "client" })`. */
+export function convexPresence(config) {
+    return { kind: "convex", topology: config?.topology ?? "shared", authority: "client" };
+}
+/**
+ * WebSocket transport. Omitting `authority` (or passing `"client"`) is **presence-only** — prefer
+ * `wsPresence()` to name that intent explicitly. Pass `{ authority: "server" }` for a shared,
+ * host-authoritative world — see `examples/HOSTED.md`.
+ */
 export function ws(config) {
     return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
+/** Presence-only WebSocket transport — each client runs its own `onTick`; only presence/feeds/chat sync. Sugar for `ws({ ...config, authority: "client" })`. */
+export function wsPresence(config) {
+    return { kind: "ws", topology: config?.topology ?? "shared", url: config?.url, authority: "client" };
+}
 export function fly(config) {
     return {
         kind: "ws",
@@ -23,8 +41,33 @@ export function lan(config) {
 }
 /** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
 export function isServerAuthoritative(multiplayer) {
+    return resolveAuthority(multiplayer) === "server";
+}
+/**
+ * Resolved authority for a multiplayer config.
+ * - `offline` / missing adapter → `null` (single-player; not multiplayer authority).
+ * - unset or `"client"` → `"client"` (presence-only; each client ticks).
+ * - `"server"` → host-authoritative shared sim.
+ */
+export function resolveAuthority(multiplayer) {
+    const adapter = adapterOf(multiplayer);
+    if (adapter === null || adapter.kind === "offline")
+        return null;
+    if ("authority" in adapter && adapter.authority === "server")
+        return "server";
+    return "client";
+}
+/**
+ * True when multiplayer is on but the world sim is not host-authoritative — presence/feeds/chat only.
+ * Equivalent to `resolveAuthority(m) === "client"`.
+ */
+export function isPresenceOnly(multiplayer) {
+    return resolveAuthority(multiplayer) === "client";
+}
+/** True for a single-player world — no adapter, or an explicit `offline()` one. Gates offline-only wiring like local whole-world save. */
+export function isOffline(multiplayer) {
     const adapter = adapterOf(multiplayer);
-    return adapter !== null && "authority" in adapter && adapter.authority === "server";
+    return adapter === null || adapter.kind === "offline";
 }
 export function offline() {
     return { kind: "offline" };

package/dist/runtime/cameraDirector.d.ts

@@ -12,4 +12,5 @@ export interface CameraDirector {
     chaseTuning(): ChaseCameraTuning | null;
     subscribe(listener: () => void): () => void;
 }
+/** @internal */
 export declare function createCameraDirector(): CameraDirector;

package/dist/runtime/cameraDirector.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createCameraDirector() {
     const listeners = new Set();
     let followEntity = undefined;

package/dist/runtime/commandRunner.d.ts

@@ -12,4 +12,5 @@ export type RunCommandResult = {
     ok: false;
     reason: string;
 };
+/** @internal */
 export declare function runCommand<TInput>(snapshot: import("./snapshot.js").GameRuntimeSnapshot, commands: Record<string, CommandDef<TInput>>, commandName: string, input: TInput, actorUserId: string): RunCommandResult;

package/dist/runtime/commandRunner.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function runCommand(snapshot, commands, commandName, input, actorUserId) {
     const command = commands[commandName];
     if (!command) {

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

@@ -0,0 +1,23 @@
+import type { EffectInput, EffectResult } from "../../combat/effects.js";
+import { type HitReaction } from "../../combat/hitReaction.js";
+import type { GameEvents } from "../../game/events.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { FloatTextInput, HitReactionInput, TelegraphInput, VfxInput } from "../gameContext.js";
+/** @internal What the combat-presentation helpers need from the live context: entity poses, the event bus, the sim clock (telegraph windups), and the raw effect application. */
+export interface CombatFxDeps {
+    entities: EntityStore;
+    events: GameEvents;
+    time: SimClock;
+    applyEffect: (input: EffectInput) => EffectResult[];
+}
+/** @internal Combat presentation surface registered under `ctx.scene.entity`: float text, VFX bursts, telegraphs, hit reactions, and the effect wrapper that emits damage/heal float text. */
+export interface CombatFx {
+    emitFloatText(input: FloatTextInput): void;
+    emitVfx(input: VfxInput): void;
+    fireTelegraph(input: TelegraphInput): () => void;
+    applyHitReaction(input: HitReactionInput): HitReaction | null;
+    applyEffectAndFloat(input: EffectInput): EffectResult[];
+}
+/** @internal */
+export declare function createCombatFx(d: CombatFxDeps): CombatFx;

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

@@ -0,0 +1,21 @@
+import type { GameEvents } from "../../game/events.js";
+import { type WorldItemRecord, type WorldItemSpawnInput, type WorldItemStore } from "../../game/worldItem.js";
+import type { Drop } from "../../game/lootTable.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { WorldItemPickupResult } from "../gameContext.js";
+/** @internal What the ground-item surface needs from the live context: entity spawn/despawn, the event bus, loot granting, and change notification. */
+export interface WorldItemContextDeps {
+    entities: EntityStore;
+    events: GameEvents;
+    despawnEntity: (instanceId: string) => boolean;
+    grantToPlayer: (userId: string, drops: Drop[], source?: string) => void;
+    signalNotify: () => void;
+}
+/** @internal The `ctx.scene.worldItem` wiring: the reactive store plus the spawn/pickup verbs that emit `worldItem.*` events and route pickups through loot. */
+export interface WorldItemContext {
+    worldItems: WorldItemStore;
+    spawnWorldItem(input: WorldItemSpawnInput): WorldItemRecord;
+    pickupWorldItem(instanceId: string, userId: string): WorldItemPickupResult;
+}
+/** @internal */
+export declare function createWorldItemContext(d: WorldItemContextDeps): WorldItemContext;

package/dist/runtime/context/worldItems.js

@@ -0,0 +1,37 @@
+import { createWorldItemStore, WORLD_ITEM_ENTITY_NAME, } from "../../game/worldItem.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+/** @internal */
+export function createWorldItemContext(d) {
+    const worldItems = notifyAfter(createWorldItemStore({
+        spawnEntity: (position) => d.entities.spawn(WORLD_ITEM_ENTITY_NAME, { position, role: "prop" }),
+        despawnEntity: d.despawnEntity,
+        resolvePosition: (instanceId) => d.entities.get(instanceId)?.position,
+    }), ["spawn", "take", "remove"], d.signalNotify);
+    function spawnWorldItem(input) {
+        const record = worldItems.spawn(input);
+        d.events.emit("worldItem.dropped", {
+            instanceId: record.instanceId,
+            itemId: record.itemId,
+            rarity: record.rarity,
+            count: record.count,
+            position: [input.position[0], input.position[1], input.position[2]],
+            ...(record.source !== undefined ? { source: record.source } : {}),
+        });
+        return record;
+    }
+    function pickupWorldItem(instanceId, userId) {
+        const record = worldItems.take(instanceId);
+        if (record === null)
+            return { status: "rejected", reason: "not-found" };
+        d.grantToPlayer(userId, [{ item: record.itemId, count: record.count }], "worldItem.pickup");
+        d.events.emit("worldItem.picked_up", {
+            instanceId,
+            userId,
+            itemId: record.itemId,
+            rarity: record.rarity,
+            count: record.count,
+        });
+        return { status: "ok", record };
+    }
+    return { worldItems, spawnWorldItem, pickupWorldItem };
+}

package/dist/runtime/descriptors/baseline.d.ts

@@ -0,0 +1,48 @@
+import type { WalletState } from "../../economy/wallet.js";
+import type { GameFeed } from "../../game/feed.js";
+import type { InventorySet } from "../../inventory/inventoryModel.js";
+import type { PoseState } from "../../movement/poseState.js";
+import { type StatValueMap } from "../../scene/entityStats.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { Possession } from "../../scene/possession.js";
+import type { ObservableKeyedStore } from "../../store/observableKeyedStore.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { MotionIntents } from "../motionIntents.js";
+import type { SnapshotModule } from "../worldSnapshot.js";
+/** @internal The live always-on subsystems the baseline descriptors serialize — handed in by `createGameContext`. */
+export interface BaselineDeps {
+    signalNotify: () => void;
+    entities: EntityStore;
+    statsByInstance: Map<string, StatValueMap>;
+    store: ObservableKeyedStore<unknown>;
+    feed: GameFeed;
+    inventoryIds: readonly string[];
+    inventoryByUser: ReadonlyMap<string, InventorySet<string>>;
+    inventoryFor: (userId: string) => InventorySet<string>;
+    wallets: Map<string, WalletState>;
+    time: SimClock;
+    pose: PoseState;
+    possession: Possession;
+    motionByUser: ReadonlyMap<string, MotionIntents>;
+    motionFor: (userId: string) => MotionIntents;
+}
+/** @internal What an always-on baseline descriptor contributes: a replication module, a save-only module, or both. */
+export interface BaselineBuild {
+    /** Registered into the host→client replication set (`ctx.snapshot`/`ctx.hydrate`), and therefore also into the save set. */
+    replicate?: SnapshotModule;
+    /** Registered into the whole-world save-only set (`ctx.game.save`) — persisted but never sent to clients. */
+    save?: SnapshotModule;
+}
+/**
+ * Always-on counterpart to {@link featureDescriptors}: each baseline subsystem (entities, stats,
+ * store, feed, inventory, economy, time, pose, possession, motion) owns its own serialization here
+ * instead of `createGameContext` hand-maintaining two distant module arrays. Order is
+ * load-bearing — it fixes the snapshot key order, so it must stay stable.
+ * @internal
+ */
+export interface BaselineDescriptor {
+    readonly key: string;
+    create(deps: BaselineDeps): BaselineBuild;
+}
+/** @internal */
+export declare const baselineDescriptors: readonly BaselineDescriptor[];

package/dist/runtime/descriptors/baseline.js

@@ -0,0 +1,134 @@
+import { hydrateEntityStats, snapshotEntityStats, } from "../../scene/entityStats.js";
+/** @internal */
+export const baselineDescriptors = [
+    {
+        key: "entities",
+        create: (d) => ({
+            replicate: {
+                key: "entities",
+                snapshot: () => d.entities.snapshot(),
+                hydrate: (data) => d.entities.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "stats",
+        create: (d) => ({
+            replicate: {
+                key: "stats",
+                snapshot: () => snapshotEntityStats(d.statsByInstance),
+                hydrate: (data) => hydrateEntityStats(d.statsByInstance, data),
+            },
+        }),
+    },
+    {
+        key: "store",
+        create: (d) => ({
+            replicate: {
+                key: "store",
+                snapshot: () => d.store.snapshot(),
+                hydrate: (data) => d.store.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "feed",
+        create: (d) => ({
+            replicate: {
+                key: "feed",
+                snapshot: () => d.feed.snapshot(),
+                hydrate: (data) => d.feed.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "inventory",
+        create: (d) => ({
+            replicate: {
+                key: "inventory",
+                snapshot: () => {
+                    const byUser = {};
+                    for (const [userId, set] of d.inventoryByUser) {
+                        const states = {};
+                        for (const inventoryId of d.inventoryIds)
+                            states[inventoryId] = set.state(inventoryId);
+                        byUser[userId] = states;
+                    }
+                    return byUser;
+                },
+                hydrate: (data) => {
+                    for (const [userId, states] of Object.entries(data)) {
+                        const set = d.inventoryFor(userId);
+                        for (const [inventoryId, state] of Object.entries(states))
+                            set.replaceState(inventoryId, state);
+                    }
+                },
+            },
+        }),
+    },
+    {
+        key: "economy",
+        create: (d) => ({
+            save: {
+                key: "economy",
+                snapshot: () => Object.fromEntries(d.wallets),
+                hydrate: (data) => {
+                    d.wallets.clear();
+                    for (const [userId, state] of Object.entries(data)) {
+                        d.wallets.set(userId, state);
+                    }
+                    d.signalNotify();
+                },
+            },
+        }),
+    },
+    {
+        key: "time",
+        create: (d) => ({
+            save: {
+                key: "time",
+                snapshot: () => d.time.snapshot(),
+                hydrate: (data) => d.time.hydrate(data),
+            },
+        }),
+    },
+    {
+        key: "pose",
+        create: (d) => ({
+            save: {
+                key: "pose",
+                snapshot: () => d.pose.snapshotAll(),
+                hydrate: (data) => d.pose.hydrateAll(data),
+            },
+        }),
+    },
+    {
+        key: "possession",
+        create: (d) => ({
+            save: {
+                key: "possession",
+                snapshot: () => d.possession.snapshotAll(),
+                hydrate: (data) => d.possession.hydrateAll(data),
+            },
+        }),
+    },
+    {
+        key: "motion",
+        create: (d) => ({
+            save: {
+                key: "motion",
+                snapshot: () => {
+                    const out = {};
+                    for (const [userId, queue] of d.motionByUser)
+                        out[userId] = queue.snapshot();
+                    return out;
+                },
+                hydrate: (data) => {
+                    for (const [userId, batch] of Object.entries(data)) {
+                        d.motionFor(userId).hydrate(batch);
+                    }
+                },
+            },
+        }),
+    },
+];