@jgengine/core 0.35.0 → 0.37.0

package/dist/combat/projectiles.js

@@ -1,9 +1,6 @@
 import { createSceneRaycast, firstImpact, hitsUntilBlocked, } from "../scene/sceneRaycast.js";
+import { resolveShotSpec, shotArc, shotHitOutcome, shotSpecFromStats } from "./shotSpec.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 copyPosition(position) {
     return [position[0], position[1], position[2]];
 }
@@ -256,53 +253,36 @@ export function createProjectileSystem(deps) {
             const until = hitsUntilBlocked(all);
             return until.map(sceneHitToRaycast);
         });
-    function resolveRange(via) {
-        return itemStat(via, "range") ?? DEFAULT_RANGE;
+    function resolveShotSpecOf(input) {
+        return resolveShotSpec(input.spec ?? shotSpecFromStats((stat) => itemStat(input.via, stat)));
     }
-    function isBallistic(via) {
-        return itemStat(via, "projectile.fuseTime") !== null || itemStat(via, "explosion.radius") !== null;
-    }
-    function ballisticArc(input) {
-        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, resolveRange(input.via));
+    function ballisticArc(input, spec) {
+        const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, spec.range);
         const origin = resolved?.origin ?? [0, 0, 0];
         const direction = resolved?.direction ?? aimDirection(input.aim) ?? [0, 0, 1];
-        const speed = itemStat(input.via, "projectile.speed") ?? DEFAULT_PROJECTILE_SPEED;
-        const gravityScale = itemStat(input.via, "projectile.gravity") ?? 1;
-        const fuseTime = itemStat(input.via, "projectile.fuseTime");
-        const gravity = GRAVITY * gravityScale;
-        const verticalSpeed = direction[1] * speed;
-        const flightCap = fuseTime ?? resolveRange(input.via) / speed;
-        const impactTime = gravity > 0
-            ? (verticalSpeed + Math.sqrt(verticalSpeed * verticalSpeed + 2 * gravity * Math.max(0, origin[1]))) / gravity
-            : flightCap;
-        const flightTime = Math.min(impactTime, flightCap);
-        const settledY = Math.max(0, origin[1] + verticalSpeed * flightTime - 0.5 * gravity * flightTime * flightTime);
-        return {
-            origin,
-            velocity: [direction[0] * speed, verticalSpeed, direction[2] * speed],
-            gravity,
-            flightTime,
-            landing: [
-                origin[0] + direction[0] * speed * flightTime,
-                settledY,
-                origin[2] + direction[2] * speed * flightTime,
-            ],
-        };
+        const arc = shotArc(spec, origin, direction);
+        return { origin, velocity: arc.velocity, gravity: arc.gravity, flightTime: arc.flightTime, landing: arc.landing };
     }
-    function ballisticSettlePoint(input) {
-        const arc = ballisticArc(input);
+    function ballisticSettlePoint(input, spec) {
+        const arc = ballisticArc(input, spec);
         const sweep = deps.sweepBallistic;
         if (sweep !== undefined) {
             const impact = sweep(arc.origin, arc.velocity, arc.gravity, arc.flightTime);
             if (impact !== null)
                 return impact.point;
         }
+        if (arc.gravity === 0 && spec.body.fuse === "impact") {
+            const contact = raycast(input.from, withWeaponSpread(input.via, input.aim), spec.range, input.originPolicy)[0];
+            if (contact !== undefined)
+                return [contact.at[0], contact.at[1], contact.at[2]];
+        }
         return arc.landing;
     }
     function predictHits(input) {
         const aim = withWeaponSpread(input.via, input.aim);
-        const resolved = resolveShotFor(input.from, aim, input.originPolicy, resolveRange(input.via));
-        const rawHits = raycast(input.from, aim, resolveRange(input.via), input.originPolicy);
+        const range = resolveShotSpecOf(input).range;
+        const resolved = resolveShotFor(input.from, aim, input.originPolicy, range);
+        const rawHits = raycast(input.from, aim, range, input.originPolicy);
         const visible = rawHits.filter((hit) => isObjectHit(hit) || deps.spatial.hasLineOfSight(input.from, hit.instanceId));
         return {
             rawHits,
@@ -312,7 +292,7 @@ export function createProjectileSystem(deps) {
         };
     }
     function missPoint(input) {
-        const range = resolveRange(input.via);
+        const range = resolveShotSpecOf(input).range;
         const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, range);
         if (resolved === null)
             return [0, 0, 0];
@@ -356,14 +336,16 @@ export function createProjectileSystem(deps) {
                 ...input,
                 aim: copyAim(input.aim),
                 via: { ...input.via },
+                ...(input.spec === undefined ? {} : { spec: structuredClone(input.spec) }),
                 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 spec = resolveShotSpecOf(captured);
             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) {
+            if ((captured.travel !== undefined || spec.mode === "trace") && aimSpreadDeg(captured.aim) > 0) {
                 for (let pellet = 0; pellet < pellets; pellet += 1) {
                     coneSamples.push([rng(), rng()]);
                 }
@@ -372,7 +354,7 @@ export function createProjectileSystem(deps) {
             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));
+                const resolved = resolveShotFor(captured.from, captured.aim, captured.originPolicy, spec.range);
                 if (resolved === null)
                     throw new Error("Live projectile requires a resolvable launch origin and direction");
                 shot.origin = copyPosition(resolved.origin);
@@ -399,7 +381,8 @@ export function createProjectileSystem(deps) {
                     continue;
                 const travel = shot.input.travel;
                 const gravity = travel.gravity ?? [0, 0, 0];
-                const range = resolveRange(shot.input.via);
+                const spec = resolveShotSpecOf(shot.input);
+                const range = spec.range;
                 for (const flight of shot.flights) {
                     if (!flight.active)
                         continue;
@@ -440,9 +423,9 @@ export function createProjectileSystem(deps) {
                         flight.active = false;
                         shot.at ??= copyPosition(flight.position);
                         const target = impact?.target;
-                        const splash = itemStat(shot.input.via, "explosion.radius");
+                        const splash = spec.contact.splash;
                         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" }));
+                            shot.hits.push(...deps.effects.applyEffect({ from: shot.input.from, effect: shot.input.effect, via: shot.input.via, at: flight.position, radius: splash.radius, falloff: splash.falloff }));
                         }
                         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 }));
@@ -514,20 +497,20 @@ export function createProjectileSystem(deps) {
             shot.settled = true;
             pruneSettled();
             const { input } = shot;
-            const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, resolveRange(input.via));
+            const spec = resolveShotSpecOf(input);
+            const resolved = resolveShotFor(input.from, input.aim, input.originPolicy, spec.range);
             const origin = resolved?.origin ?? [0, 0, 0];
             const originTuple = [origin[0], origin[1], origin[2]];
-            if (isBallistic(input.via)) {
-                const at = ballisticSettlePoint(input);
-                const splashRadius = itemStat(input.via, "explosion.radius");
-                const radius = splashRadius ?? BASE_HIT_RADIUS;
+            if (spec.mode === "body") {
+                const at = ballisticSettlePoint(input, spec);
+                const splash = spec.contact.splash;
                 const hits = deps.effects.applyEffect({
                     from: input.from,
                     effect: input.effect,
                     via: input.via,
                     at,
-                    radius,
-                    falloff: splashRadius === null ? "none" : "linear",
+                    radius: splash?.radius ?? spec.body.radius,
+                    falloff: splash?.falloff ?? "none",
                 });
                 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 };
@@ -550,14 +533,34 @@ export function createProjectileSystem(deps) {
                 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) {
+                const splash = spec.contact.splash;
+                if (splash !== null) {
+                    const centre = (target === undefined ? undefined : deps.spatial.positionOf(target.instanceId)) ?? impact?.point ?? target?.point ?? missPoint(pelletInput);
                     hits.push(...deps.effects.applyEffect({
                         from: input.from,
-                        to: target.instanceId,
                         effect: input.effect,
                         via: input.via,
+                        at: [centre[0], centre[1], centre[2]],
+                        radius: splash.radius,
+                        falloff: splash.falloff,
                     }));
                 }
+                else if (target !== undefined) {
+                    const hitsTaken = untilBlock.filter((hit) => hit.targetKind === "entity" && hit.damageEligible &&
+                        deps.spatial.hasLineOfSight(input.from, hit.instanceId) &&
+                        deps.effects.canReceive(hit.instanceId, input.effect) === null).slice(0, spec.contact.penetration.count + 1);
+                    for (const [index, hit] of hitsTaken.entries()) {
+                        const outcome = shotHitOutcome(spec, hit.distance, index);
+                        if (!outcome.applies || outcome.scale <= 0)
+                            continue;
+                        hits.push(...deps.effects.applyEffect({
+                            from: input.from,
+                            to: hit.instanceId,
+                            effect: input.effect,
+                            via: outcome.scale === 1 ? input.via : { ...input.via, amount: (spec.contact.damage?.base ?? 0) * outcome.scale },
+                        }));
+                    }
+                }
                 if (at === undefined) {
                     const point = impact?.point ?? target?.point ?? missPoint(pelletInput);
                     at = [point[0], point[1], point[2]];

package/dist/combat/shotSpec.d.ts

@@ -0,0 +1,239 @@
+/**
+ * One description of how a shot travels and what it does when it arrives, plus the single resolver
+ * that turns that description into behaviour. A weapon is data: a rifle, a grenade, a mortar and an
+ * arrow differ by fields here, never by a code path, a weapon id or a classifier that reads one stat
+ * as proof of another.
+ */
+/** A world-space point or direction in metres. */
+export type ShotVec3 = readonly [number, number, number];
+/** Standard gravity used to scale `ShotBody.gravity`, m/s². */
+export declare const SHOT_GRAVITY = 9.8;
+/** Furthest a shot resolves when the delivery names no range, m. */
+export declare const DEFAULT_SHOT_RANGE = 100;
+/** Launch speed of a body that names none, m/s. */
+export declare const DEFAULT_SHOT_SPEED = 15;
+/** Hit-sphere radius of a body that names none, m. */
+export declare const DEFAULT_SHOT_RADIUS = 0.5;
+/** Most extra hits a shot may pass through when it names no penetration. */
+export declare const DEFAULT_SHOT_PENETRATION = 0;
+/** Damage multiplier left at the end of falloff when a shot names no end scale. */
+export declare const DEFAULT_FALLOFF_END_SCALE = 0.5;
+/** An instant trace: the shot resolves on the tick it is fired and never travels. */
+export interface ShotTrace {
+    kind: "trace";
+    /** Furthest the trace resolves, m (default {@link DEFAULT_SHOT_RANGE}). */
+    range?: number;
+}
+/**
+ * A travelling body simulated over time. Every dimension is stated; nothing is read off another
+ * field, so a slow arrow with a splash and a fast bullet without one are the same shape.
+ */
+export interface ShotBody {
+    kind: "body";
+    /** Hard distance cap, m, on top of `lifetime` (default {@link DEFAULT_SHOT_RANGE}). */
+    range?: number;
+    /** Launch speed, m/s (default {@link DEFAULT_SHOT_SPEED}). */
+    speed?: number;
+    /** Downward acceleration as a multiple of {@link SHOT_GRAVITY} (default `0`: flies straight). */
+    gravity?: number;
+    /** Velocity decay, 1/s (default `0`: keeps its speed). */
+    drag?: number;
+    /** Seconds the body stays alive before it expires (default `range / speed`). */
+    lifetime?: number;
+    /** Radius of the hit sphere, m (default {@link DEFAULT_SHOT_RADIUS}). */
+    radius?: number;
+    /**
+     * `"impact"` detonates on the first contact (default). A number detonates that many seconds into
+     * flight, which is what gives a grenade its fuse and a mortar its ground burst.
+     */
+    fuse?: number | "impact";
+    /** Turn rate toward the aimed target, rad/s (default `0`: no homing). */
+    homing?: number;
+}
+/** How the shot reaches its target. */
+export type ShotDelivery = ShotTrace | ShotBody;
+/** Linear damage falloff between two distances. */
+export interface ShotFalloff {
+    /** Distance, m, where damage starts dropping. */
+    start: number;
+    /** Distance, m, where it reaches `endScale`; clamped beyond. */
+    end: number;
+    /** Damage multiplier at `end`, `0..1`. */
+    endScale: number;
+}
+/** Extra targets a hit passes through. */
+export interface ShotPenetration {
+    /** Targets after the first that the shot may also hit (default `0`). */
+    count: number;
+    /** Whether those later hits keep full damage (default `true`); `false` leaves them undamaged. */
+    keepDamage?: boolean;
+}
+/** Area damage around the contact point. */
+export interface ShotSplash {
+    /** Radius, m. */
+    radius: number;
+    /** Damage scale across the radius (default `"linear"`). */
+    falloff?: "linear" | "none";
+    /** Multiplier on the direct hit's damage before falloff (default `1`). */
+    damageScale?: number;
+}
+/** Bounces off the first surface contacted. */
+export interface ShotRicochet {
+    /** Bounces the shot resolves before it stops (default `0`). */
+    count: number;
+    /** Widest incoming angle, degrees, that still bounces (default `45`). */
+    angleDeg?: number;
+    /** Damage multiplier after the first bounce (default `0.5`). */
+    damageScale?: number;
+}
+/** One damage channel a shot applies on contact. */
+export interface ShotDamage {
+    /** Damage type id in the caller's damage table. */
+    type: string;
+    /** Damage before hit zone, table, armor, falloff and penetration scale. */
+    base: number;
+    /** Status ids the hit tries to apply; the damage runtime owns chance and effect. */
+    statuses?: readonly string[];
+}
+/** What a shot does on contact: damage, falloff, penetration, splash, ricochet, statuses. */
+export interface ShotContact {
+    /** Direct damage. Omit for a shot that only splashes. */
+    damage?: ShotDamage;
+    /** Damage over distance, on both deliveries. Omit for no falloff. */
+    falloff?: ShotFalloff;
+    /** Extra targets the shot passes through. */
+    penetration?: ShotPenetration;
+    /** Area damage around the contact point. */
+    splash?: ShotSplash;
+    /** Bounces off the first surface contacted. */
+    ricochet?: ShotRicochet;
+}
+/**
+ * A shot as plain data: how it travels and what it does on arrival. Every field but `delivery.kind`
+ * is optional with a documented default, so a plain gun is three lines.
+ */
+export interface ShotSpec {
+    delivery: ShotDelivery;
+    contact?: ShotContact;
+}
+/** A spec with every default filled in. Read `mode` and the branch it names, never the raw spec. */
+export interface ResolvedShotSpec {
+    /** The one decision a firing path makes: resolve now, or simulate a body over time. */
+    mode: "trace" | "body";
+    /** Furthest the shot resolves, m. */
+    range: number;
+    /** Present when `mode` is `"trace"`. */
+    trace: {
+        range: number;
+    } | null;
+    /** Present when `mode` is `"body"`. */
+    body: {
+        speed: number;
+        gravity: number;
+        drag: number;
+        lifetime: number;
+        radius: number;
+        fuse: number | "impact";
+        homing: number;
+    } | null;
+    contact: {
+        damage: {
+            type: string;
+            base: number;
+            statuses: readonly string[];
+        } | null;
+        falloff: {
+            start: number;
+            end: number;
+            endScale: number;
+        } | null;
+        penetration: {
+            count: number;
+            keepDamage: boolean;
+        };
+        splash: {
+            radius: number;
+            falloff: "linear" | "none";
+            damageScale: number;
+        } | null;
+        ricochet: {
+            count: number;
+            angleDeg: number;
+            damageScale: number;
+        } | null;
+    };
+}
+/** What one contact does: whether the shot still carries damage, at what scale, and whether it goes on. */
+export interface ShotHitOutcome {
+    /** `false` once every penetration slot is spent; the shot stops on this target. */
+    applies: boolean;
+    /** Multiplier on the damage base for this target. */
+    scale: number;
+}
+/**
+ * Fill every default and return the one shape firing paths act on. This is the only place that
+ * decides how a shot travels, so a delivery can never be guessed from a damage or splash field.
+ *
+ * @capability shot-spec resolve one shot description into explicit travel and contact behaviour
+ */
+export declare function resolveShotSpec(spec: ShotSpec): ResolvedShotSpec;
+/** Number of seconds the body flies before its fuse ends the flight, or `null` when it flies to contact. */
+export declare function shotFuseSeconds(shot: ResolvedShotSpec): number | null;
+/** Damage multiplier from falloff at `distance`; `1` with no falloff. */
+export declare function shotFalloffAt(shot: ResolvedShotSpec, distance: number): number;
+/**
+ * What a contact at `distance` does to the `hitIndex`-th target it meets, counting the first as `0`.
+ * A trace or body stops once its penetration slots are spent, so penetration is a number, not a branch.
+ */
+export declare function shotHitOutcome(shot: ResolvedShotSpec, distance: number, hitIndex: number): ShotHitOutcome;
+/** Straight-line flight of a body, for a caller that only needs where it starts and how fast. */
+export interface ShotLaunch {
+    origin: ShotVec3;
+    velocity: ShotVec3;
+    gravity: number;
+}
+/** Where a body lands and how long it took, in the same numbers the runtime simulates. */
+export interface ShotArc extends ShotLaunch {
+    /** Seconds of flight, capped by the fuse and ended early by the ground. */
+    flightTime: number;
+    /** Highest point above the launch, m. */
+    apex: number;
+    /** Contact point; `y` is clamped to the ground plane. */
+    landing: [number, number, number];
+}
+/**
+ * Solve the path of a body from a launch pose. A trace has no path and fails loudly instead of
+ * returning a straight line a caller would mistake for an arc.
+ */
+export declare function shotArc(shot: ResolvedShotSpec, origin: ShotVec3, direction: ShotVec3): ShotArc;
+/** Reads a numeric stat by name; the shape every item registry already exposes. */
+export type ShotStatReader = (stat: string) => number | null;
+/**
+ * Project an existing {@link WeaponDefinition} onto a spec, so a weapon authored as a definition and
+ * one authored as a spec reach the same firing paths.
+ */
+export declare function shotSpecFromWeapon(definition: {
+    delivery: {
+        kind: "hitscan";
+        maxRange: number;
+    } | {
+        kind: "projectile";
+        speed: number;
+        gravity?: number;
+        drag?: number;
+        lifetime: number;
+        maxRange?: number;
+    };
+    damage: {
+        type: string;
+        base: number;
+        statuses?: readonly string[];
+    };
+    falloff?: ShotFalloff;
+}): ShotSpec;
+/**
+ * Adapt the numeric stat keys older item data carries to a spec. This is the only place those keys
+ * are read, and delivery is decided by the keys that describe travel (`projectile.*`) alone: a
+ * splash radius or a damage number never turns a trace into a body.
+ */
+export declare function shotSpecFromStats(read: ShotStatReader): ShotSpec;

package/dist/combat/shotSpec.js

@@ -0,0 +1,216 @@
+/**
+ * One description of how a shot travels and what it does when it arrives, plus the single resolver
+ * that turns that description into behaviour. A weapon is data: a rifle, a grenade, a mortar and an
+ * arrow differ by fields here, never by a code path, a weapon id or a classifier that reads one stat
+ * as proof of another.
+ */
+/** Standard gravity used to scale `ShotBody.gravity`, m/s². */
+export const SHOT_GRAVITY = 9.8;
+/** Furthest a shot resolves when the delivery names no range, m. */
+export const DEFAULT_SHOT_RANGE = 100;
+/** Launch speed of a body that names none, m/s. */
+export const DEFAULT_SHOT_SPEED = 15;
+/** Hit-sphere radius of a body that names none, m. */
+export const DEFAULT_SHOT_RADIUS = 0.5;
+/** Most extra hits a shot may pass through when it names no penetration. */
+export const DEFAULT_SHOT_PENETRATION = 0;
+/** Damage multiplier left at the end of falloff when a shot names no end scale. */
+export const DEFAULT_FALLOFF_END_SCALE = 0.5;
+function finite(value, field, min) {
+    if (!Number.isFinite(value) || value < min)
+        throw new RangeError(`Shot spec field "${field}" must be a finite number >= ${min}; got ${String(value)}`);
+    return value;
+}
+/**
+ * Fill every default and return the one shape firing paths act on. This is the only place that
+ * decides how a shot travels, so a delivery can never be guessed from a damage or splash field.
+ *
+ * @capability shot-spec resolve one shot description into explicit travel and contact behaviour
+ */
+export function resolveShotSpec(spec) {
+    const delivery = spec.delivery;
+    const contact = spec.contact ?? {};
+    const falloff = contact.falloff;
+    const penetration = contact.penetration;
+    const splash = contact.splash;
+    const ricochet = contact.ricochet;
+    const damage = contact.damage;
+    const resolvedContact = {
+        damage: damage === undefined
+            ? null
+            : {
+                type: damage.type,
+                base: finite(damage.base, "contact.damage.base", 0),
+                statuses: damage.statuses === undefined ? [] : [...damage.statuses],
+            },
+        falloff: falloff === undefined
+            ? null
+            : {
+                start: finite(falloff.start, "contact.falloff.start", 0),
+                end: finite(falloff.end, "contact.falloff.end", 0),
+                endScale: finite(falloff.endScale, "contact.falloff.endScale", 0),
+            },
+        penetration: {
+            count: penetration === undefined ? DEFAULT_SHOT_PENETRATION : Math.floor(finite(penetration.count, "contact.penetration.count", 0)),
+            keepDamage: penetration?.keepDamage ?? true,
+        },
+        splash: splash === undefined
+            ? null
+            : {
+                radius: finite(splash.radius, "contact.splash.radius", 0),
+                falloff: splash.falloff ?? "linear",
+                damageScale: splash.damageScale === undefined ? 1 : finite(splash.damageScale, "contact.splash.damageScale", 0),
+            },
+        ricochet: ricochet === undefined
+            ? null
+            : {
+                count: Math.floor(finite(ricochet.count, "contact.ricochet.count", 0)),
+                angleDeg: ricochet.angleDeg === undefined ? 45 : finite(ricochet.angleDeg, "contact.ricochet.angleDeg", 0),
+                damageScale: ricochet.damageScale === undefined ? 0.5 : finite(ricochet.damageScale, "contact.ricochet.damageScale", 0),
+            },
+    };
+    if (delivery.kind === "trace") {
+        const range = delivery.range === undefined ? DEFAULT_SHOT_RANGE : finite(delivery.range, "delivery.range", Number.MIN_VALUE);
+        return { mode: "trace", range, trace: { range }, body: null, contact: resolvedContact };
+    }
+    const speed = delivery.speed === undefined ? DEFAULT_SHOT_SPEED : finite(delivery.speed, "delivery.speed", Number.MIN_VALUE);
+    const gravity = delivery.gravity === undefined ? 0 : finite(delivery.gravity, "delivery.gravity", 0);
+    const drag = delivery.drag === undefined ? 0 : finite(delivery.drag, "delivery.drag", 0);
+    const range = delivery.range === undefined ? DEFAULT_SHOT_RANGE : finite(delivery.range, "delivery.range", Number.MIN_VALUE);
+    const lifetime = delivery.lifetime === undefined ? range / speed : finite(delivery.lifetime, "delivery.lifetime", Number.MIN_VALUE);
+    const radius = delivery.radius === undefined ? DEFAULT_SHOT_RADIUS : finite(delivery.radius, "delivery.radius", 0);
+    const homing = delivery.homing === undefined ? 0 : finite(delivery.homing, "delivery.homing", 0);
+    const fuse = delivery.fuse === undefined
+        ? "impact"
+        : delivery.fuse === "impact"
+            ? "impact"
+            : finite(delivery.fuse, "delivery.fuse", 0);
+    return {
+        mode: "body",
+        range,
+        trace: null,
+        body: { speed, gravity, drag, lifetime, radius, fuse, homing },
+        contact: resolvedContact,
+    };
+}
+/** Number of seconds the body flies before its fuse ends the flight, or `null` when it flies to contact. */
+export function shotFuseSeconds(shot) {
+    return shot.body === null || shot.body.fuse === "impact" ? null : shot.body.fuse;
+}
+/** Damage multiplier from falloff at `distance`; `1` with no falloff. */
+export function shotFalloffAt(shot, distance) {
+    const falloff = shot.contact.falloff;
+    if (falloff === null || distance <= falloff.start)
+        return 1;
+    if (falloff.end <= falloff.start)
+        return falloff.endScale;
+    const t = Math.min(1, (distance - falloff.start) / (falloff.end - falloff.start));
+    return 1 + (falloff.endScale - 1) * t;
+}
+/**
+ * What a contact at `distance` does to the `hitIndex`-th target it meets, counting the first as `0`.
+ * A trace or body stops once its penetration slots are spent, so penetration is a number, not a branch.
+ */
+export function shotHitOutcome(shot, distance, hitIndex) {
+    const index = Math.max(0, Math.floor(hitIndex));
+    if (index > shot.contact.penetration.count)
+        return { applies: false, scale: 0 };
+    const survived = index === 0 || shot.contact.penetration.keepDamage ? 1 : 0;
+    return { applies: true, scale: shotFalloffAt(shot, distance) * survived };
+}
+/**
+ * Solve the path of a body from a launch pose. A trace has no path and fails loudly instead of
+ * returning a straight line a caller would mistake for an arc.
+ */
+export function shotArc(shot, origin, direction) {
+    if (shot.body === null)
+        throw new RangeError('Shot spec field "delivery.kind" must be "body" to have a trajectory; a trace resolves instantly');
+    const { speed, gravity, fuse } = shot.body;
+    const acceleration = SHOT_GRAVITY * gravity;
+    const vertical = direction[1] * speed;
+    const fuseSeconds = fuse === "impact" ? null : fuse;
+    const flightCap = fuseSeconds ?? shot.range / speed;
+    const toGround = acceleration > 0
+        ? (vertical + Math.sqrt(vertical * vertical + 2 * acceleration * Math.max(0, origin[1]))) / acceleration
+        : flightCap;
+    const flightTime = Math.min(toGround, flightCap);
+    const settledY = Math.max(0, origin[1] + vertical * flightTime - 0.5 * acceleration * flightTime * flightTime);
+    return {
+        origin,
+        velocity: [direction[0] * speed, vertical, direction[2] * speed],
+        gravity: acceleration,
+        flightTime,
+        apex: acceleration > 0 ? Math.max(0, vertical * vertical / (2 * acceleration)) : 0,
+        landing: [
+            origin[0] + direction[0] * speed * flightTime,
+            settledY,
+            origin[2] + direction[2] * speed * flightTime,
+        ],
+    };
+}
+/**
+ * Project an existing {@link WeaponDefinition} onto a spec, so a weapon authored as a definition and
+ * one authored as a spec reach the same firing paths.
+ */
+export function shotSpecFromWeapon(definition) {
+    const delivery = definition.delivery.kind === "hitscan"
+        ? { kind: "trace", range: definition.delivery.maxRange }
+        : {
+            kind: "body",
+            speed: definition.delivery.speed,
+            ...(definition.delivery.gravity === undefined ? {} : { gravity: definition.delivery.gravity / SHOT_GRAVITY }),
+            ...(definition.delivery.drag === undefined ? {} : { drag: definition.delivery.drag }),
+            lifetime: definition.delivery.lifetime,
+            ...(definition.delivery.maxRange === undefined ? {} : { range: definition.delivery.maxRange }),
+        };
+    return {
+        delivery,
+        contact: {
+            damage: {
+                type: definition.damage.type,
+                base: definition.damage.base,
+                ...(definition.damage.statuses === undefined ? {} : { statuses: definition.damage.statuses }),
+            },
+            ...(definition.falloff === undefined ? {} : { falloff: definition.falloff }),
+        },
+    };
+}
+/**
+ * Adapt the numeric stat keys older item data carries to a spec. This is the only place those keys
+ * are read, and delivery is decided by the keys that describe travel (`projectile.*`) alone: a
+ * splash radius or a damage number never turns a trace into a body.
+ */
+export function shotSpecFromStats(read) {
+    const speed = read("projectile.speed");
+    const fuseTime = read("projectile.fuseTime");
+    const gravity = read("projectile.gravity");
+    const lifetime = read("projectile.lifetime");
+    const radius = read("projectile.radius");
+    const drag = read("projectile.drag");
+    const homing = read("projectile.homing");
+    const range = read("range");
+    const splashRadius = read("explosion.radius");
+    const damage = read("damage");
+    const penetration = read("penetration");
+    const delivery = speed === null && fuseTime === null && gravity === null && lifetime === null && radius === null && drag === null && homing === null
+        ? { kind: "trace", ...(range === null ? {} : { range }) }
+        : {
+            kind: "body",
+            ...(range === null ? {} : { range }),
+            ...(speed === null ? {} : { speed }),
+            ...(gravity === null ? {} : { gravity }),
+            ...(drag === null ? {} : { drag }),
+            ...(lifetime === null ? {} : { lifetime }),
+            ...(radius === null ? {} : { radius }),
+            ...(homing === null ? {} : { homing }),
+            ...(fuseTime === null ? {} : { fuse: fuseTime }),
+        };
+    return {
+        delivery,
+        contact: {
+            ...(damage === null ? {} : { damage: { type: "damage", base: damage } }),
+            ...(splashRadius === null ? {} : { splash: { radius: splashRadius } }),
+            ...(penetration === null ? {} : { penetration: { count: penetration } }),
+        },
+    };
+}