@jgengine/core 0.11.0 → 0.13.0

package/dist/physics/vehicleObstacles.d.ts

@@ -0,0 +1,44 @@
+import { type CollisionObstacle } from "../movement/movementModel.js";
+/**
+ * A single blocked-move event a car can react to (#1051): crash damage, screen shake, a metal-crunch
+ * cue. Reported once, when a move is first vetoed, then consumed by {@link VehicleObstacleClamp.takeImpact}.
+ */
+export interface VehicleImpact {
+    /** Speed (world units/s) the car was carrying *into* the obstacle at the moment the move was blocked. */
+    closingSpeed: number;
+    /** Unit push-back direction — points from the struck surface back toward the car. */
+    normal: readonly [number, number];
+    /** Index into the obstacle set passed for the blocking tick. */
+    obstacleIndex: number;
+}
+/**
+ * A planar move clamp for a kinematic car: feed {@link clampMove} to a vehicle's `clampMove` hook so
+ * an attempted XZ displacement slides along world solids instead of driving through them, and read
+ * {@link takeImpact} once per tick for the crash it produced.
+ */
+export interface VehicleObstacleClamp {
+    /** Resolve an attempted `from`→`to` XZ move to the destination actually allowed (slide-along). */
+    clampMove(from: readonly [number, number], to: readonly [number, number]): readonly [number, number];
+    /** Impact recorded since last take, consumed on read (null when none). Closing speed is the velocity component into the obstacle at block time, units/s. */
+    takeImpact(): VehicleImpact | null;
+}
+/**
+ * Build a slide-along move clamp for a kinematic car (#1051). `obstacles` is sampled fresh each tick —
+ * the caller hands back the already-filtered set of solids near the car — and `dt` supplies the current
+ * tick length so a blocked move's lost displacement converts to a closing speed. `radius` inflates each
+ * obstacle footprint by the car's body radius (default {@link DEFAULT_VEHICLE_RADIUS}).
+ *
+ * The slide itself is delegated to {@link resolveObstacleStep} so cars and pedestrians share one proven
+ * axis-separated resolver: a shallow graze keeps its tangential run and only the into-wall component is
+ * shed, a head-on zeroes forward progress. When any component is shed the largest such block this tick is
+ * kept as a {@link VehicleImpact}; {@link VehicleObstacleClamp.takeImpact} returns and clears it so a hit
+ * fires exactly once. The happy path (no solids near) is a zero-allocation passthrough returning `to`.
+ */
+export declare function createVehicleObstacleClamp(options: {
+    /** Solids near the car this tick (already filtered to the relevant, solid set). */
+    obstacles: () => readonly CollisionObstacle[];
+    /** Vehicle body radius (units). Default {@link DEFAULT_VEHICLE_RADIUS}. */
+    radius?: number;
+    /** Current tick dt (seconds) — the divisor turning shed displacement into closing speed. */
+    dt: () => number;
+}): VehicleObstacleClamp;

package/dist/physics/vehicleObstacles.js

@@ -0,0 +1,115 @@
+import { resolveObstacleStep } from "../movement/movementModel.js";
+/** Matches the unit-box default {@link resolveObstacleStep} applies to obstacles without explicit extents. */
+const DEFAULT_OBSTACLE_HALF_EXTENTS = [0.5, 0.5, 0.5];
+/** Default vehicle body radius (units) inflating obstacle footprints; a compact hatchback-ish disc. */
+const DEFAULT_VEHICLE_RADIUS = 1.4;
+/**
+ * Y the car body is pinned to when handing solids to {@link resolveObstacleStep}. That stepper gates
+ * each obstacle by a 1.8-tall pedestrian span around `current[1]`; centring every pre-filtered solid
+ * on this value makes the gate always admit them, so collision is purely horizontal and the car hits
+ * world solids at any ground elevation (bridges, hills) even though the clamp only knows XZ.
+ */
+const CAR_BODY_MID_Y = 0.9;
+/** Below this the returned step is treated as unblocked (float-noise slack), so no phantom impacts fire. */
+const BLOCK_EPSILON = 1e-6;
+/**
+ * Build a slide-along move clamp for a kinematic car (#1051). `obstacles` is sampled fresh each tick —
+ * the caller hands back the already-filtered set of solids near the car — and `dt` supplies the current
+ * tick length so a blocked move's lost displacement converts to a closing speed. `radius` inflates each
+ * obstacle footprint by the car's body radius (default {@link DEFAULT_VEHICLE_RADIUS}).
+ *
+ * The slide itself is delegated to {@link resolveObstacleStep} so cars and pedestrians share one proven
+ * axis-separated resolver: a shallow graze keeps its tangential run and only the into-wall component is
+ * shed, a head-on zeroes forward progress. When any component is shed the largest such block this tick is
+ * kept as a {@link VehicleImpact}; {@link VehicleObstacleClamp.takeImpact} returns and clears it so a hit
+ * fires exactly once. The happy path (no solids near) is a zero-allocation passthrough returning `to`.
+ */
+export function createVehicleObstacleClamp(options) {
+    const radius = options.radius ?? DEFAULT_VEHICLE_RADIUS;
+    // Grow-only scratch of Y-normalised solids, reused across ticks so a sustained crash allocates nothing
+    // after warm-up. Per-clamp (closure-local) so concurrent cars never share it.
+    const scratch = [];
+    let pending = null;
+    function vehicleView(source) {
+        const n = source.length;
+        for (let i = 0; i < n; i += 1) {
+            let entry = scratch[i];
+            if (entry === undefined) {
+                entry = { position: [0, 0, 0] };
+                scratch[i] = entry;
+            }
+            const from = source[i];
+            entry.position[0] = from.position[0];
+            entry.position[1] = CAR_BODY_MID_Y;
+            entry.position[2] = from.position[2];
+            entry.halfExtents = from.halfExtents;
+        }
+        if (scratch.length > n)
+            scratch.length = n;
+        return scratch;
+    }
+    /** Obstacle the attempted endpoint penetrates deepest (its inflated footprint), else nearest centre. */
+    function blockingIndex(source, tx, tz) {
+        let bestIndex = -1;
+        let bestDepth = -Number.POSITIVE_INFINITY;
+        let fallbackIndex = 0;
+        let fallbackDistSq = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < source.length; i += 1) {
+            const o = source[i];
+            const half = o.halfExtents ?? DEFAULT_OBSTACLE_HALF_EXTENTS;
+            const ex = half[0] + radius;
+            const ez = half[2] + radius;
+            const minX = o.position[0] - ex;
+            const maxX = o.position[0] + ex;
+            const minZ = o.position[2] - ez;
+            const maxZ = o.position[2] + ez;
+            if (tx > minX && tx < maxX && tz > minZ && tz < maxZ) {
+                const depth = Math.min(tx - minX, maxX - tx, tz - minZ, maxZ - tz);
+                if (depth > bestDepth) {
+                    bestDepth = depth;
+                    bestIndex = i;
+                }
+            }
+            const dx = o.position[0] - tx;
+            const dz = o.position[2] - tz;
+            const distSq = dx * dx + dz * dz;
+            if (distSq < fallbackDistSq) {
+                fallbackDistSq = distSq;
+                fallbackIndex = i;
+            }
+        }
+        return bestIndex >= 0 ? bestIndex : fallbackIndex;
+    }
+    return {
+        clampMove(from, to) {
+            const obstacles = options.obstacles();
+            if (obstacles.length === 0)
+                return to;
+            const attemptedX = to[0] - from[0];
+            const attemptedZ = to[1] - from[1];
+            const step = resolveObstacleStep([from[0], CAR_BODY_MID_Y, from[1]], attemptedX, attemptedZ, vehicleView(obstacles), radius);
+            const blockedX = attemptedX - step.stepX;
+            const blockedZ = attemptedZ - step.stepZ;
+            if (blockedX === 0 && blockedZ === 0)
+                return to;
+            const blockedMag = Math.hypot(blockedX, blockedZ);
+            if (blockedMag > BLOCK_EPSILON) {
+                const dt = options.dt();
+                const closingSpeed = dt > 0 ? blockedMag / dt : 0;
+                if (pending === null || closingSpeed > pending.closingSpeed) {
+                    pending = {
+                        closingSpeed,
+                        normal: [-blockedX / blockedMag, -blockedZ / blockedMag],
+                        obstacleIndex: blockingIndex(obstacles, to[0], to[1]),
+                    };
+                }
+            }
+            return [from[0] + step.stepX, from[1] + step.stepZ];
+        },
+        takeImpact() {
+            const impact = pending;
+            pending = null;
+            return impact;
+        },
+    };
+}

package/dist/random/rng.d.ts

@@ -20,7 +20,10 @@ export declare function randomSeedFrom(seed: number): RandomSeed;
  * instead of closing over a generator.
  */
 export declare function stepRandomSeed(seed: RandomSeed): readonly [value: number, next: RandomSeed];
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export declare function seededRng(seed: string | number): () => number;
 /** Derives independent, deterministic {@link seededRng} streams from one base seed, keyed by stream name. */
 export declare function seededStreams(seed: string | number): (stream: string) => () => number;

package/dist/random/rng.js

@@ -29,7 +29,10 @@ export function stepRandomSeed(seed) {
     const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
     return [value, next];
 }
-/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence. */
+/** Deterministic pseudo-random generator seeded from a string or number — same seed, same sequence.
+ *
+ * @capability seeded-random injected deterministic randomness for game logic — never `Math.random` in a simulation
+ */
 export function seededRng(seed) {
     let cursor = randomSeedFrom(hashSeed(seed));
     return () => {

package/dist/runtime/adapter.d.ts

@@ -56,6 +56,8 @@ export declare function convexPresence(config?: {
  * 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;
@@ -78,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;
@@ -105,6 +112,12 @@ export declare function resolveAuthority(multiplayer: unknown): MultiplayerAutho
 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

@@ -14,6 +14,8 @@ export function convexPresence(config) {
  * 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 };
@@ -33,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 };
 }
@@ -69,6 +76,12 @@ export function isOffline(multiplayer) {
     const adapter = adapterOf(multiplayer);
     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/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,131 @@
+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 { createEntityStatsApi } from "../../scene/entityStats.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,
+        statPools: createEntityStatsApi((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.js

@@ -1,5 +1,6 @@
 import { resolveHitReaction } from "../../combat/hitReaction.js";
 import { pointInTelegraph } from "../../combat/telegraph.js";
+import { resolveVfxPreset } from "../../combat/vfxPresets.js";
 /** @internal */
 export function createCombatFx(d) {
     const { entities, events, time } = d;
@@ -52,17 +53,26 @@ export function createCombatFx(d) {
         const from = resolveVfxPoint(input.from) ?? to;
         if (from === undefined)
             return;
+        // A named preset fills in kind/color/defaults; any field on the call still wins. With no
+        // preset and no explicit kind/color the resolver falls back to a visible spark rather than
+        // emitting an invalid (blank) burst — so a bare `vfx({ from, to })` still shows something.
+        const resolved = resolveVfxPreset(input.preset, {
+            ...(input.kind === undefined ? {} : { kind: input.kind }),
+            ...(input.color === undefined ? {} : { color: input.color }),
+            ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+            ...(input.radius === undefined ? {} : { radius: input.radius }),
+        });
         const event = {
             id: vfxSeq++,
-            kind: input.kind,
-            color: input.color,
+            kind: resolved.kind,
+            color: resolved.color,
             from,
-            durationMs: input.durationMs ?? vfxDefaultDurationMs[input.kind],
+            durationMs: resolved.durationMs ?? vfxDefaultDurationMs[resolved.kind],
         };
         if (to !== undefined)
             event.to = to;
-        if (input.radius !== undefined)
-            event.radius = input.radius;
+        if (resolved.radius !== undefined)
+            event.radius = resolved.radius;
         events.emit("combat.vfx", event);
     }
     let telegraphSeq = 0;

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;