@jgengine/core 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -26,6 +26,90 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.37.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.37.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.34.0`; `@jgengine/github` is `0.24.0`.
+
+### Added
+
+- `bun run check:script-help` walks every `package.json` script that points into `scripts/`, runs each with `--help`, and fails when one errors, hangs over its own timeout, prints nothing, or when a script names a file the repo does not have. Script files that predate `--help` are listed in `scripts/script-help-baseline.json` and reported, so a new one cannot arrive undocumented.
+- `land`, `lane:close`, `lane:audit`, `ci-status` and `verify:fast` answer `--help` with their purpose, the flags they actually accept, one example and their exit codes, through one shared `scripts/script-help.ts`. No install, network or browser needed.
+- `RunLoop.present(count)` and `RunLoop.choose(id)` (`@jgengine/core/run/runLoop`) draw several next-run changes for a choice screen and adopt the pick, so a game that offers three relics does not compose `game/runDraft` beside the loop. `present` honours the same `after` gates and weights as the single draw and never repeats the change just played while alternatives remain; `choose` opens the next run around the pick and refuses an id the loop's table does not carry.
+- `installRunProbe` (`@jgengine/core/run/runLoop`) publishes `window.__jgengineRun` with the run in progress, what it carries, what it banked or lost, its best bank and the change it offers, so a capture or devtools read proves the loop is live instead of only imported.
+- `bun run find <pattern> [--in <dir>] [--kind ts,tsx] [--files]` answers a repository-wide search in about a second: ripgrep reads the tree once, honours `.gitignore` and never enters `node_modules`, `.git`, `.claude/worktrees` or build output. `--files` lists names by `--glob`, which is what a tree listing was for. Eight of the ten hard timeouts in three hours of lane transcripts were a recursive directory listing over this checkout (160 s, 3.0M files) against a 120 s limit, while every other call's p90 was 10.5 s.
+- `bun run check-recursive-walk` fails a `scripts/**` file or a lane document (`AGENTS.md`, `README.md`, every skill under `.claude/skills`) that ships a recursive directory listing, a `find` walk from a root, or `git ls-files` piped into per-file work; a required one carries `// walk-ok: <reason>`. It runs in CI through the scripts test shard.
+- `ModelConfig.variants` (`levels: [{ url, maxDistance? }]`, `hysteresis?`) declares ordered mesh detail levels for a model. The instanced prop path switches level per instance by distance to the camera, so near and far placements of one species keep their own mesh inside one batch cell. A model without `variants` draws exactly as before.
+- `createModelVariantSelector` (`@jgengine/core/world/modelLod`) returns the level index for an id at a distance, carrying hysteresis across each boundary (`DEFAULT_VARIANT_HYSTERESIS`, 6 m). `lodBandIndex` is now exported from `@jgengine/core/world/lod` and both the LOD scheduler and the selector read distances through it, so simulation throttling and mesh detail cannot disagree.
+- `syncStaticObjectSource` takes an optional `accept` predicate so one batch can split its instances between two instanced draws.
+- `InstancedScatter` now honours `ModelConfig.variants`: each species-chunk batch asks the same `createModelVariantSelector` the static prop path uses for every placement's level, and each level draws its own instanced meshes claiming only its placements. A chunk that holds near and far palms of one species draws both levels from the one batch; a model without `variants` draws exactly as before.
+- `writeScatterVariantLevel` (`@jgengine/shell` internal, `scatter/scatterVariants`) is the per-frame pass: it writes one level's composed matrices into a reserved slot array and returns `count`, allocating nothing per frame, and takes an optional `keep` predicate so a tier-distance or occlusion cull composes with level selection in one loop.
+- `terrain({ cellSize })` states ground density as world units per quad instead of a segment count, and derives the per-axis grid from `bounds` — the same `cellSize` on a bigger world spends more cells rather than stretching one count across it. `segments` still works and also takes `[x, z]` for a non-square grid. Setting both fails naming `cellSize`; a cell size over the 1,000,000-vertex ceiling fails with the cell/vertex numbers and the smallest `cellSize` that fits.
+- `shoot`, `drive` and `perf` take `--quality <low|medium|high|ultra>` and pin that graphics tier on the game page (`?quality=<tier>`). Each run reads the tier back from the shell (`data-jg-quality`) and fails when it is missing or different, so a capture or perf record always names the tier it measured. Every capture summary prints `tier <tier>`; `perf` echoes `perf: tier <tier>` and records it in `quality`.
+- The old `--quality draft|full` iteration mode is now the `--draft` switch (low tier, half viewport, `-draft` file names), on `shoot`, `drive` and `perf`; `perf:gate` takes `--draft` too. An unknown `--quality` value fails naming all four tiers.
+- `attributeTriangles` (`@jgengine/shell/render/triangleAttribution`) sums a scene's triangles by model and geometry with instance counts, and the devtools render probe publishes it as `probes["render/triangles"]` and the `render/triangles` system probe, so `debug_snapshot` names the object behind a heavy frame instead of only counting it. Harbor Heat read 1,021,671 triangles from 840 objects: the 640 m terrain at 300 segments (180,000), the `TwistedTree_2` foliage species (137,010 over 15 trees) and 93 instances of a 1,280-triangle NPC model.
+- `ShotSpec` and `resolveShotSpec` (`@jgengine/core/combat/shotSpec`) describe how a shot travels and what it does on contact as plain data: an instant trace or a travelling body with speed, gravity, drag, fuse, lifetime, radius and homing, plus contact damage, falloff, penetration, splash, ricochet and statuses. Every field but `delivery.kind` is optional with a documented default, so a plain gun is three lines and a grenade, mortar, arrow or hitscan explosive is the same shape with different numbers. `shotArc`, `shotFalloffAt` and `shotHitOutcome` are the one place trajectory, falloff and penetration are solved; `shotSpecFromStats` and `shotSpecFromWeapon` adapt existing item stats and weapon definitions once, and a splash radius or damage number never decides that a shot travels.
+- `ProjectileShotInput.spec` lets a caller state the spec directly; the projectile and weapon systems read the resolved spec at spawn, fuse, hitscan settle and damage application instead of classifying a shot.
+- A trace that carries splash now resolves its area damage at the contact point on the same tick, which is the #2272 hitscan-explosive configuration.
+- `bun run check:path-portability` fails a test that asserts one platform's path separator: a `\\` literal under `toContain`/`toEqual`/`toBe`/`includes`/`endsWith`, a bare `toContain("/")`, a POSIX root handed to `join`/`resolve`, or a literal compared with an OS path result. It reports the file, the line and the `join(...)` that replaces it. A genuinely single-platform assertion is named in `scripts/path-portability-allow.json` with a reason, printed on every run. This is the class behind #2301 (`toContain("proofs\\flows")`) and the `agent-worktree.test.ts` assertions that only pass on one OS.
+
+Verification:
+- `bun test scripts/check-path-portability.test.ts` - pass, including the pre-fix `proofs\\flows` line failing through the gate and the fixed one passing
+- `bun run check:path-portability` - ok, 3 allowlisted with reasons
+- `bun test scripts/agent-worktree.test.ts scripts/shot-metrics.test.ts scripts/lane-audit.test.ts` - pass
+
+### Changed
+
+- Merge pull request #2309 from Noisemaker111/agent/lane-path-portability
+- `bun run land` hands the PR over instead of waiting for it: it pushes, opens or updates the PR, runs `--verify`, arms auto-merge and exits in seconds, printing the PR URL and `bun run ci:status --pr <n>`. A trivial change spent 5m09s inside `land`'s own poll loop, and one night's lanes spent 449 minutes watching CI. `--watch` still lands the old way and says it is deprecated.
+- `bun run land:queue` is the only process that waits for CI. It lands ready PRs into `beta` in readiness order (auto-merge armed, else the `land:queue` label), rebases a branch whose base moved in a throwaway worktree so a moved base costs one CI run instead of two, waits once per PR and prints one line per PR with its wait time and run id. A lane hands off by running `bun run land`; it never rebases, labels or waits.
+- `bun run lane:close` ends a lane in one command. It stages the worktree's tracked and new files (ignored ones such as `.scratch/` stay out), takes the commit message from the branch's own `changes/` fragment, writes that fragment from the commit summary when the diff has none, pushes, opens or updates the PR with the fragment as the body, arms auto-merge, and prints the PR URL and `bun run ci:status --pr <n>`. One lane's last 20 calls were 13 of commit, push, rebase and PR choreography; this replaces them with one. `bun run land --commit` does the same for a lane that skips `lane:close`, and a clean tree lands as it did before.
+- `bun run bg:run -- <cmd>` starts a long command and returns its id at once; `bun run bg:await <id>` blocks on that task's exit file as an event, then prints its whole output and its exit code. It replaces waiting out a `.out` file with guessed intervals — one lane spent 10 minutes of `Start-Sleep` calls watching a capture it had already started. A runner that dies is answered rather than waited on forever.
+- `--commit` prints every path it will commit before committing, and refuses the ones a lane did not author: a scratch artifact, a path git ignores, a lockfile staged without its `package.json` manifest, and a new `changes/` fragment whose name is not part of the branch's name. `--allow <path>` keeps one refused file on purpose. The first replay committed a test-written `changes/agent-lane-x.md` and this checkout's shared-install `bun.lock` drift; both are refused now, with the file list printed either way.
+- A capture at a non-default tier writes its tier into the file name (`-low`, `-medium`, `-ultra`), so an ultra shot cannot overwrite the high one it was compared against.
+
+Root cause: `--quality` carried the iteration preset, not the graphics tier, so a culling lane that asked for ultra got the game's default `high` on both sides of its comparison and could not prove a tier claim.
+
+### Fixed
+
+- `verify:fast`, `land` and `lane:close` refuse a checkout with no `node_modules` up front: they print the missing marker, the exact fix (`bun install` in this checkout, or `bun run agent:bootstrap`) and exit 78, instead of a `command not found` or a module error from a test file. A genuine failure still exits on its own code.
+- `lane:audit --cwd` finds the lane whose own tool calls name that worktree, and prints `attributed ses_… (N references to …)`. Ambiguous ties name their candidates and pick the worst-waiting one; no candidate at all exits non-zero naming the path it searched, so `--fail-on-waiting` has a lane to judge instead of an empty table.
+- `land` builds the PR body only from `changes/` fragments its own `git diff origin/beta...HEAD` adds, prints a line for every fragment it ignores, and falls back to the branch's commit subjects.
+
+Root cause: a subagent session stores the directory of the agent that spawned it, so a lane was invisible to its own audit; `changes/` is shared by every lane on the branch, so "newest fragment" was free to be a stranger's note.
+
+Before: `lane:audit --cwd …\lane-wait-audit` exited 1 with "no child sessions", and a body built from a stray `changes/` fragment claimed work the diff did not contain.
+After: `lane:audit: attributed ses_e94f3aeedffe2CCMsTlrzgvez5 (136 references to …\lane-wait-audit)`, and `land: ignoring changes/scratch-leftover.md: this branch's diff against origin/beta does not add it`.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run verify:fast` — pass
+- `bun run lane:audit --cwd <the real lane worktree> --hours 6` — attributed that lane by 136 references
+- `lane:audit` classifies a call by what it runs, not by the text inside its arguments: `rg`, `grep`, `Select-String`, `findstr`, `Get-Content`, `cat`, `echo`, `Write-Output` and `git` (any subcommand) never count as a sleep or a CI watch, and quoted arguments are stripped before matching. A lane that greps for `Start-Sleep` or writes a PR body about `gh run watch` no longer records waiting it never did.
+- Catches the waits it used to miss: `Start-Sleep` under `powershell -Command`/`pwsh -c`/`bash -lc`, `cmd /c "timeout /t"`, `Thread.sleep`, `Atomics.wait`, `Bun.sleep`, and `gh pr checks` inside a `for`/`while` loop.
+
+Over the last 40 hours (209 lanes): sleep 1066.6 -> 1068.7 minutes, CI watch 421.8 -> 421.3 minutes. 15 calls stopped counting as waits, one real `Start-Sleep -Seconds 150` started counting.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run lane:audit --json --hours 40` before and after, compared per command
+- `lane:close` reads `calls` as the count it is, takes waits from a new `waits` list in `lane:audit --json`, and refuses an unfamiliar audit shape with `the audit output shape changed: <field> is <type>, expected <type> (keys seen: …)` instead of a TypeError. Exit codes unchanged: a sleep or CI watch is 2, `--waive` records the reason, no percentage thresholds.
+
+Root cause: `lane:audit --json` had always reported `calls` as a number, while `lane:close` held it as a list of call objects; nothing read the real document until lane attribution started returning a lane, so the gate that judges a finishing lane crashed on the first lane that had one.
+
+Before: `lane:close` landed the PR, then died with `source.filter is not a function` at `waitingGate`.
+After: the same captured output is judged, the waits are listed, and the lane gets exit 2 with a report skeleton.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts` — pass, including the captured-output fixture
+- `bun run verify:fast` — pass
+- `shoot --url ... --look` now sends the aim to the page it captures, so a lane can measure a branch on a dev runner it started itself. The read-back stays: a page that reports no applied aim still fails the capture instead of returning a plausible wrong view, and a page that applies `--param look=` itself can report it on `data-jg-look` or `window.__jgLook`. `--site --look` is refused at the command line, naming the `--url` form that works.
+- `check:no-blocking-wait` judges code that waits, not prose that describes waiting. In `packages/<pkg>/src/meta` (the changelog mirror and its neighbours) single- and double-quoted text and comments are masked before matching, so a release note reading "one lane spent 10 minutes of `Start-Sleep`" no longer fails the gate; a command in a template literal still fails, and every other `scripts/**` path keeps the strict rule where a quoted command is a real finding. The 0.37.0 release cut failed `types` on `packages/core/src/meta/changelog.ts:46,55,56` with exactly that false positive.
+- `@jgengine/rapier` now accumulates `step(dt)` into its fixed substeps instead of stepping once per call with `fixedDt` as the timestep. A 1 s move covered 0.5 s of simulated time at 30 fps and 2.4 s at 144 fps; it now covers 1 s at either rate, matching `PhysicsWorld` and the `PhysicsBackend` contract.
+- `PhysicsWorld` bounds-floor friction is Coulomb (`friction × g × dt`) like contact friction, not a 60 Hz multiplicative brake: a crate sliding at 4 m/s travelled 0.165 m on the world floor and 0.970 m on a floor collider, and now travels 0.967 m on both.
+- Player and character-controller gravity integrate trapezoidally, so a jump reaches `v²/2g` at any frame rate: the default jump peaked at 0.933 m at 30 fps and 1.026 m at 144 fps, and now at 1.050 m for both.
+
 ## 0.36.0
 
 ### Migrate

package/dist/combat/projectiles.d.ts

@@ -4,10 +4,13 @@ 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";
+import { type ShotSpec } from "./shotSpec.js";
 import { type ShotOriginPolicy } from "./shotOrigin.js";
 export interface ProjectileShotInput {
     from: string;
     via: EffectVia;
+    /** How this shot travels and what it does on contact. Omitted means the shot's numeric stats are adapted once. */
+    spec?: ShotSpec;
     aim: Aim;
     effect: string;
     /** Defaults to `{ kind: "converge" }` — explicit rays pass through; angular aim converges from the muzzle to the sightline. */
@@ -121,8 +124,9 @@ export interface ProjectileSettleReport {
     effect: string;
     hit: boolean;
     /**
-     * True for lobbed/exploding shots (grenades, launchers, rockets) whose real path is an arc,
-     * false for direct-fire shots (bullets, bolts) that travel muzzle→impact in a straight line.
+     * True for lobbed fused rounds (grenades, launchers, rockets) whose real path is an arc,
+     * false for direct-fire shots (bullets, bolts) that travel muzzle→impact in a straight line,
+     * including direct-fire shots that carry an explosion.
      * Presentation uses it to keep straight-line tracers off arced projectiles.
      */
     ballistic: boolean;

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;