@jgengine/core 0.35.0 → 0.37.0

package/dist/combat/weaponSystem.js

@@ -1,8 +1,9 @@
 import { devtools } from "../devtools/devtools.js";
 import { createMagazine } from "./magazine.js";
-import { assertWeaponDefinition, weaponDamageAt, weaponIntervalMs, weaponMaxInFlight, } from "./weaponDefinition.js";
+import { assertWeaponDefinition, weaponIntervalMs, weaponMaxInFlight, } from "./weaponDefinition.js";
 import { createWeaponHandling, } from "./weaponHandling.js";
 import { createFireCadence } from "./weaponFire.js";
+import { SHOT_GRAVITY, resolveShotSpec, shotFalloffAt, shotSpecFromWeapon } from "./shotSpec.js";
 const MAX_SHOTS_PER_TICK_CAP = 16;
 const DEFAULT_SHOTS_PER_TICK = 4;
 const HALF_PI = Math.PI / 2;
@@ -73,15 +74,16 @@ export function createWeaponSystem(initial, deps) {
     assertWeaponDefinition(initial);
     const rng = deps.rng;
     const maxShotsPerTick = Math.min(MAX_SHOTS_PER_TICK_CAP, Math.max(1, Math.floor(deps.maxShotsPerTick ?? DEFAULT_SHOTS_PER_TICK)));
-    function assertWiring(definition) {
-        if (definition.delivery.kind === "hitscan" && deps.raycast === undefined) {
+    function assertWiring(definition, shotSpec) {
+        if (shotSpec.mode === "trace" && deps.raycast === undefined) {
             throw new Error(`Weapon "${definition.id}" is hitscan but no raycast was provided`);
         }
-        if (definition.delivery.kind === "projectile" && deps.sweep === undefined) {
+        if (shotSpec.mode === "body" && deps.sweep === undefined) {
             throw new Error(`Weapon "${definition.id}" is projectile but no sweep was provided`);
         }
     }
-    assertWiring(initial);
+    const initialShot = resolveShotSpec(shotSpecFromWeapon(initial));
+    assertWiring(initial, initialShot);
     function buildMagazine(definition) {
         const magazine = definition.magazine;
         if (magazine === undefined)
@@ -93,6 +95,7 @@ export function createWeaponSystem(initial, deps) {
         });
     }
     let definition = initial;
+    let shotSpec = initialShot;
     let intervalMs = weaponIntervalMs(initial);
     let cadence = createFireCadence({ intervalMs });
     let magazine = buildMagazine(definition);
@@ -134,7 +137,7 @@ export function createWeaponSystem(initial, deps) {
         const target = contact.target;
         if (target === undefined)
             return;
-        const falloff = weaponDamageAt(definition, distance);
+        const falloff = shotFalloffAt(shotSpec, distance);
         const context = { shot, pellet, distance, falloff };
         const input = deps.damageFor === undefined
             ? defaultDamage(contact, target, falloff)
@@ -154,17 +157,17 @@ export function createWeaponSystem(initial, deps) {
             resolution,
         });
     }
-    function spawnPellet(shot, pellet, origin, direction) {
-        const delivery = definition.delivery;
-        if (delivery.kind !== "projectile")
+    function spawnPellet(shotIndex, pellet, origin, direction) {
+        const body = shotSpec.body;
+        if (body === null)
             return;
         if (pellets.length >= weaponMaxInFlight(definition)) {
             stats.pelletsDropped += 1;
             return;
         }
-        const speed = delivery.speed;
+        const speed = body.speed;
         pellets.push({
-            shot,
+            shot: shotIndex,
             pellet,
             position: origin,
             velocity: [direction[0] * speed, direction[1] * speed, direction[2] * speed],
@@ -183,15 +186,15 @@ export function createWeaponSystem(initial, deps) {
         for (let pellet = 0; pellet < perShot; pellet += 1) {
             const direction = coneDirection(aim.direction, shot.spread, rng);
             directions.push(direction);
-            if (definition.delivery.kind === "hitscan") {
+            if (shotSpec.trace !== null) {
                 const raycast = deps.raycast;
                 if (raycast === undefined)
                     continue;
-                const contact = raycast(origin, direction, definition.delivery.maxRange);
+                const contact = raycast(origin, direction, shotSpec.trace.range);
                 if (contact === null)
                     continue;
                 const distance = distanceBetween(origin, contact.point);
-                if (distance > definition.delivery.maxRange + 1e-6)
+                if (distance > shotSpec.trace.range + 1e-6)
                     continue;
                 resolveContact(contact, distance, shotCount, pellet, out);
             }
@@ -217,14 +220,14 @@ export function createWeaponSystem(initial, deps) {
         });
     }
     function advancePellets(dt, out) {
-        const delivery = definition.delivery;
-        if (pellets.length === 0 || delivery.kind !== "projectile")
+        const body = shotSpec.body;
+        if (pellets.length === 0 || body === null)
             return;
         const sweep = deps.sweep;
         if (sweep === undefined)
             return;
-        const gravity = delivery.gravity ?? 0;
-        const drag = delivery.drag ?? 0;
+        const gravity = body.gravity * SHOT_GRAVITY;
+        const drag = body.drag;
         const dragScale = Math.max(0, 1 - drag * dt);
         const next = [];
         for (const pellet of pellets) {
@@ -250,8 +253,8 @@ export function createWeaponSystem(initial, deps) {
             pellet.velocity = velocity;
             pellet.age += dt;
             pellet.distance = travelled;
-            const outOfRange = delivery.maxRange !== undefined && travelled >= delivery.maxRange;
-            if (pellet.age >= delivery.lifetime || outOfRange) {
+            const outOfRange = travelled >= shotSpec.range;
+            if (pellet.age >= body.lifetime || outOfRange) {
                 stats.projectilesExpired += 1;
                 continue;
             }
@@ -385,11 +388,13 @@ export function createWeaponSystem(initial, deps) {
         },
         retune(next) {
             assertWeaponDefinition(next);
-            assertWiring(next);
+            const nextShot = resolveShotSpec(shotSpecFromWeapon(next));
+            assertWiring(next, nextShot);
             if ((next.magazine === undefined) !== (magazine === null))
                 return false;
             const elapsed = cadence.elapsedMs();
             definition = next;
+            shotSpec = nextShot;
             intervalMs = weaponIntervalMs(next);
             cadence = createFireCadence({ intervalMs });
             cadence.restore(elapsed);

package/dist/combat.d.ts

@@ -30,6 +30,7 @@ export { resistanceScale, resolveResistance } from "./combat/resistance.js";
 export { createResourcePool, type ResourcePool } from "./combat/resourcePool.js";
 export { allocateRewards, filterOutcomeFor, resolveClaim, type AllocationOutcome, type AllocationRequest, type ClaimOutcome, type ClaimablePool, type RewardClaimSpec, type RewardGrant, type RewardPolicyKind, type RewardRecipient, type RewardResult, type RewardShare, } from "./combat/rewardAllocation.js";
 export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, type ResolvedShot, type ShotOriginPolicy, } from "./combat/shotOrigin.js";
+export { DEFAULT_FALLOFF_END_SCALE, DEFAULT_SHOT_PENETRATION, DEFAULT_SHOT_RADIUS, DEFAULT_SHOT_RANGE, DEFAULT_SHOT_SPEED, SHOT_GRAVITY, resolveShotSpec, shotArc, shotFalloffAt, shotFuseSeconds, shotHitOutcome, shotSpecFromStats, type ResolvedShotSpec, type ShotArc, type ShotBody, type ShotContact, type ShotDamage, type ShotDelivery, type ShotFalloff, type ShotHitOutcome, type ShotLaunch, type ShotPenetration, type ShotRicochet, type ShotSpec, type ShotSplash, type ShotStatReader, type ShotTrace, type ShotVec3, } from "./combat/shotSpec.js";
 export { createSquadCombat, type SquadCombat, type SquadCombatOptions, type SquadCombatSnapshot, type SquadCombatStats, type SquadCombatTunables, type SquadMemberSpec, type SquadMemberView, type SquadMode, } from "./combat/squadCombat.js";
 export { assignSquadRoles, threatsFromMemory, type FireDiscipline, type SquadComposition, type SquadRole, type ThreatReadOptions, type ThreatReading, } from "./combat/squadTactics.js";
 export { resolveStatusApplication, type StatusApplicationOutcome, type StatusApplicationSpec, type StatusImmunity, type StatusInstance, type StatusStackPolicy, } from "./combat/statusApplication.js";

package/dist/combat.js

@@ -30,6 +30,7 @@ export { resistanceScale, resolveResistance } from "./combat/resistance.js";
 export { createResourcePool } from "./combat/resourcePool.js";
 export { allocateRewards, filterOutcomeFor, resolveClaim, } from "./combat/rewardAllocation.js";
 export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, } from "./combat/shotOrigin.js";
+export { DEFAULT_FALLOFF_END_SCALE, DEFAULT_SHOT_PENETRATION, DEFAULT_SHOT_RADIUS, DEFAULT_SHOT_RANGE, DEFAULT_SHOT_SPEED, SHOT_GRAVITY, resolveShotSpec, shotArc, shotFalloffAt, shotFuseSeconds, shotHitOutcome, shotSpecFromStats, } from "./combat/shotSpec.js";
 export { createSquadCombat, } from "./combat/squadCombat.js";
 export { assignSquadRoles, threatsFromMemory, } from "./combat/squadTactics.js";
 export { resolveStatusApplication, } from "./combat/statusApplication.js";

package/dist/game/playableGame.d.ts

@@ -3,6 +3,8 @@ import type { AmbienceZoneDef } from "../audio/ambience.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { AudioOcclusionConfig } from "../audio/occlusion.js";
 import type { MusicTheme } from "../audio/music.js";
+import type { ModelVariantLodConfig } from "../world/modelLod.js";
+export type { ModelVariantConfig, ModelVariantLodConfig } from "../world/modelLod.js";
 import type { UiCueOverrides } from "../audio/uiCues.js";
 import type { FeedbackCueOverrides } from "../audio/feedbackCues.js";
 import type { NoticeFeedConfig } from "./notices.js";
@@ -307,6 +309,13 @@ export interface ModelConfig {
      * distance tiers (full rate) — see {@link ModelLodConfig}.
      */
     lod?: ModelLodConfig | false;
+    /**
+     * Ordered mesh detail levels — the full mesh plus decimated copies — switched per instance by
+     * distance to the camera, so one species can keep full geometry near and a cheaper mesh far. Only
+     * the instanced draw path swaps levels; a single-instance placement always draws `url`. See
+     * {@link ModelVariantLodConfig} and `core/world/modelLod`.
+     */
+    variants?: ModelVariantLodConfig;
 }
 /**
  * Distance tiers for one character model. Distances are metres from the camera; every field is data

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.35.0";
+export declare const VERSION = "0.37.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,83 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.35.0";
+export const VERSION = "0.37.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "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.",
+            "`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.",
+            "`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.",
+            "`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.",
+            "`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.",
+            "`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.",
+        ],
+        removed: [],
+    },
+    "0.36.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.36.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.",
+        ],
+        added: [
+            "`createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system, a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.",
+            "`--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.",
+            "`createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.",
+            "`bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.",
+            "`HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).",
+        ],
+        changed: [
+            "The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.",
+            "Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.",
+            "Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer \"how far is this point?\" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.",
+            "Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.",
+        ],
+        removed: [],
+    },
     "0.35.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.35.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.32.0`; `@jgengine/github` is `0.22.0`.",

package/dist/movement/characterController.d.ts

@@ -41,6 +41,11 @@ export interface CharacterMoveInput {
     crouch?: boolean;
     /** Body the controller itself is represented by, excluded from its own casts. */
     self?: BodyHandle;
+    /**
+     * Vertical displacement for this move when the caller already integrated it (a movement model that
+     * owns jump/gravity feel). Overrides the controller's own `verticalVelocity * dt` for the sweep.
+     */
+    verticalStep?: number;
 }
 /** What one move did. */
 export interface CharacterMoveResult {

package/dist/movement/characterController.js

@@ -182,14 +182,21 @@ export function createCharacterController(initial) {
                     break;
                 remaining = slid;
             }
+            const verticalBefore = state.verticalVelocity;
             if (input.gravity !== undefined)
                 state.verticalVelocity -= input.gravity * dt;
+            let jumped = false;
             if (input.jumpVelocity !== undefined && state.grounded) {
                 state.verticalVelocity = input.jumpVelocity;
                 state.grounded = false;
+                jumped = true;
             }
             const wasGrounded = state.grounded;
-            let vertical = state.verticalVelocity * dt + carry[1];
+            // Trapezoidal displacement: the step moves at the average of this step's start and end vertical
+            // speed, so a jump reaches its analytic apex (v²/2g) at any frame rate. A caller that already
+            // integrated the vertical motion passes the step explicitly.
+            const verticalStep = input.verticalStep ?? (jumped ? state.verticalVelocity : (verticalBefore + state.verticalVelocity) / 2) * dt;
+            let vertical = verticalStep + carry[1];
             if (wasGrounded && vertical <= 0)
                 vertical -= cfg.snapDistance;
             const { hit: verticalHit } = sweep(backend, pos, height, [0, vertical, 0], self);

package/dist/movement/movementModel.js

@@ -221,10 +221,13 @@ export function advancePlayerMotion(motion, intent, forwardX, forwardZ, baseSpee
             : motion.verticalVelocity < 0
                 ? (tuning?.fallGravityScale ?? 1)
                 : 1;
+        const risingVelocity = motion.verticalVelocity;
         motion.verticalVelocity -= gravityAcceleration * gravityScale * deltaSeconds;
         if (motion.verticalVelocity <= 0)
             motion.jumpRising = false;
-        motion.jumpOffset += motion.verticalVelocity * deltaSeconds;
+        // Trapezoidal, not Euler: a jump integrates to v²/2g whatever the frame rate. First-order Euler
+        // undershot the apex by 11% at 30 fps and 2% at 144 fps, so the same jump reached different heights.
+        motion.jumpOffset += ((risingVelocity + motion.verticalVelocity) / 2) * deltaSeconds;
         if (motion.jumpOffset <= 0 && options?.externalGrounding !== true) {
             motion.jumpOffset = 0;
             motion.verticalVelocity = 0;

package/dist/movement/playerMovement.js

@@ -572,6 +572,9 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         }
         const horizontalStep = advancePlayerMotion(horizontal, controllerIntent, forwardX, forwardZ, walkSpeed, dt, tuning.physics, { buffer: state.jumpBuffer, externalGrounding: true, authoritativeStep: tuning.authoritativeStep });
         state.controllerJumpHeld = intent.jumping;
+        // `jumpOffset` is this step's vertical displacement under the movement model's trapezoidal
+        // integration; the controller sweeps that instead of re-deriving `v * dt` from the end velocity.
+        const verticalStep = horizontal.jumpOffset;
         controller.restore({
             ...controller.state(),
             verticalVelocity: horizontal.verticalVelocity,
@@ -580,6 +583,7 @@ export function stepPlayerMovement(ctx, userId, input, dt, tuning, heading, pitc
         const result = controller.move(tuning.controller.backend, {
             motion: [horizontalStep.stepX, 0, horizontalStep.stepZ],
             dt: motionStepSeconds(dt, tuning.authoritativeStep),
+            verticalStep,
         });
         horizontal.verticalVelocity = controller.state().verticalVelocity;
         horizontal.jumpOffset = 0;

package/dist/physics/physicsBackendConformance.js

@@ -38,6 +38,23 @@ export function runPhysicsBackendConformance(create, harness) {
         expect(state.position[1]).toBeLessThan(0.7);
         expect(Math.abs(state.velocity[1])).toBeLessThan(0.5);
     });
+    test("the same wall-clock time simulates the same distance at 30, 60 and 144 fps", () => {
+        // A backend that honours `fixedDt` as one step per call simulates `fixedDt * fps` seconds per
+        // second of real time — half speed at 30 fps, 2.4x at 144 fps. Horizontal travel ignores the
+        // integrator, so the distance is exactly `v * realSeconds` for any backend that accumulates.
+        const backend = create();
+        const travelled = [];
+        for (const fps of [30, 60, 144]) {
+            const ball = backend.addBody({ shape: { kind: "sphere", radius: 0.2 }, position: [0, 8, 0], velocity: [10, 0, 0] });
+            for (let i = 0; i < fps; i += 1)
+                backend.step(1 / fps);
+            travelled.push(backend.body(ball).position[0]);
+            backend.removeBody(ball);
+        }
+        const spread = Math.max(...travelled) - Math.min(...travelled);
+        expect(travelled[1]).toBeGreaterThan(8);
+        expect(spread).toBeLessThan(0.2);
+    });
     test("raycast reports the floor with an upward normal and the right distance", () => {
         const backend = create();
         const ground = floor(backend);

package/dist/physics/physicsWorld.d.ts

@@ -276,6 +276,13 @@ export declare class PhysicsWorld {
     getStats(): PhysicsStats;
     private substep;
     private constrainBounds;
+    /**
+     * Coulomb friction against the bounds floor, using the same `friction` coefficient a contact
+     * applies: horizontal speed bleeds by `friction * |gravity| * dt` per substep. The old
+     * multiplicative form (`* (1 - friction)` every substep) removed 60 × 40% per second, so a body
+     * on the world floor stopped ~6× shorter than the same body on a static floor collider.
+     */
+    private applyFloorFriction;
     /**
      * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
      * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count

package/dist/physics/physicsWorld.js

@@ -565,7 +565,7 @@ export class PhysicsWorld {
             this.posX[i] += this.velX[i] * dt;
             this.posY[i] += this.velY[i] * dt;
             this.posZ[i] += this.velZ[i] * dt;
-            this.constrainBounds(i);
+            this.constrainBounds(i, dt, true);
         }
         this.buildGrid();
         const iterations = this.solverIterations;
@@ -575,10 +575,10 @@ export class PhysicsWorld {
                 this.solveJoints(dt);
         }
         for (let a = 0; a < this.awakeCount; a += 1)
-            this.constrainBounds(this.awakeList[a]);
+            this.constrainBounds(this.awakeList[a], dt, false);
         this.updateSleep();
     }
-    constrainBounds(i) {
+    constrainBounds(i, dt, frictionPass) {
         const min = this.bounds.min;
         const max = this.bounds.max;
         const e = this.restitution;
@@ -613,9 +613,8 @@ export class PhysicsWorld {
             this.posY[i] = loY;
             if (this.velY[i] < 0)
                 this.velY[i] = -this.velY[i] < rt ? 0 : this.velY[i] * -e;
-            const tf = 1 - this.friction;
-            this.velX[i] *= tf;
-            this.velZ[i] *= tf;
+            if (frictionPass)
+                this.applyFloorFriction(i, dt);
         }
         else if (this.posY[i] > hiY) {
             this.posY[i] = hiY;
@@ -623,6 +622,28 @@ export class PhysicsWorld {
                 this.velY[i] = this.velY[i] < rt ? 0 : -this.velY[i] * e;
         }
     }
+    /**
+     * Coulomb friction against the bounds floor, using the same `friction` coefficient a contact
+     * applies: horizontal speed bleeds by `friction * |gravity| * dt` per substep. The old
+     * multiplicative form (`* (1 - friction)` every substep) removed 60 × 40% per second, so a body
+     * on the world floor stopped ~6× shorter than the same body on a static floor collider.
+     */
+    applyFloorFriction(i, dt) {
+        const decel = this.friction * Math.abs(this.gravity) * dt;
+        if (!(decel > 0))
+            return;
+        const vx = this.velX[i];
+        const vz = this.velZ[i];
+        const speed = Math.sqrt(vx * vx + vz * vz);
+        if (speed <= decel) {
+            this.velX[i] = 0;
+            this.velZ[i] = 0;
+            return;
+        }
+        const keep = (speed - decel) / speed;
+        this.velX[i] = vx * keep;
+        this.velZ[i] = vz * keep;
+    }
     /**
      * Walk every broadphase cell body `i`'s AABB overlaps, invoking `visit(cell)` once per cell. The
      * cell-range math (six `cellCoord` calls plus the row-major triple loop) lives here so the count

package/dist/run/runLoop.d.ts

@@ -19,6 +19,28 @@ export interface RunOffer<T> {
     changeId: string | null;
     change: T | null;
 }
+/** One change a run could open with, in the shape a choice screen shows: the id and its payload. */
+export interface RunChoice<T> {
+    id: string;
+    change: T;
+}
+/** What the loop reports about the run it is playing, for a capture or devtools read. */
+export interface RunReadout {
+    /** The run in progress, or the last settled run when none is open. */
+    run: number;
+    /** What the run in progress carries and can still lose. */
+    carried: number;
+    banked: number;
+    lost: number;
+    /** The best single bank across the career. */
+    best: number;
+    /** The change the run in progress opened with, or the one the next run is offered. */
+    offered: string | null;
+}
+/** Read-only handle a capture or devtools uses to prove a run loop is live, not merely imported. */
+export interface RunProbe {
+    read(): RunReadout;
+}
 /** Everything a run loop stores as plain JSON: the run in progress plus lifetime totals. */
 export interface RunLoopState {
     /** The run in progress, or `0` before the first `start`. */
@@ -66,6 +88,17 @@ export interface RunLoop<T> {
     haul(): number;
     /** The run in progress's offer, or the offer the next `start` would open. */
     offer(): RunOffer<T>;
+    /**
+     * Up to `count` distinct changes the next run could open with, drawn weighted and in draw order,
+     * so a game can offer a choice instead of the single change {@link RunOffer} names. `choose` takes one.
+     */
+    present(count: number): RunChoice<T>[];
+    /**
+     * Open the next run around `changeId` (or around no change for `null`), which is how a presented
+     * choice becomes the change the run carries. Returns false for an id this loop's table does not
+     * carry, leaving the offer untouched.
+     */
+    choose(changeId: string | null): boolean;
     /**
      * Close the run in progress: bank the haul scaled by `multiplier`, or lose it. Throws when no run
      * is open, so a double settle cannot bank the same haul twice.
@@ -81,8 +114,18 @@ export interface RunLoop<T> {
  * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
  * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
  * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
- * seed and the same run history give the same sequence, before or after a save/load.
+ * seed and the same run history give the same sequence, before or after a save/load. `present(count)`
+ * draws several of those changes for a choice screen and `choose(id)` adopts the pick as the next run's
+ * change.
  *
  * @capability run-loop bank or lose what a run carries, with one deterministic change per run
  */
 export declare function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T>;
+/**
+ * Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state
+ * the live run, what it carries, what it banked or lost and the change it offers. Reads only; it never
+ * starts, settles or changes a run. Returns the uninstaller.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export declare function installRunProbe<T>(loop: RunLoop<T>): () => void;

package/dist/run/runLoop.js

@@ -10,7 +10,9 @@ function positive(value) {
  * with the game (pair it with `progression/careerBank`). After each settled run the loop draws the next
  * run's change from `changes`: eligible when `after <= completed`, never the change just played unless
  * it is the only one eligible, weighted by `weight`. The draw is `seededRng(seed:run:N)`, so the same
- * seed and the same run history give the same sequence, before or after a save/load.
+ * seed and the same run history give the same sequence, before or after a save/load. `present(count)`
+ * draws several of those changes for a choice screen and `choose(id)` adopts the pick as the next run's
+ * change.
  *
  * @capability run-loop bank or lose what a run carries, with one deterministic change per run
  */
@@ -30,14 +32,18 @@ export function createRunLoop(config) {
     let lostTotal = 0;
     let bestHaul = 0;
     function drawFor(index, previous) {
-        const eligible = table.filter((change) => (change.after ?? 0) <= index - 1);
-        const fresh = eligible.filter((change) => change.id !== previous);
-        // A one-entry table still offers its change rather than nothing.
-        const pool = fresh.length > 0 ? fresh : eligible;
+        const pool = poolFor(index, previous);
         const rng = seededRng(`${config.seed}:run:${index}`);
         const drawn = pickWeighted(rng, pool, (change) => change.weight ?? 1) ?? null;
         return { run: index, changeId: drawn?.id ?? null, change: drawn?.value ?? null };
     }
+    /** The changes run `index` may open with: `after`-eligible, and never the one just played while others remain. */
+    function poolFor(index, previous) {
+        const eligible = table.filter((change) => (change.after ?? 0) <= index - 1);
+        const fresh = eligible.filter((change) => change.id !== previous);
+        // A one-entry table still offers its change rather than nothing.
+        return fresh.length > 0 ? fresh : eligible;
+    }
     function offer() {
         // An open run's change was adopted at `start`, so the offer repeats it instead of redrawing.
         if (run > completed) {
@@ -62,6 +68,32 @@ export function createRunLoop(config) {
         },
         haul: () => haul,
         offer,
+        present(count) {
+            const index = run > completed ? run : completed + 1;
+            const remaining = poolFor(index, changeId);
+            const drawn = [];
+            const wanted = Number.isFinite(count) ? Math.max(0, Math.floor(count)) : 0;
+            const rng = seededRng(`${config.seed}:present:${index}`);
+            while (drawn.length < wanted && remaining.length > 0) {
+                const picked = pickWeighted(rng, remaining, (change) => change.weight ?? 1);
+                if (picked === undefined)
+                    break;
+                drawn.push({ id: picked.id, change: picked.value });
+                remaining.splice(remaining.indexOf(picked), 1);
+            }
+            return drawn;
+        },
+        choose(nextChangeId) {
+            if (nextChangeId !== null && !known.has(nextChangeId))
+                return false;
+            // A settled loop has no run to adopt the pick, so the pick opens the next one.
+            if (run <= completed) {
+                run = completed + 1;
+                haul = 0;
+            }
+            changeId = nextChangeId;
+            return true;
+        },
         settle(outcome, multiplier) {
             if (run <= completed)
                 throw new Error("run loop: no run is open to settle");
@@ -90,3 +122,32 @@ export function createRunLoop(config) {
         },
     };
 }
+const RUN_PROBE_KEY = "__jgengineRun";
+/**
+ * Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state
+ * the live run, what it carries, what it banked or lost and the change it offers. Reads only; it never
+ * starts, settles or changes a run. Returns the uninstaller.
+ *
+ * @capability run-loop bank or lose what a run carries, with one deterministic change per run
+ */
+export function installRunProbe(loop) {
+    const scope = globalThis;
+    const probe = {
+        read() {
+            const state = loop.snapshot();
+            return {
+                run: state.run,
+                carried: state.haul,
+                banked: state.bankedTotal,
+                lost: state.lostTotal,
+                best: state.bestHaul,
+                offered: loop.offer().changeId,
+            };
+        },
+    };
+    scope[RUN_PROBE_KEY] = probe;
+    return () => {
+        if (scope[RUN_PROBE_KEY] === probe)
+            delete scope[RUN_PROBE_KEY];
+    };
+}