@jgengine/core 0.10.0 → 0.12.0

package/dist/rules/triggeredRules.js

@@ -0,0 +1,241 @@
+/**
+ * The reusable bridge from typed runtime events to effects. A triggered rule is pure data — which
+ * event it listens to, a declarative predicate over the event facts, how the affected target is
+ * resolved, an effect *reference* (never a callback), and how the resulting effect is gated, lived,
+ * and stacked. Affixes, talents, perks, quests, achievements, environment rules, and reactive AI all
+ * subscribe through this one seam instead of owning parallel trigger runtimes.
+ *
+ * Core stays decoupled from any specific effect system: `dispatch` returns provenance-rich firings
+ * and the game applies them to whatever effect/stat system it owns. Gate state (cooldowns, rate
+ * windows, remaining charges) and active timed effects serialize cleanly so future triggers survive
+ * save/load.
+ */
+import { evaluatePredicate, readPath } from "./predicate.js";
+function roleId(event, role, owner) {
+    switch (role) {
+        case "subject":
+            return event.subject;
+        case "object":
+            return event.object;
+        case "source":
+            return event.source;
+        case "owner":
+            return owner;
+    }
+}
+function resolveTarget(rule, event) {
+    const selector = rule.target ?? { role: "subject" };
+    if ("literal" in selector)
+        return selector.literal;
+    if ("path" in selector) {
+        const value = readPath(event.facts ?? {}, selector.path);
+        return typeof value === "string" ? value : undefined;
+    }
+    return roleId(event, selector.role, rule.owner);
+}
+function cooldownKey(ruleId, target) {
+    return `${ruleId}\u0000${target}`;
+}
+/**
+ * Create an empty triggered-rule engine. Rules are added as data; dispatching an event returns the
+ * firings the caller applies to its own effect system. Time is caller-supplied (`now` in ms), so the
+ * engine is deterministic and drives equally from a fixed-step loop or a save-restored timeline.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export function createTriggeredRuleEngine(rules = []) {
+    const ruleList = [];
+    const ruleIndex = new Map();
+    const remainingCharges = new Map();
+    const lastFire = new Map();
+    const fireWindows = new Map();
+    let active = [];
+    let seq = 0;
+    function indexRules() {
+        ruleIndex.clear();
+        for (let i = 0; i < ruleList.length; i++)
+            ruleIndex.set(ruleList[i].id, i);
+    }
+    function add(rule) {
+        const existing = ruleIndex.get(rule.id);
+        if (existing !== undefined)
+            ruleList[existing] = rule;
+        else
+            ruleList.push(rule);
+        indexRules();
+        if (rule.charges !== undefined)
+            remainingCharges.set(rule.id, rule.charges);
+        else
+            remainingCharges.delete(rule.id);
+    }
+    for (const rule of rules)
+        add(rule);
+    function dropRuleState(ruleId) {
+        remainingCharges.delete(ruleId);
+        fireWindows.delete(ruleId);
+        for (const key of [...lastFire.keys()]) {
+            if (key.startsWith(`${ruleId}\u0000`))
+                lastFire.delete(key);
+        }
+        active = active.filter((instance) => instance.ruleId !== ruleId);
+    }
+    function passesRate(rule, now) {
+        if (rule.rateLimit === undefined)
+            return true;
+        const window = fireWindows.get(rule.id) ?? [];
+        const cutoff = now - rule.rateLimit.windowMs;
+        const kept = window.filter((stamp) => stamp > cutoff);
+        fireWindows.set(rule.id, kept);
+        return kept.length < rule.rateLimit.count;
+    }
+    function recordFire(rule, target, now) {
+        lastFire.set(cooldownKey(rule.id, target), now);
+        if (rule.rateLimit !== undefined) {
+            const window = fireWindows.get(rule.id) ?? [];
+            window.push(now);
+            fireWindows.set(rule.id, window);
+        }
+        if (rule.charges !== undefined) {
+            remainingCharges.set(rule.id, (remainingCharges.get(rule.id) ?? 0) - 1);
+        }
+    }
+    function applyTimed(rule, target, now) {
+        const duration = rule.durationMs;
+        const policy = rule.stacking ?? "refresh";
+        const expiresAt = now + duration;
+        if (policy !== "independent") {
+            const current = active.find((instance) => instance.ruleId === rule.id && instance.target === target);
+            if (current !== undefined) {
+                if (policy === "ignore")
+                    return { blocked: "stack-ignored" };
+                const stacks = policy === "stack" ? Math.min(current.stacks + 1, Math.max(1, rule.maxStacks ?? 1)) : 1;
+                const updated = { ...current, expiresAt, stacks, appliedAt: now };
+                active = active.map((instance) => (instance === current ? updated : instance));
+                return { instanceId: updated.instanceId, stacks };
+            }
+        }
+        const instanceId = `${rule.id}#${seq++}`;
+        active.push({
+            instanceId,
+            ruleId: rule.id,
+            effectId: rule.effect.id,
+            owner: rule.owner,
+            target,
+            params: rule.effect.params,
+            appliedAt: now,
+            expiresAt,
+            stacks: 1,
+        });
+        return { instanceId, stacks: 1 };
+    }
+    function evaluate(rule, event, now) {
+        const base = { ruleId: rule.id, event: event.type, owner: rule.owner, effect: rule.effect, at: now };
+        if (!evaluatePredicate(rule.when, event.facts ?? {}))
+            return { ...base, target: "", blocked: "predicate" };
+        const target = resolveTarget(rule, event);
+        if (target === undefined || target === "")
+            return { ...base, target: "", blocked: "no-target" };
+        if (rule.charges !== undefined && (remainingCharges.get(rule.id) ?? 0) <= 0)
+            return { ...base, target, blocked: "no-charges" };
+        if (rule.cooldownMs !== undefined) {
+            const last = lastFire.get(cooldownKey(rule.id, target));
+            if (last !== undefined && now - last < rule.cooldownMs)
+                return { ...base, target, blocked: "cooldown" };
+        }
+        if (!passesRate(rule, now))
+            return { ...base, target, blocked: "rate-limit" };
+        if (rule.durationMs !== undefined) {
+            const outcome = applyTimed(rule, target, now);
+            if ("blocked" in outcome)
+                return { ...base, target, blocked: outcome.blocked };
+            recordFire(rule, target, now);
+            return { ...base, target, instanceId: outcome.instanceId, stacks: outcome.stacks };
+        }
+        recordFire(rule, target, now);
+        return { ...base, target };
+    }
+    return {
+        add,
+        remove(ruleId) {
+            const index = ruleIndex.get(ruleId);
+            if (index === undefined)
+                return;
+            ruleList.splice(index, 1);
+            indexRules();
+            dropRuleState(ruleId);
+        },
+        removeByOwner(owner) {
+            const removed = ruleList.filter((rule) => rule.owner === owner).map((rule) => rule.id);
+            if (removed.length === 0) {
+                active = active.filter((instance) => instance.owner !== owner);
+                return;
+            }
+            for (let i = ruleList.length - 1; i >= 0; i--) {
+                if (ruleList[i].owner === owner)
+                    ruleList.splice(i, 1);
+            }
+            indexRules();
+            for (const ruleId of removed)
+                dropRuleState(ruleId);
+            active = active.filter((instance) => instance.owner !== owner);
+        },
+        rules: () => ruleList.slice(),
+        dispatch(event, now) {
+            const firings = [];
+            for (const rule of ruleList) {
+                if (rule.event !== event.type)
+                    continue;
+                firings.push(evaluate(rule, event, now));
+            }
+            return firings;
+        },
+        tick(now) {
+            const expired = active.filter((instance) => instance.expiresAt <= now);
+            if (expired.length > 0)
+                active = active.filter((instance) => instance.expiresAt > now);
+            return expired;
+        },
+        active: () => active.slice(),
+        activeFor: (target) => active.filter((instance) => instance.target === target),
+        clearActive() {
+            active = [];
+        },
+        reset() {
+            remainingCharges.clear();
+            lastFire.clear();
+            fireWindows.clear();
+            active = [];
+            for (const rule of ruleList) {
+                if (rule.charges !== undefined)
+                    remainingCharges.set(rule.id, rule.charges);
+            }
+        },
+        snapshot() {
+            return {
+                seq,
+                rules: ruleList.map((rule) => ({ ...rule })),
+                charges: Object.fromEntries(remainingCharges),
+                cooldowns: Object.fromEntries(lastFire),
+                windows: Object.fromEntries([...fireWindows].map(([id, stamps]) => [id, stamps.slice()])),
+                active: active.map((instance) => ({ ...instance })),
+            };
+        },
+        hydrate(state) {
+            ruleList.length = 0;
+            for (const rule of state.rules)
+                ruleList.push({ ...rule });
+            indexRules();
+            remainingCharges.clear();
+            for (const [id, value] of Object.entries(state.charges))
+                remainingCharges.set(id, value);
+            lastFire.clear();
+            for (const [key, value] of Object.entries(state.cooldowns))
+                lastFire.set(key, value);
+            fireWindows.clear();
+            for (const [id, stamps] of Object.entries(state.windows))
+                fireWindows.set(id, stamps.slice());
+            active = state.active.map((instance) => ({ ...instance }));
+            seq = state.seq;
+        },
+    };
+}

package/dist/runtime/adapter.d.ts

@@ -1,8 +1,14 @@
 export type MultiplayerTopology = "shared" | "lobbies" | "private";
 /**
- * Where the world simulation is authoritative. `"client"` (default) keeps the historical model — each client runs
- * its own `onTick` and syncs only presence/feeds/chat. `"server"` opts into host-authoritative replication: the
- * host runs the loop, and the shell mirrors the server's world into the local `ctx` instead of simulating locally.
+ * Where the world simulation is authoritative.
+ *
+ * - `"client"` (default when omitted) — **presence-only multiplayer**: each client runs its own `onTick` and
+ *   syncs presence / feeds / chat. Not competitive-safe; do not treat it as a shared sim.
+ * - `"server"` — host-authoritative world replication: the host runs the loop; the shell mirrors the host's
+ *   world into the local `ctx` instead of simulating locally.
+ *
+ * Prefer naming the product intent in game code: pass `authority: "server"` for shared worlds, leave unset or
+ * `"client"` only for co-op presence / lobbies that intentionally tick independently.
  */
 export type MultiplayerAuthority = "server" | "client";
 export type MultiplayerAdapterConfig = {
@@ -33,15 +39,36 @@ export type MultiplayerAdapterConfig = {
 } | {
     kind: "offline";
 };
+/**
+ * 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 declare function convex(config?: {
     topology?: MultiplayerTopology;
     authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/** Presence-only Convex transport — each client runs its own `onTick`; only presence/feeds/chat sync. Sugar for `convex({ ...config, authority: "client" })`. */
+export declare function convexPresence(config?: {
+    topology?: MultiplayerTopology;
+}): MultiplayerAdapterConfig;
+/**
+ * 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`.
+ *
+ * @capability multiplayer-ws server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
+ */
 export declare function ws(config?: {
     topology?: MultiplayerTopology;
     url?: string;
     authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/** Presence-only WebSocket transport — each client runs its own `onTick`; only presence/feeds/chat sync. Sugar for `ws({ ...config, authority: "client" })`. */
+export declare function wsPresence(config?: {
+    topology?: MultiplayerTopology;
+    url?: string;
+}): MultiplayerAdapterConfig;
 export declare function fly(config: {
     app: string;
     topology?: MultiplayerTopology;
@@ -53,6 +80,11 @@ export declare function socketIo(config?: {
     url?: string;
     authority?: MultiplayerAuthority;
 }): MultiplayerAdapterConfig;
+/**
+ * Serverless peer-to-peer (WebRTC) session — one peer hosts, friends join by room code.
+ *
+ * @capability multiplayer-p2p serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+ */
 export declare function p2p(config?: {
     topology?: MultiplayerTopology;
     room?: string;
@@ -66,6 +98,26 @@ export declare function lan(config?: {
 }): MultiplayerAdapterConfig;
 /** True when the adapter opts into host-authoritative world replication (`authority: "server"`). */
 export declare function isServerAuthoritative(multiplayer: unknown): boolean;
+/**
+ * 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 declare function resolveAuthority(multiplayer: unknown): MultiplayerAuthority | null;
+/**
+ * True when multiplayer is on but the world sim is not host-authoritative — presence/feeds/chat only.
+ * Equivalent to `resolveAuthority(m) === "client"`.
+ */
+export declare function isPresenceOnly(multiplayer: unknown): boolean;
+/** True for a single-player world — no adapter, or an explicit `offline()` one. Gates offline-only wiring like local whole-world save. */
+export declare function isOffline(multiplayer: unknown): boolean;
+/**
+ * Explicit single-player adapter. Solo games never need this — omitting `multiplayer` in the shell
+ * `defineGame` already defaults to offline; pass it only where an adapter value is structurally required.
+ *
+ * @capability multiplayer-offline explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+ */
 export declare function offline(): MultiplayerAdapterConfig;
 export declare function adapterOf(multiplayer: unknown): MultiplayerAdapterConfig | null;
 export declare function multiplayerAdapterKind(multiplayer: unknown): string | null;

package/dist/runtime/adapter.js

@@ -1,9 +1,29 @@
+/**
+ * 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`.
+ *
+ * @capability multiplayer-ws server-hosted shared world over WebSocket — `multiplayer: ws({ authority: "server" })`
+ */
 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",
@@ -15,6 +35,11 @@ export function fly(config) {
 export function socketIo(config) {
     return { kind: "socketio", topology: config?.topology ?? "shared", url: config?.url, authority: config?.authority };
 }
+/**
+ * Serverless peer-to-peer (WebRTC) session — one peer hosts, friends join by room code.
+ *
+ * @capability multiplayer-p2p serverless co-op over WebRTC — `multiplayer: p2p({ room })`
+ */
 export function p2p(config) {
     return { kind: "p2p", topology: config?.topology ?? "private", room: config?.room, authority: config?.authority };
 }
@@ -23,9 +48,40 @@ 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";
 }
+/**
+ * Explicit single-player adapter. Solo games never need this — omitting `multiplayer` in the shell
+ * `defineGame` already defaults to offline; pass it only where an adapter value is structurally required.
+ *
+ * @capability multiplayer-offline explicit solo adapter — omit `multiplayer` instead; offline is the shell default
+ */
 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/combat.d.ts

@@ -0,0 +1,51 @@
+import { type DeathSystem } from "../../combat/death.js";
+import { type CombatSpatialDeps, type EffectSystem } from "../../combat/effects.js";
+import { type ProjectileSystem } from "../../combat/projectiles.js";
+import type { PhysicsConfig } from "../../game/defineGame.js";
+import type { GameEvents } from "../../game/events.js";
+import { type VfxInstanceStore } from "../../game/vfxInstance.js";
+import type { LootRegistry } from "../../game/lootTable.js";
+import type { EntityColliderSet } from "../../scene/colliders.js";
+import type { EntityStore } from "../../scene/entityStore.js";
+import type { ObjectStore } from "../../scene/objectStore.js";
+import type { SceneRaycastApi } from "../../scene/sceneRaycast.js";
+import type { WeaponStats } from "../../item/weapon.js";
+import type { SimClock } from "../../time/simClock.js";
+import type { WorldItemRecord, WorldItemSpawnInput } from "../../game/worldItem.js";
+import type { GameContextContent, GameContextEntityEntry, GameContextLoot } from "../gameContext.js";
+import { type CombatFx } from "./combatFx.js";
+/** @internal Wiring combat needs from the live scene, loot, and command seams. */
+export interface CombatSubsystemDeps {
+    content: GameContextContent;
+    signalNotify: () => void;
+    now: () => number;
+    events: GameEvents;
+    time: SimClock;
+    entities: EntityStore;
+    objects: ObjectStore;
+    combatSpatial: CombatSpatialDeps;
+    sceneRaycast: SceneRaycastApi;
+    entityCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    objectCollidersOf: (instanceId: string) => EntityColliderSet | null;
+    catalogEntry: (instanceId: string) => GameContextEntityEntry | null | undefined;
+    statsByInstance: Map<string, import("../../scene/entityStats.js").StatValueMap>;
+    weapon: WeaponStats;
+    loot: GameContextLoot;
+    lootRegistry: LootRegistry;
+    spawnWorldItem: (input: WorldItemSpawnInput) => WorldItemRecord;
+    despawnEntity: (instanceId: string) => boolean;
+    runCommand: (name: string, args: unknown) => void;
+    localUserId: string;
+    physics?: PhysicsConfig;
+}
+/** @internal Effects, projectiles, death, and combat presentation surface. */
+export interface CombatSubsystem {
+    death: DeathSystem;
+    effects: EffectSystem;
+    floatingEffects: EffectSystem;
+    projectiles: ProjectileSystem;
+    combatFx: CombatFx;
+    vfxInstances: VfxInstanceStore;
+}
+/** @internal */
+export declare function createCombatSubsystem(d: CombatSubsystemDeps): CombatSubsystem;

package/dist/runtime/context/combat.js

@@ -0,0 +1,130 @@
+import { createDeathSystem, deathReasonFromEffect } from "../../combat/death.js";
+import { createEffectSystem, } from "../../combat/effects.js";
+import { createProjectileSystem } from "../../combat/projectiles.js";
+import { createVfxInstanceStore } from "../../game/vfxInstance.js";
+import { notifyAfter } from "../../store/changeSignal.js";
+import { createCombatFx } from "./combatFx.js";
+import { applyLethalLoot, isLocalPlayerKill } from "./deathLoot.js";
+/** @internal */
+export function createCombatSubsystem(d) {
+    const { content, signalNotify, now, events, time, entities, objects, combatSpatial, sceneRaycast, entityCollidersOf, objectCollidersOf, catalogEntry, statsByInstance, weapon, loot, lootRegistry, spawnWorldItem, despawnEntity, runCommand, localUserId, } = d;
+    const death = createDeathSystem({
+        resolveOnDeath: (instanceId) => catalogEntry(instanceId)?.onDeath,
+        resolveIdentity(instanceId) {
+            const entity = entities.get(instanceId);
+            if (entity === null)
+                return null;
+            return {
+                catalogId: entity.name,
+                position: [entity.position[0], entity.position[1], entity.position[2]],
+            };
+        },
+        loot: { roll: (tableId) => (lootRegistry.has(tableId) ? lootRegistry.roll(tableId) : []) },
+        events,
+        runCommand(name, args) {
+            runCommand(name, args);
+        },
+        despawn(instanceId) {
+            despawnEntity(instanceId);
+        },
+    });
+    const effects = notifyAfter(createEffectSystem({
+        resolveReceive: (instanceId) => catalogEntry(instanceId)?.receive,
+        resolveStats: (instanceId) => statsByInstance.get(instanceId),
+        getStat: weapon.getStat,
+        spatial: combatSpatial,
+        onLethal(instanceId, lethalCtx) {
+            // Capture identity + onDeath *before* resolveDeath despawns the entity.
+            const dyingEntity = entities.get(instanceId);
+            const catalogId = dyingEntity?.name;
+            const position = dyingEntity?.position;
+            const onDeath = catalogEntry(instanceId)?.onDeath;
+            const reason = deathReasonFromEffect({
+                ...lethalCtx,
+                userIdOf: (id) => (id === localUserId ? localUserId : undefined),
+            });
+            const resolution = death.resolveDeath(instanceId, reason);
+            if (resolution.status !== "resolved")
+                return;
+            applyLethalLoot({
+                drops: resolution.drops,
+                grantToLocalPlayer: isLocalPlayerKill(lethalCtx, localUserId),
+                onDeath,
+                position,
+                catalogId,
+                content,
+                spawnWorldItem,
+                grantToPlayer: loot.grantToPlayer,
+                localUserId,
+            });
+        },
+    }), ["applyEffect"], signalNotify);
+    const combatFx = createCombatFx({
+        entities,
+        events,
+        time,
+        applyEffect: (input) => effects.applyEffect(input),
+    });
+    const vfxInstances = createVfxInstanceStore({
+        onOp: (op) => events.emit("combat.vfxInstance", op),
+        now: () => time.now() * 1000,
+    });
+    const floatingEffects = {
+        canReceive: effects.canReceive,
+        preview: effects.preview,
+        applyEffect: combatFx.applyEffectAndFloat,
+    };
+    const projectileObstacles = d.physics?.projectileObstacles === true;
+    const projectileFilterFor = (filter) => ({
+        entities: true,
+        objects: projectileObstacles,
+        terrain: false,
+        walls: projectileObstacles,
+        ...filter,
+    });
+    const projectileSceneRaycast = {
+        raycast(input) {
+            return sceneRaycast.raycast({ ...input, filter: projectileFilterFor(input.filter) });
+        },
+        raycastAll(input) {
+            return sceneRaycast.raycastAll({ ...input, filter: projectileFilterFor(input.filter) });
+        },
+    };
+    const projectiles = notifyAfter(createProjectileSystem({
+        effects: floatingEffects,
+        spatial: combatSpatial,
+        getStat: weapon.getStat,
+        sceneRaycast: projectileSceneRaycast,
+        objects: projectileObstacles
+            ? {
+                list: () => objects.list(),
+                inBox: (min, max) => objects.inBox(min, max),
+                halfExtents: (catalogId) => {
+                    const half = content.objectById?.(catalogId)?.halfExtents;
+                    return half === undefined ? null : [half[0], half[1], half[2]];
+                },
+                collidersOf: objectCollidersOf,
+            }
+            : undefined,
+        entityCollidersOf,
+        rotationYOf: (instanceId) => entities.get(instanceId)?.rotationY,
+        now,
+        onSettle(report) {
+            events.emit("projectile.settled", {
+                from: report.from,
+                origin: [report.origin[0], report.origin[1], report.origin[2]],
+                at: [report.at[0], report.at[1], report.at[2]],
+                effect: report.effect,
+                hit: report.hit,
+            });
+        },
+    }), ["fireProjectile", "settleProjectile"], signalNotify);
+    return {
+        death,
+        effects,
+        floatingEffects,
+        projectiles,
+        combatFx,
+        vfxInstances,
+    };
+}

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;