@jgengine/core 0.36.0 → 0.37.0

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 } }),
+        },
+    };
+}

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.36.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,64 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.36.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`.",

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