@jgengine/core 0.19.0 → 0.21.0

package/dist/combat/death.js

@@ -9,7 +9,7 @@ export function normalizeOnDeath(spec) {
     return normalized;
 }
 function matchesReason(when, reason) {
-    return when === undefined || when.reason === reason.kind;
+    return when === undefined || when.reason === "any" || when.reason === reason.kind;
 }
 /**
  * Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
@@ -37,7 +37,7 @@ export function createDeathSystem(deps) {
             if (identity.displayName !== undefined)
                 event.displayName = identity.displayName;
             deps.events.emit("entity.died", event);
-            const onDeath = normalizeOnDeath(deps.resolveOnDeath(instanceId));
+            const onDeath = normalizeOnDeath(deps.resolveOnDeath(instanceId, reason));
             const drops = [];
             for (const rule of onDeath.drops) {
                 if (matchesReason(rule.when, reason))
@@ -47,7 +47,7 @@ export function createDeathSystem(deps) {
             if (onDeath.command !== null &&
                 matchesReason(onDeath.command.when, reason) &&
                 deps.runCommand !== undefined) {
-                deps.runCommand(onDeath.command.name, onDeath.command.args);
+                deps.runCommand(onDeath.command.name, onDeath.command.args, reason);
                 ranCommand = onDeath.command.name;
             }
             deps.despawn(instanceId);

package/dist/combat/magazine.d.ts

@@ -17,6 +17,13 @@ export interface MagazineConfig {
      */
     reserve?: number | MagazineReserve;
 }
+/** Live magazine tuning; shrinking below loaded rounds rejects unless overflow is explicit. */
+export interface MagazineTuning {
+    capacity?: number;
+    reloadMs?: number;
+    /** Defaults to `reject`; returning rounds requires a finite reserve with `gain`. */
+    overflow?: "reject" | "discard" | "return-to-reserve";
+}
 /** Complete serializable state for a {@link Magazine}; `reserve: null` means infinite reserve. */
 export interface MagazineSnapshot {
     loaded: number;
@@ -31,6 +38,8 @@ export interface MagazineSnapshot {
 export interface Magazine {
     loaded(): number;
     capacity(): number;
+    /** Retune without granting ammo or resetting reload elapsed time; false leaves all state unchanged. */
+    retune(tuning: MagazineTuning): boolean;
     /** Reserve rounds available to reload from, or `null` when the reserve is infinite. */
     reserve(): number | null;
     isReloading(): boolean;

package/dist/combat/magazine.js

@@ -26,8 +26,8 @@ const INFINITE_RESERVE = {
  * @capability magazine a weapon magazine with capacity, timed reload, and reserve-pool interaction
  */
 export function createMagazine(config) {
-    const capacity = Math.max(0, config.capacity);
-    const reloadMs = Math.max(0, config.reloadMs);
+    let capacity = Math.max(0, config.capacity);
+    let reloadMs = Math.max(0, config.reloadMs);
     const isInfiniteReserve = config.reserve === undefined;
     const reserve = isInfiniteReserve
         ? INFINITE_RESERVE
@@ -42,6 +42,28 @@ export function createMagazine(config) {
     return {
         loaded: () => loaded,
         capacity: () => capacity,
+        retune(tuning) {
+            if ((tuning.capacity !== undefined && !Number.isFinite(tuning.capacity)) ||
+                (tuning.reloadMs !== undefined && !Number.isFinite(tuning.reloadMs)))
+                return false;
+            const nextCapacity = Math.max(0, tuning.capacity ?? capacity);
+            const nextReloadMs = Math.max(0, tuning.reloadMs ?? reloadMs);
+            const overflow = Math.max(0, loaded - nextCapacity);
+            if (overflow > 0) {
+                const policy = tuning.overflow ?? "reject";
+                if (policy === "reject")
+                    return false;
+                if (policy === "return-to-reserve") {
+                    if (isInfiniteReserve || reserve.gain === undefined)
+                        return false;
+                    reserve.gain(overflow);
+                }
+            }
+            capacity = nextCapacity;
+            reloadMs = nextReloadMs;
+            loaded = clampLoaded(loaded);
+            return true;
+        },
         reserve: () => (isInfiniteReserve ? null : reserve.current()),
         isReloading: () => reloadElapsedMs !== null,
         reloadFraction: () => (reloadElapsedMs === null || reloadMs <= 0 ? 0 : Math.min(1, reloadElapsedMs / reloadMs)),

package/dist/combat/projectiles.d.ts

@@ -1,6 +1,6 @@
 import type { BallisticSweep } from "../physics/ballisticSweep.js";
 import type { EntityPosition } from "../scene/entityStore.js";
-import { type EntityColliderSet } from "../scene/colliders.js";
+import type { EntityColliderSet } from "../scene/colliders.js";
 import { type SceneRaycastApi } from "../scene/sceneRaycast.js";
 import type { Aim } from "../scene/spatial.js";
 import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
@@ -10,8 +10,84 @@ export interface ProjectileShotInput {
     via: EffectVia;
     aim: Aim;
     effect: string;
-    /** Defaults to `{ kind: "eye" }` — aim.origin when given, else shooter position at eye height. */
+    /** Defaults to `{ kind: "converge" }` — explicit rays pass through; angular aim converges from the muzzle to the sightline. */
     originPolicy?: ShotOriginPolicy;
+    /** Opt into simulation-owned travel. Values are captured at launch; time is in game-seconds. */
+    travel?: ProjectileTravelConfig;
+}
+/** Captured launch settings for authoritative live travel. */
+export interface ProjectileTravelConfig {
+    speed: number;
+    lifetime: number;
+    /** Forwarded to the injected sweep; the default scene query sweeps a centerline. */
+    radius?: number;
+    gravity?: EntityPosition;
+    /** Game-owned wind coupling in 1/seconds, from 0 to 1e12; omission leaves wind response off. */
+    windResponse?: number;
+    /** Target bits read by the injected environmental force sampler. */
+    forceMask?: number;
+    /** Cap injected acceleration in m/s², from 0 to 1e12, independently of gravity. */
+    maxAcceleration?: number;
+}
+/** Nearest contact returned by a live segment sweep. */
+export interface ProjectileTravelImpact {
+    /** Earliest contact fraction along this step, including moving targets. */
+    fraction: number;
+    at: EntityPosition;
+    target?: ProjectileHit;
+}
+/** Authoritative clock, collision and environmental acceleration providers. */
+export interface ProjectileTravelDeps {
+    /** Authoritative game-seconds; no wall-clock fallback is used for live travel. */
+    now(): number;
+    sweep?(from: EntityPosition, to: EntityPosition, step: {
+        shotId: string;
+        input: ProjectileShotInput;
+        radius: number;
+        fromTime: number;
+        toTime: number;
+    }): ProjectileTravelImpact | null;
+    acceleration?(position: EntityPosition, velocity: EntityPosition, time: number, input: ProjectileShotInput): EntityPosition;
+    maxActive?: number;
+    maxRetained?: number;
+}
+/** Detached pose of one active projectile pellet for presentation. */
+export interface LiveProjectile {
+    shotId: string;
+    pellet: number;
+    from: string;
+    effect: string;
+    via: EffectVia;
+    position: EntityPosition;
+    velocity: EntityPosition;
+    age: number;
+    radius: number;
+}
+/** Serializable motion state of one projectile pellet. */
+export interface ProjectileFlightState {
+    position: EntityPosition;
+    velocity: EntityPosition;
+    age: number;
+    distance: number;
+    active: boolean;
+}
+/** Serializable captured launch and settlement state. */
+export interface ProjectileShotState {
+    shotId: string;
+    input: ProjectileShotInput;
+    coneSamples: readonly (readonly [number, number])[];
+    pellets: number;
+    firedAt: number;
+    settled: boolean;
+    origin?: EntityPosition;
+    flights?: ProjectileFlightState[];
+    hits: EffectResult[];
+    at?: EntityPosition;
+}
+/** Detached projectile owner state for replay and restore. */
+export interface ProjectileSystemState {
+    shotCounter: number;
+    shots: ProjectileShotState[];
 }
 export interface EntityRaycastHit {
     kind: "entity";
@@ -34,7 +110,11 @@ export interface ObjectRaycastHit {
 }
 export type RaycastHit = EntityRaycastHit | ObjectRaycastHit;
 export type Raycast = (from: string, aim: Aim, range: number, originPolicy?: ShotOriginPolicy) => RaycastHit[];
+/** Exactly-once settlement with launch identity and actual applied effects. */
 export interface ProjectileSettleReport {
+    shotId: string;
+    /** Actual applied effects; empty for misses and cover impacts. */
+    hits: readonly EffectResult[];
     from: string;
     origin: EntityPosition;
     at: EntityPosition;
@@ -75,7 +155,12 @@ export interface ProjectileSystemDeps {
     sweepBallistic?: BallisticSweep;
     defaultOriginPolicy?: ShotOriginPolicy;
     now?: () => number;
+    /** Cone samples use two draws per nonzero-spread pellet at fire time; defaults to Math.random. */
+    rng?: () => number;
+    /** Per-shot ray limit, clamped to [1, 256]; defaults to 64. */
+    maxPellets?: number;
     onSettle?(report: ProjectileSettleReport): void;
+    travel?: ProjectileTravelDeps;
 }
 export type ProjectileHit = {
     kind: "entity";
@@ -110,9 +195,16 @@ export type SettleResult = {
     reason: string;
 };
 export interface ProjectileSystem {
+    /** Predict the center ray without consuming random samples or applying effects. */
     willHitProjectile(input: ProjectileShotInput): ProjectilePrediction;
+    /** Capture aim, origin-policy vectors and cone samples independently of subsequent caller mutation. */
     fireProjectile(input: ProjectileShotInput): string;
     settleProjectile(shotId: string): SettleResult;
+    /** Advance live shots once per authoritative simulation step; settled shots emit no further effects. */
+    advanceProjectiles(dt: number, time: number): SettleResult[];
+    activeProjectiles(): LiveProjectile[];
+    snapshot(): ProjectileSystemState;
+    restore(state: ProjectileSystemState): void;
 }
 /**
  * Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.

package/dist/combat/projectiles.js

@@ -1,12 +1,33 @@
-import { defaultEntityColliders, resolveColliders } from "../scene/colliders.js";
 import { createSceneRaycast, firstImpact, hitsUntilBlocked, } from "../scene/sceneRaycast.js";
 import { aimDirection, aimSpreadDeg, convergeShot, resolveShot, } from "./shotOrigin.js";
 const DEFAULT_RANGE = 100;
 const DEFAULT_PROJECTILE_SPEED = 15;
 const GRAVITY = 9.8;
 const BASE_HIT_RADIUS = 0.5;
-function isEntityHit(hit) {
-    return hit.kind === "entity";
+function copyPosition(position) {
+    return [position[0], position[1], position[2]];
+}
+function copyAim(aim) {
+    return "origin" in aim
+        ? { ...aim, origin: copyPosition(aim.origin), direction: copyPosition(aim.direction) }
+        : { ...aim };
+}
+function copyOriginPolicy(policy) {
+    switch (policy.kind) {
+        case "camera":
+        case "world":
+            return { ...policy, origin: copyPosition(policy.origin), ...(policy.direction !== undefined ? { direction: copyPosition(policy.direction) } : {}) };
+        case "entityOffset":
+            return { ...policy, offset: copyPosition(policy.offset) };
+        case "muzzle":
+            return { ...policy, ...(policy.offset !== undefined ? { offset: copyPosition(policy.offset) } : {}) };
+        case "converge":
+            return { ...policy, ...(policy.muzzle !== undefined ? { muzzle: copyPosition(policy.muzzle) } : {}) };
+        case "eye":
+        case "legacy":
+        case "entity":
+            return { ...policy };
+    }
 }
 function isObjectHit(hit) {
     return hit.kind === "object";
@@ -67,6 +88,41 @@ function asSceneHits(hits) {
         normal: [0, 1, 0],
     }));
 }
+/** Validate captured travel settings before a launch or restore can mutate the owner. */
+function validateProjectileTravel(travel) {
+    if (!(travel.speed > 0) || !Number.isFinite(travel.speed) || !(travel.lifetime > 0) || !Number.isFinite(travel.lifetime) ||
+        !(travel.radius === undefined || (Number.isFinite(travel.radius) && travel.radius >= 0)) ||
+        !(travel.gravity === undefined || travel.gravity.every(Number.isFinite))) {
+        throw new RangeError("Projectile travel requires finite positive speed/lifetime and nonnegative radius");
+    }
+    if (!(travel.windResponse === undefined || (Number.isFinite(travel.windResponse) && travel.windResponse >= 0 && travel.windResponse <= 1e12)) ||
+        !(travel.maxAcceleration === undefined || (Number.isFinite(travel.maxAcceleration) && travel.maxAcceleration >= 0 && travel.maxAcceleration <= 1e12))) {
+        throw new RangeError("Projectile wind response and acceleration cap must be finite and between 0 and 1e12");
+    }
+}
+function sampleCone(forward, spreadDeg, sample) {
+    const cone = Math.min(Math.PI / 2, spreadDeg * Math.PI / 180);
+    const unit = (value) => Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 0;
+    const cosTheta = 1 - unit(sample[0]) * (1 - Math.cos(cone));
+    const sinTheta = Math.sqrt(Math.max(0, 1 - cosTheta * cosTheta));
+    const phi = unit(sample[1]) * Math.PI * 2;
+    const horizontal = Math.hypot(forward[0], forward[2]);
+    const right = horizontal > 1e-9
+        ? [forward[2] / horizontal, 0, -forward[0] / horizontal]
+        : [1, 0, 0];
+    const up = [
+        forward[1] * right[2] - forward[2] * right[1],
+        forward[2] * right[0] - forward[0] * right[2],
+        forward[0] * right[1] - forward[1] * right[0],
+    ];
+    const x = sinTheta * Math.cos(phi);
+    const y = sinTheta * Math.sin(phi);
+    return [
+        forward[0] * cosTheta + right[0] * x + up[0] * y,
+        forward[1] * cosTheta + right[1] * x + up[1] * y,
+        forward[2] * cosTheta + right[2] * x + up[2] * y,
+    ];
+}
 /**
  * Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
  *
@@ -75,8 +131,43 @@ function asSceneHits(hits) {
 export function createProjectileSystem(deps) {
     const shots = new Map();
     let shotCounter = 0;
+    let liveCount = 0;
     const now = deps.now ?? (() => Date.now());
+    const rng = deps.rng ?? Math.random;
+    const maxPellets = Number.isFinite(deps.maxPellets)
+        ? Math.max(1, Math.min(256, Math.floor(deps.maxPellets)))
+        : 64;
     const defaultPolicy = deps.defaultOriginPolicy ?? { kind: "converge" };
+    const maxActive = Math.max(1, Math.floor(deps.travel?.maxActive ?? 256));
+    const maxRetained = Math.max(0, Math.floor(deps.travel?.maxRetained ?? 256));
+    if (!Number.isFinite(maxActive) || !Number.isFinite(maxRetained))
+        throw new RangeError("Projectile budgets must be finite");
+    function pruneSettled() {
+        let retained = 0;
+        for (const shot of shots.values())
+            if (shot.settled)
+                retained += 1;
+        for (const [id, shot] of shots) {
+            if (retained <= maxRetained)
+                break;
+            if (shot.settled) {
+                shots.delete(id);
+                retained -= 1;
+            }
+        }
+    }
+    function copyShot(shot) {
+        return structuredClone(shot);
+    }
+    function finishFlight(shot) {
+        shot.settled = true;
+        liveCount -= 1;
+        const origin = shot.origin;
+        const at = shot.at ?? shot.flights[0].position;
+        deps.onSettle?.({ shotId: shot.shotId, hits: structuredClone(shot.hits), from: shot.input.from, origin: copyPosition(origin), at: copyPosition(at), effect: shot.input.effect, hit: shot.hits.length > 0, ballistic: true });
+        pruneSettled();
+        return { status: "settled", shotId: shot.shotId, at: [at[0], at[1], at[2]], origin: [origin[0], origin[1], origin[2]], hits: shot.hits };
+    }
     function itemStat(via, stat) {
         return via.item === undefined ? null : deps.getStat(via.item, stat);
     }
@@ -163,38 +254,7 @@ export function createProjectileSystem(deps) {
                 excludeInstanceIds: [from],
             });
             const until = hitsUntilBlocked(all);
-            const spreadRad = (aimSpreadDeg(aim) * Math.PI) / 180;
-            const mapped = [];
-            for (const hit of until) {
-                if (hit.targetKind === "entity" && spreadRad > 0) {
-                    const position = deps.spatial.positionOf(hit.instanceId);
-                    if (position !== undefined) {
-                        const colliders = resolveColliders(deps.entityCollidersOf?.(hit.instanceId) ?? defaultEntityColliders());
-                        const collider = colliders.find((candidate) => candidate.name === hit.colliderName) ?? colliders[0];
-                        const localOffset = collider?.shape.offset ?? [0, 0, 0];
-                        const slack = collider === undefined
-                            ? BASE_HIT_RADIUS
-                            : collider.shape.kind === "sphere"
-                                ? collider.shape.radius
-                                : Math.hypot(...collider.shape.halfExtents);
-                        const rotationY = deps.rotationYOf?.(hit.instanceId) ?? 0;
-                        const cos = Math.cos(rotationY);
-                        const sin = Math.sin(rotationY);
-                        const dx = position[0] + localOffset[0] * cos + localOffset[2] * sin - origin[0];
-                        const dy = position[1] + localOffset[1] - origin[1];
-                        const dz = position[2] - localOffset[0] * sin + localOffset[2] * cos - origin[2];
-                        const along = dx * direction[0] + dy * direction[1] + dz * direction[2];
-                        const px = dx - direction[0] * along;
-                        const py = dy - direction[1] * along;
-                        const pz = dz - direction[2] * along;
-                        const perpendicular = Math.sqrt(px * px + py * py + pz * pz);
-                        if (perpendicular > slack + Math.tan(spreadRad) * along)
-                            continue;
-                    }
-                }
-                mapped.push(sceneHitToRaycast(hit));
-            }
-            return mapped;
+            return until.map(sceneHitToRaycast);
         });
     function resolveRange(via) {
         return itemStat(via, "range") ?? DEFAULT_RANGE;
@@ -280,18 +340,179 @@ export function createProjectileSystem(deps) {
             return prediction;
         },
         fireProjectile(input) {
+            if (input.travel !== undefined) {
+                if (deps.travel === undefined)
+                    throw new Error("Live projectiles require an authoritative travel clock");
+                const travel = input.travel;
+                validateProjectileTravel(travel);
+                if ((travel.radius ?? 0) > 0 && deps.travel.sweep === undefined)
+                    throw new RangeError("Projectile radius requires an injected radius-aware sweep");
+                if (liveCount >= maxActive)
+                    throw new RangeError("Active projectile budget exhausted");
+            }
             shotCounter += 1;
             const shotId = `shot_${shotCounter}`;
-            shots.set(shotId, { input, firedAt: now(), settled: false });
+            const captured = {
+                ...input,
+                aim: copyAim(input.aim),
+                via: { ...input.via },
+                originPolicy: copyOriginPolicy(input.originPolicy ?? defaultPolicy),
+                ...(input.travel === undefined ? {} : { travel: { ...input.travel, ...(input.travel.gravity === undefined ? {} : { gravity: copyPosition(input.travel.gravity) }) } }),
+            };
+            captured.aim = withWeaponSpread(captured.via, captured.aim);
+            const count = itemStat(captured.via, "pellets") ?? 1;
+            const pellets = Number.isFinite(count) ? Math.max(1, Math.min(maxPellets, Math.round(count))) : 1;
+            const coneSamples = [];
+            if ((captured.travel !== undefined || !isBallistic(captured.via)) && aimSpreadDeg(captured.aim) > 0) {
+                for (let pellet = 0; pellet < pellets; pellet += 1) {
+                    coneSamples.push([rng(), rng()]);
+                }
+            }
+            const shot = { shotId, input: captured, coneSamples, pellets, firedAt: captured.travel === undefined ? now() : deps.travel.now(), settled: false, hits: [] };
+            if (captured.travel !== undefined) {
+                if (!Number.isFinite(shot.firedAt))
+                    throw new RangeError("Projectile authority time must be finite");
+                const resolved = resolveShotFor(captured.from, captured.aim, captured.originPolicy, resolveRange(captured.via));
+                if (resolved === null)
+                    throw new Error("Live projectile requires a resolvable launch origin and direction");
+                shot.origin = copyPosition(resolved.origin);
+                shot.flights = [];
+                for (let pellet = 0; pellet < pellets; pellet += 1) {
+                    const sample = coneSamples[pellet];
+                    const direction = sample === undefined ? resolved.direction : sampleCone(resolved.direction, aimSpreadDeg(captured.aim), sample);
+                    shot.flights.push({ position: copyPosition(resolved.origin), velocity: [direction[0] * captured.travel.speed, direction[1] * captured.travel.speed, direction[2] * captured.travel.speed], age: 0, distance: 0, active: true });
+                }
+            }
+            shots.set(shotId, shot);
+            if (shot.flights !== undefined)
+                liveCount += 1;
             return shotId;
         },
+        advanceProjectiles(dt, time) {
+            if (!Number.isFinite(dt) || dt < 0 || !Number.isFinite(time))
+                throw new RangeError("Projectile steps require finite nonnegative dt and authoritative time");
+            const results = [];
+            if (dt === 0 || liveCount === 0)
+                return results;
+            for (const shot of Array.from(shots.values())) {
+                if (shot.settled || shot.flights === undefined)
+                    continue;
+                const travel = shot.input.travel;
+                const gravity = travel.gravity ?? [0, 0, 0];
+                const range = resolveRange(shot.input.via);
+                for (const flight of shot.flights) {
+                    if (!flight.active)
+                        continue;
+                    const step = Math.min(dt, Math.max(0, time - shot.firedAt - flight.age), Math.max(0, travel.lifetime - flight.age));
+                    if (step <= 0)
+                        continue;
+                    const fromTime = shot.firedAt + flight.age;
+                    const external = deps.travel?.acceleration?.(copyPosition(flight.position), copyPosition(flight.velocity), fromTime, shot.input) ?? [0, 0, 0];
+                    if (!external.every(Number.isFinite))
+                        throw new RangeError("Projectile acceleration must be finite");
+                    const magnitude = Math.hypot(...external);
+                    const cap = travel.maxAcceleration ?? Number.POSITIVE_INFINITY;
+                    const forceScale = magnitude > cap ? cap / magnitude : 1;
+                    const acceleration = [gravity[0] + external[0] * forceScale, gravity[1] + external[1] * forceScale, gravity[2] + external[2] * forceScale];
+                    const from = flight.position;
+                    const to = [from[0] + flight.velocity[0] * step + acceleration[0] * step * step / 2, from[1] + flight.velocity[1] * step + acceleration[1] * step * step / 2, from[2] + flight.velocity[2] * step + acceleration[2] * step * step / 2];
+                    const length = Math.hypot(to[0] - from[0], to[1] - from[1], to[2] - from[2]);
+                    const rangeFraction = length > 0 ? Math.max(0, Math.min(1, (range - flight.distance) / length)) : 1;
+                    const end = [from[0] + (to[0] - from[0]) * rangeFraction, from[1] + (to[1] - from[1]) * rangeFraction, from[2] + (to[2] - from[2]) * rangeFraction];
+                    let impact;
+                    if (deps.travel?.sweep !== undefined) {
+                        impact = deps.travel.sweep(copyPosition(from), copyPosition(end), { shotId: shot.shotId, input: shot.input, radius: travel.radius ?? 0, fromTime, toTime: fromTime + step * rangeFraction });
+                    }
+                    else {
+                        const distance = length * rangeFraction;
+                        const hits = distance > 0 ? internalSceneRaycast.raycastAll({ origin: from, direction: [end[0] - from[0], end[1] - from[1], end[2] - from[2]], maxDistance: distance, excludeInstanceIds: [shot.input.from] }) : [];
+                        const hit = hits.find(hit => hit.blocks || (hit.targetKind === "entity" && hit.damageEligible)) ?? null;
+                        impact = hit === null ? null : { fraction: hit.distance / distance, at: hit.point, target: toProjectileHit(sceneHitToRaycast(hit)) };
+                    }
+                    if (impact !== null && (!Number.isFinite(impact.fraction) || impact.fraction < 0 || impact.fraction > 1 || !impact.at.every(Number.isFinite)))
+                        throw new RangeError("Projectile sweep must return a finite contact in the segment");
+                    const fraction = rangeFraction * (impact?.fraction ?? 1);
+                    flight.position = impact === null ? end : copyPosition(impact.at);
+                    flight.velocity = [flight.velocity[0] + acceleration[0] * step * fraction, flight.velocity[1] + acceleration[1] * step * fraction, flight.velocity[2] + acceleration[2] * step * fraction];
+                    flight.age += step * fraction;
+                    flight.distance += length * fraction;
+                    if (impact !== null || rangeFraction < 1 || flight.age >= travel.lifetime || flight.distance >= range) {
+                        flight.active = false;
+                        shot.at ??= copyPosition(flight.position);
+                        const target = impact?.target;
+                        const splash = itemStat(shot.input.via, "explosion.radius");
+                        if (impact !== null && splash !== null) {
+                            shot.hits.push(...deps.effects.applyEffect({ from: shot.input.from, effect: shot.input.effect, via: shot.input.via, at: flight.position, radius: splash, falloff: "linear" }));
+                        }
+                        else if (target?.kind === "entity" && target.damageEligible !== false && deps.effects.canReceive(target.instanceId, shot.input.effect) === null) {
+                            shot.hits.push(...deps.effects.applyEffect({ from: shot.input.from, to: target.instanceId, effect: shot.input.effect, via: shot.input.via }));
+                        }
+                    }
+                }
+                if (shot.flights.every(flight => !flight.active))
+                    results.push(finishFlight(shot));
+            }
+            return results;
+        },
+        activeProjectiles() {
+            const active = [];
+            if (liveCount === 0)
+                return active;
+            for (const shot of shots.values()) {
+                if (shot.settled || shot.flights === undefined)
+                    continue;
+                shot.flights.forEach((flight, pellet) => {
+                    if (flight.active)
+                        active.push({ shotId: shot.shotId, pellet, from: shot.input.from, effect: shot.input.effect, via: { ...shot.input.via }, position: copyPosition(flight.position), velocity: copyPosition(flight.velocity), age: flight.age, radius: shot.input.travel?.radius ?? 0 });
+                });
+            }
+            return active;
+        },
+        snapshot: () => ({ shotCounter, shots: Array.from(shots.values(), copyShot) }),
+        restore(state) {
+            const next = new Map();
+            let active = 0;
+            for (const shot of state.shots) {
+                if (!Number.isInteger(shot.pellets) || shot.pellets < 1 || shot.pellets > maxPellets ||
+                    !Array.isArray(shot.coneSamples) || (shot.coneSamples.length !== 0 && shot.coneSamples.length !== shot.pellets)) {
+                    throw new RangeError("Restored projectile pellet budget or sample count is invalid");
+                }
+                if (shot.input.travel !== undefined) {
+                    validateProjectileTravel(shot.input.travel);
+                    if ((shot.input.travel.radius ?? 0) > 0 && deps.travel?.sweep === undefined)
+                        throw new RangeError("Projectile radius requires an injected radius-aware sweep");
+                }
+                if ((shot.flights !== undefined) !== (shot.input.travel !== undefined) ||
+                    (shot.flights !== undefined && (!Array.isArray(shot.flights) || shot.flights.length !== shot.pellets))) {
+                    throw new RangeError("Restored projectile flight count must match captured travel pellets");
+                }
+                if (shot.flights !== undefined && deps.travel === undefined)
+                    throw new Error("Restoring live projectiles requires an authoritative travel clock");
+                if (shot.flights !== undefined && !shot.settled)
+                    active += 1;
+                if (next.has(shot.shotId))
+                    throw new Error("Restoring duplicate projectile ids");
+                next.set(shot.shotId, copyShot(shot));
+            }
+            if (active > maxActive)
+                throw new RangeError("Restored projectile budget exhausted");
+            shots.clear();
+            shotCounter = state.shotCounter;
+            liveCount = active;
+            for (const [id, shot] of next)
+                shots.set(id, shot);
+            pruneSettled();
+        },
         settleProjectile(shotId) {
             const shot = shots.get(shotId);
             if (shot === undefined)
                 return { status: "rejected", shotId, reason: "unknown-shot" };
             if (shot.settled)
                 return { status: "rejected", shotId, reason: "already-settled" };
+            if (shot.flights !== undefined)
+                return { status: "rejected", shotId, reason: "in-flight" };
             shot.settled = true;
+            pruneSettled();
             const { input } = shot;
             const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, resolveRange(input.via));
             const origin = resolved?.origin ?? [0, 0, 0];
@@ -308,23 +529,28 @@ export function createProjectileSystem(deps) {
                     radius,
                     falloff: splashRadius === null ? "none" : "linear",
                 });
-                deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: true });
+                deps.onSettle?.({ shotId, hits: structuredClone(hits), from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: true });
                 return { status: "settled", shotId, at, hits, origin: originTuple };
             }
-            const { visible, rawHits } = predictHits(input);
-            const ordered = asSceneHits(rawHits);
-            const untilBlock = hitsUntilBlocked(ordered);
-            const impact = firstImpact(untilBlock);
-            const solidBlock = impact !== null && impact.blocks && !impact.damageEligible;
-            const damageEntityHits = visible.filter((hit) => isEntityHit(hit) &&
-                hit.damageEligible !== false &&
-                (!solidBlock || hit.distance <= (impact?.distance ?? Infinity) + 1e-9) &&
-                deps.effects.canReceive(hit.instanceId, input.effect) === null);
-            const pellets = Math.max(1, Math.round(itemStat(input.via, "pellets") ?? 1));
+            const pellets = shot.pellets;
             const hits = [];
-            if (!solidBlock && damageEntityHits.length > 0) {
-                for (let pellet = 0; pellet < pellets; pellet += 1) {
-                    const target = damageEntityHits[pellet % damageEntityHits.length];
+            let at;
+            for (let pellet = 0; pellet < pellets; pellet += 1) {
+                const sample = shot.coneSamples[pellet];
+                const pelletInput = sample === undefined || resolved === null
+                    ? input
+                    : {
+                        ...input,
+                        aim: { origin, direction: sampleCone(resolved.direction, aimSpreadDeg(input.aim), sample) },
+                        originPolicy: { kind: "eye" },
+                    };
+                const { rawHits } = predictHits(pelletInput);
+                const untilBlock = hitsUntilBlocked(asSceneHits(rawHits));
+                const impact = firstImpact(untilBlock);
+                const target = untilBlock.find((hit) => hit.targetKind === "entity" && hit.damageEligible &&
+                    deps.spatial.hasLineOfSight(input.from, hit.instanceId) &&
+                    deps.effects.canReceive(hit.instanceId, input.effect) === null);
+                if (target !== undefined) {
                     hits.push(...deps.effects.applyEffect({
                         from: input.from,
                         to: target.instanceId,
@@ -332,18 +558,13 @@ export function createProjectileSystem(deps) {
                         via: input.via,
                     }));
                 }
+                if (at === undefined) {
+                    const point = impact?.point ?? target?.point ?? missPoint(pelletInput);
+                    at = [point[0], point[1], point[2]];
+                }
             }
-            let at;
-            if (impact !== null) {
-                at = [impact.point[0], impact.point[1], impact.point[2]];
-            }
-            else if (damageEntityHits[0] !== undefined) {
-                at = [damageEntityHits[0].at[0], damageEntityHits[0].at[1], damageEntityHits[0].at[2]];
-            }
-            else {
-                at = missPoint(input);
-            }
-            deps.onSettle?.({ from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: false });
+            at ??= missPoint(input);
+            deps.onSettle?.({ shotId, hits: structuredClone(hits), from: input.from, origin, at, effect: input.effect, hit: hits.length > 0, ballistic: false });
             return { status: "settled", shotId, at, hits, origin: originTuple };
         },
     };