@jgengine/core 0.36.0 → 0.38.0

package/dist/world/features.d.ts

@@ -214,7 +214,21 @@ export interface TerrainEnvironmentConfig {
     materialRegions?: readonly TerrainMaterialRegion[];
     /** Ordered z-banded ground palettes that cross-fade along the world's z axis (vale → marsh → peaks). Painted under `materialRegions`. */
     biomeBands?: readonly BiomeBand[];
-    segments?: number;
+    /**
+     * Grid segments per axis, or `[x, z]` for a non-square grid. Honoured as-is for compatibility,
+     * but a count says nothing about ground detail until you know the bounds — prefer `cellSize`.
+     */
+    segments?: number | readonly [x: number, z: number];
+    /**
+     * Ground resolution as world units per quad — the density form of `segments`. The per-axis grid is
+     * derived from `bounds`, so the same `cellSize` on a bigger world spends more cells instead of
+     * stretching one fixed count over it. Set this or `segments`, never both.
+     *
+     * A world that needs mixed density next (a coarse far ring around a fine playable core, or bands
+     * that tighten over a painted path) would carry `density?: readonly { cellSize: number; radius?: number }[]`
+     * in place of this single number. Not built.
+     */
+    cellSize?: number;
     seed?: string;
     frequency?: number;
     octaves?: number;

package/dist/world/features.js

@@ -79,6 +79,53 @@ export function environment(config = {}) {
         ...(config.clearings === undefined || config.clearings.length === 0 ? {} : { clearings: config.clearings }),
     };
 }
+/**
+ * Vertex ceiling for a terrain grid derived from `cellSize`. A density target that reads fine
+ * ("0.4 m cells") can quietly ask for millions of vertices on a large world; past this the
+ * declaration fails with its own numbers instead of booting a ground mesh nobody can afford.
+ */
+const TERRAIN_VERTEX_CEILING = 1_000_000;
+function gridVertices(bounds, cellSize) {
+    const x = Math.max(1, Math.round(bounds.w / cellSize));
+    const z = Math.max(1, Math.round(bounds.d / cellSize));
+    return { x, z, vertices: (x + 1) * (z + 1) };
+}
+/** Smallest `cellSize` whose derived grid fits the ceiling — quoted back in the failure, so the fix is one number. */
+function minimumCellSize(bounds) {
+    let lo = Math.sqrt((bounds.w * bounds.d) / TERRAIN_VERTEX_CEILING) * 0.5;
+    let hi = Math.max(bounds.w, bounds.d, 1);
+    for (let step = 0; step < 64; step += 1) {
+        const mid = (lo + hi) / 2;
+        if (gridVertices(bounds, mid).vertices > TERRAIN_VERTEX_CEILING)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return hi;
+}
+/**
+ * Resolves the authored grid: `segments` passes through, `cellSize` derives a per-axis count from the
+ * bounds. Both forms in one declaration is an error rather than a silent precedence rule, because the
+ * pair produces exactly the accidental density this API exists to remove.
+ */
+function terrainSegments(bounds, config) {
+    const { segments, cellSize } = config;
+    if (segments !== undefined && cellSize !== undefined) {
+        throw new Error("terrain: set segments or cellSize, not both — cellSize (world units per quad) derives the grid from the bounds, segments counts it directly. Keep cellSize and drop segments.");
+    }
+    if (cellSize === undefined)
+        return segments;
+    if (!Number.isFinite(cellSize) || cellSize <= 0) {
+        throw new Error(`terrain: cellSize must be a positive number of world units per quad (got ${cellSize})`);
+    }
+    const { x, z, vertices } = gridVertices(bounds, cellSize);
+    if (vertices > TERRAIN_VERTEX_CEILING) {
+        // Rounded up: the quoted cell size has to pass the same check, not read well and fail again.
+        const minimum = Math.ceil(minimumCellSize(bounds) * 1_000) / 1_000;
+        throw new Error(`terrain: cellSize ${cellSize} on ${bounds.w}×${bounds.d} bounds is ${x}×${z} cells = ${vertices.toLocaleString("en-US")} vertices, over the ${TERRAIN_VERTEX_CEILING.toLocaleString("en-US")}-vertex ceiling. Use cellSize ${minimum} or larger, or shrink the bounds.`);
+    }
+    return x === z ? x : [x, z];
+}
 /** Declares a heightfield terrain patch for `environment()` — bounds, noise, materials, and flatten masks. */
 export function terrain(config = {}) {
     if (config.baseHeight !== undefined &&
@@ -87,9 +134,11 @@ export function terrain(config = {}) {
         typeof console !== "undefined") {
         console.warn("[jgengine:terrain] baseHeight is set but height is not — height is the noise amplitude (defaulting to 0 here), so this terrain is a flat plateau at baseHeight. Set height explicitly (height: 0 for an intentional plateau) to silence this.");
     }
+    const bounds = config.bounds ?? { w: 512, d: 512 };
+    const segments = terrainSegments(bounds, config);
     return withOptional({
         kind: "terrain",
-        bounds: config.bounds ?? { w: 512, d: 512 },
+        bounds,
         height: config.height ?? 0,
     }, {
         ...(config.heightMap === undefined ? {} : { heightMap: config.heightMap }),
@@ -98,7 +147,7 @@ export function terrain(config = {}) {
         ...(config.colors === undefined ? {} : { colors: config.colors }),
         ...(config.materialRegions === undefined ? {} : { materialRegions: config.materialRegions }),
         ...(config.biomeBands === undefined ? {} : { biomeBands: config.biomeBands }),
-        ...(config.segments === undefined ? {} : { segments: config.segments }),
+        ...(segments === undefined ? {} : { segments }),
         ...(config.seed === undefined ? {} : { seed: config.seed }),
         ...(config.frequency === undefined ? {} : { frequency: config.frequency }),
         ...(config.octaves === undefined ? {} : { octaves: config.octaves }),

package/dist/world/lod.d.ts

@@ -20,4 +20,12 @@ export interface LodScheduler {
     snapshot(): LodSchedulerState;
     restore(next: LodSchedulerState): void;
 }
+/**
+ * Index of the band `distance` falls in, `-1` past the last band. Bands must already be sorted near
+ * to far. The scheduler and `createModelVariantSelector` both read distances through this one
+ * function, so simulation throttling and mesh detail cannot disagree about what band an id is in.
+ */
+export declare function lodBandIndex(bands: readonly {
+    maxDistance: number;
+}[], distance: number): number;
 export declare function createLodScheduler(config: LodSchedulerConfig): LodScheduler;

package/dist/world/lod.js

@@ -7,17 +7,25 @@ function hashSeed(text) {
     }
     return h >>> 0;
 }
+/**
+ * Index of the band `distance` falls in, `-1` past the last band. Bands must already be sorted near
+ * to far. The scheduler and `createModelVariantSelector` both read distances through this one
+ * function, so simulation throttling and mesh detail cannot disagree about what band an id is in.
+ */
+export function lodBandIndex(bands, distance) {
+    for (let i = 0; i < bands.length; i++) {
+        if (distance <= bands[i].maxDistance)
+            return i;
+    }
+    return -1;
+}
 export function createLodScheduler(config) {
     const bands = [...config.bands].sort((a, b) => a.maxDistance - b.maxDistance);
     const beyondInterval = config.beyondInterval ?? null;
     const stagger = config.stagger ?? true;
     const buckets = new Map();
     function bandIndex(distance) {
-        for (let i = 0; i < bands.length; i++) {
-            if (distance <= bands[i].maxDistance)
-                return i;
-        }
-        return -1;
+        return lodBandIndex(bands, distance);
     }
     function effectiveInterval(band) {
         return band === -1 ? beyondInterval : bands[band].interval;

package/dist/world/modelLod.d.ts

@@ -0,0 +1,44 @@
+import type { LodBand } from "./lod.js";
+/** One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws. */
+export interface ModelVariantConfig {
+    /** GLB url for this level — the source asset for the near level, a decimated asset for the far ones. */
+    url: string;
+    /** Furthest distance in metres from the camera this level draws. The last level omits it and covers everything beyond the level before it. */
+    maxDistance?: number;
+}
+/**
+ * Ordered mesh detail levels for one model, switched per instance by camera distance. The first level
+ * is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses
+ * this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
+ */
+export interface ModelVariantLodConfig {
+    /** Levels ordered near to far; the first covers everything up to its `maxDistance`. Two or more. */
+    levels: readonly ModelVariantConfig[];
+    /** Metres an instance must travel past a switch boundary before it changes level, so a camera resting on the boundary cannot flicker. Default 6. */
+    hysteresis?: number;
+}
+/** Plain JSON state of a {@link ModelVariantSelector}: each id's current level index. */
+export interface ModelVariantSelectorState {
+    levels: Record<string, number>;
+}
+/** Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it. */
+export interface ModelVariantSelector {
+    /** Levels near to far, with the last level's `maxDistance` normalized to `Infinity`. */
+    levels(): readonly {
+        url: string;
+        maxDistance: number;
+    }[];
+    /** The same boundaries as scheduler bands, so a `createLodScheduler` never throttles an id at a different distance than its mesh switches. */
+    bands(): readonly LodBand[];
+    /** Level index for `id` at `distance` metres, carrying hysteresis from its previous answer. */
+    level(id: string, distance: number): number;
+    forget(id: string): void;
+    clear(): void;
+    size(): number;
+    snapshot(): ModelVariantSelectorState;
+    restore(next: ModelVariantSelectorState): void;
+}
+/** Metres an instance must travel past a switch boundary before it changes level unless the model declares its own. */
+export declare const DEFAULT_VARIANT_HYSTERESIS = 6;
+/** Builds the per-instance distance switch for a model's variant levels. */
+export declare function createModelVariantSelector(config: ModelVariantLodConfig): ModelVariantSelector;

package/dist/world/modelLod.js

@@ -0,0 +1,75 @@
+import { lodBandIndex } from "./lod.js";
+/** Metres an instance must travel past a switch boundary before it changes level unless the model declares its own. */
+export const DEFAULT_VARIANT_HYSTERESIS = 6;
+function normalize(config) {
+    if (!Array.isArray(config.levels) || config.levels.length < 2) {
+        throw new Error("Model variants need at least two levels: the full mesh and a cheaper one");
+    }
+    let previous = 0;
+    return config.levels.map((level, index) => {
+        if (typeof level.url !== "string" || level.url.length === 0) {
+            throw new Error(`Model variant level ${index} needs a url`);
+        }
+        const last = index === config.levels.length - 1;
+        const maxDistance = level.maxDistance;
+        if (last) {
+            if (maxDistance !== undefined && maxDistance !== Infinity) {
+                throw new Error("The last model variant level draws at every distance; leave its maxDistance undefined");
+            }
+            return { url: level.url, maxDistance: Infinity };
+        }
+        if (typeof maxDistance !== "number" || !Number.isFinite(maxDistance) || maxDistance <= previous) {
+            throw new Error(`Model variant level ${index} needs a finite maxDistance above the level before it`);
+        }
+        previous = maxDistance;
+        return { url: level.url, maxDistance };
+    });
+}
+/** Builds the per-instance distance switch for a model's variant levels. */
+export function createModelVariantSelector(config) {
+    const levels = normalize(config);
+    const hysteresis = Math.max(0, config.hysteresis ?? DEFAULT_VARIANT_HYSTERESIS);
+    const bands = levels.map((level) => ({ maxDistance: level.maxDistance, interval: 0 }));
+    const current = new Map();
+    const last = levels.length - 1;
+    return {
+        levels() {
+            return levels;
+        },
+        bands() {
+            return bands;
+        },
+        level(id, distance) {
+            let index = current.get(id);
+            if (index === undefined) {
+                const band = lodBandIndex(bands, distance);
+                index = band === -1 ? last : band;
+            }
+            else {
+                while (index < last && distance > levels[index].maxDistance + hysteresis)
+                    index += 1;
+                while (index > 0 && distance <= levels[index - 1].maxDistance - hysteresis)
+                    index -= 1;
+            }
+            current.set(id, index);
+            return index;
+        },
+        forget(id) {
+            current.delete(id);
+        },
+        clear() {
+            current.clear();
+        },
+        size() {
+            return current.size;
+        },
+        snapshot() {
+            return { levels: Object.fromEntries(current) };
+        },
+        restore(next) {
+            current.clear();
+            for (const [id, index] of Object.entries(next.levels))
+                current.set(id, index);
+        },
+    };
+}

package/dist/world.d.ts

@@ -129,12 +129,13 @@ export { type Aabb, type AvoidZone } from "./world/geometry.js";
 export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";
 export { grounded } from "./world/grounded.js";
-export { createLodScheduler } from "./world/lod.js";
+export { createLodScheduler, lodBandIndex } from "./world/lod.js";
 export { createAnnotationLayer, type AnnotationLayer, type AnnotationLayerOptions, type AnnotationSnapshot, type MapNote, type MapShapeAnnotation, type MapStroke, } from "./world/mapAnnotations.js";
 export { mapLayerColor, type MapCellStates, type MapRoute, type MapZone } from "./world/mapLayers.js";
 export { DEFAULT_MARKER_KINDS, createMarkerSet, createMarkerSource, markerKindStyle, type MapMarker, type MarkerCollection, type MarkerKindStyle, type MarkerSet, type MarkerSource, type MarkerSourceOptions, type MarkerView, } from "./world/markers.js";
 export { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, type Cardinal, type MinimapView, type WorldXZ, } from "./world/minimap.js";
 export { DEFAULT_MINIMAP_PALETTE, bakeMinimapBackground, bakeMinimapImage, encodeBakePng, minimapBakeToPngDataUri, type MinimapBake, type MinimapBakeBounds, type MinimapBakeOptions, type MinimapBakePalette, type MinimapBakeSource, type MinimapBakeZone, } from "./world/minimapBake.js";
+export { DEFAULT_VARIANT_HYSTERESIS, createModelVariantSelector, type ModelVariantConfig, type ModelVariantLodConfig, type ModelVariantSelector, type ModelVariantSelectorState, } from "./world/modelLod.js";
 export { placeAlongPath } from "./world/pathInstances.js";
 export { withPathProfiles, type PathHeightPolicy, type PathRetaining, type TerrainPathProfile, } from "./world/pathTerrain.js";
 export { isPlaceWorld, resolveWorldPhysics, seedForPlace, world, type BoardGround, type BoardGroundSize, type FlatGround, type FlatGroundSize, type GroundConfig, type GroundGenerator, type GroundMode, type PlaceConfig, type PlaceWorldFeature, type ResolvedGround, type RoundGround, type RoundGroundSize, type SurfaceLaws, type VoxelGround, type VoxelGroundSize, } from "./world/place.js";

package/dist/world.js

@@ -129,12 +129,13 @@ export {} from "./world/geometry.js";
 export { GRASS_SCHEMA } from "./world/grassKind.js";
 export { resolveGridInstances } from "./world/gridInstances.js";
 export { grounded } from "./world/grounded.js";
-export { createLodScheduler } from "./world/lod.js";
+export { createLodScheduler, lodBandIndex } from "./world/lod.js";
 export { createAnnotationLayer, } from "./world/mapAnnotations.js";
 export { mapLayerColor } from "./world/mapLayers.js";
 export { DEFAULT_MARKER_KINDS, createMarkerSet, createMarkerSource, markerKindStyle, } from "./world/markers.js";
 export { bearingToCardinal, clampToMinimapEdge, compassBearing, headingToBearing, projectToMinimap, relativeBearing, unprojectFromMinimap, } from "./world/minimap.js";
 export { DEFAULT_MINIMAP_PALETTE, bakeMinimapBackground, bakeMinimapImage, encodeBakePng, minimapBakeToPngDataUri, } from "./world/minimapBake.js";
+export { DEFAULT_VARIANT_HYSTERESIS, createModelVariantSelector, } from "./world/modelLod.js";
 export { placeAlongPath } from "./world/pathInstances.js";
 export { withPathProfiles, } from "./world/pathTerrain.js";
 export { isPlaceWorld, resolveWorldPhysics, seedForPlace, world, } from "./world/place.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.36.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.36.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.38.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-combat/SKILL.md

@@ -31,6 +31,13 @@ see
 For scene-backed `createProjectileSystem`, inject authoritative `rng`; spread
 samples independent pellet rays and prediction stays on the center ray. The
 weapon-plumbing recipe covers the bounded cone and cover contracts.
+When a weapon is not a gun — grenade, mortar, arrow, hitscan explosive — state
+how the shot travels and what it does on contact as one `ShotSpec`
+(`combat/shotSpec`) and pass it as `ProjectileShotInput.spec`, or read
+`resolveShotSpec` yourself. Delivery is `delivery.kind` ("trace" or "body") and
+nothing else decides it; a splash, damage or falloff field never makes a shot
+travel. A new weapon is a few fields, not a code path, so never branch combat
+code on a weapon id or add a second classifier.
 Tune how a weapon feels (recoil, bloom, ADS, shake and rumble) with the
 [weapon-feel recipe](recipes/weapon-feel.md): feel target → `measureWeapon`
 numbers → handling knobs, and `createWeaponFeedbackSignals` into the feedback mixer.

package/skills/jgengine-combat/api.md

@@ -44,10 +44,15 @@
 - `DEFAULT_ARMOR_HALF_VALUE` (const): const DEFAULT_ARMOR_HALF_VALUE: 100 — Default armor points at which a hit is halved.
 - `DEFAULT_CRIT_MULTIPLIER` (const): const DEFAULT_CRIT_MULTIPLIER: 2 — Default crit multiplier for a zone that does not name one.
 - `DEFAULT_EYE_HEIGHT` (const): const DEFAULT_EYE_HEIGHT: number — Shot-origin and first-person camera eye height above an entity's position: 90% of the default 1.8m hitbox top.
+- `DEFAULT_FALLOFF_END_SCALE` (const): const DEFAULT_FALLOFF_END_SCALE: 0.5 — Damage multiplier left at the end of falloff when a shot names no end scale.
 - `DEFAULT_FIRE_PULSE_SECONDS` (const): const DEFAULT_FIRE_PULSE_SECONDS: 0.12 — Default `RenderCueTuning.firePulseSeconds`.
 - `DEFAULT_HIT_PULSE_SECONDS` (const): const DEFAULT_HIT_PULSE_SECONDS: 0.2 — Default `RenderCueTuning.hitPulseSeconds`.
 - `DEFAULT_MAX_MITIGATION` (const): const DEFAULT_MAX_MITIGATION: 0.9 — Default ceiling on armor mitigation, so armor never fully negates a hit.
 - `DEFAULT_RENDER_CUES` (const): const DEFAULT_RENDER_CUES: Readonly<EntityRenderCues> — Neutral starting cue set: idle, unarmed, undamaged.
+- `DEFAULT_SHOT_PENETRATION` (const): const DEFAULT_SHOT_PENETRATION: 0 — Most extra hits a shot may pass through when it names no penetration.
+- `DEFAULT_SHOT_RADIUS` (const): const DEFAULT_SHOT_RADIUS: 0.5 — Hit-sphere radius of a body that names none, m.
+- `DEFAULT_SHOT_RANGE` (const): const DEFAULT_SHOT_RANGE: 100 — Furthest a shot resolves when the delivery names no range, m.
+- `DEFAULT_SHOT_SPEED` (const): const DEFAULT_SHOT_SPEED: 15 — Launch speed of a body that names none, m/s.
 - `DEFAULT_VFX_PRESET` (const): const DEFAULT_VFX_PRESET: VfxPresetName — The fallback flavor used when a `vfx()` call names an unknown preset — so a typo still shows a spark instead of nothing.
 - `DEFAULT_WEAPON_PELLETS_IN_FLIGHT` (const): const DEFAULT_WEAPON_PELLETS_IN_FLIGHT: 32 — Default live-pellet cap for a weapon that does not name one.
 - `DamageChannelId` (type): type DamageChannelId = string — Caller-owned id for a damage channel — `"fire"`, `"ballistic"`, `"physical"`, `"corrosive"`. The engine never branches on the value; a channel is whatever a game's data declares.
@@ -123,6 +128,7 @@
 - `RenderCueTuning` (interface): interface RenderCueTuning — Tuning knobs for `advanceMotionCues` / `useEntityRenderCues`; every field has a default, override only what a weapon/rig's feel needs to differ.
 - `ResolvedMatchup` (interface): interface ResolvedMatchup — Fully-resolved matchup outputs (every axis populated) plus the contributions that produced them.
 - `ResolvedShot` (interface): interface ResolvedShot — A shot's resolved firing geometry in world space: `origin` is the point the projectile/ray starts from and `direction` is its normalized aim vector, both computed by {@link resolveShot} from the shooter's position, facing, and the chosen origin policy.
+- `ResolvedShotSpec` (interface): interface ResolvedShotSpec — A spec with every default filled in. Read `mode` and the branch it names, never the raw spec.
 - `ResourcePool` (interface): interface ResourcePool { current(): number; max(): number; setMax(value: number): void; fraction(): number; canSpend(amount: number): boolean; spend(amount: number): boolean; gain(amount: number): number; set(value: number): void; tick(dtSeconds: number): void; i… — ⚠ undocumented · used by `createResourcePool`: A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.
 - `RewardClaimSpec` (interface): interface RewardClaimSpec — How a `claimed` allocation exposes its pool: open first-come (`first`) or `reserved` to one recipient.
 - `RewardGrant` (interface): interface RewardGrant — An authoritative, serializable award of one result stack to one recipient — carries `via` (the policy that produced it) and `private` (replication scope) so provenance and visibility survive save/load and viewer projection. Applying a grant twice with the same identity is the caller's idempotency contract; this seam only decides who is owed what.
@@ -130,7 +136,23 @@
 - `RewardRecipient` (interface): interface RewardRecipient — A participant that may receive rewards — an opaque recipient id (player, team, party slot) with an optional split `weight` (shared policy), eligibility `tags`, and an `eligible` gate. Ineligible recipients are excluded before any allocation decision so they never perturb others' streams.
 - `RewardResult` (interface): interface RewardResult — One indivisible reward to distribute among participants — an opaque result id (a rolled drop, a currency bundle, a quest token) with an optional stack `count` and free-form `tags` for eligibility and provenance. Allocation never interprets the id; generation (loot tables, roll formulas) owns what it means, keeping the seam genre-agnostic.
 - `RewardShare` (interface): interface RewardShare — A `{ result, count }` slice of a reward — the unit shared pools and grants are expressed in.
+- `SHOT_GRAVITY` (const): const SHOT_GRAVITY: 9.8 — Standard gravity used to scale `ShotBody.gravity`, m/s².
+- `ShotArc` (interface): interface ShotArc extends ShotLaunch — Where a body lands and how long it took, in the same numbers the runtime simulates.
+- `ShotBody` (interface): interface ShotBody — A travelling body simulated over time. Every dimension is stated; nothing is read off another field, so a slow arrow with a splash and a fast bullet without one are the same shape.
+- `ShotContact` (interface): interface ShotContact — What a shot does on contact: damage, falloff, penetration, splash, ricochet, statuses.
+- `ShotDamage` (interface): interface ShotDamage — One damage channel a shot applies on contact.
+- `ShotDelivery` (type): type ShotDelivery = ShotTrace | ShotBody — How the shot reaches its target.
+- `ShotFalloff` (interface): interface ShotFalloff — Linear damage falloff between two distances.
+- `ShotHitOutcome` (interface): interface ShotHitOutcome — What one contact does: whether the shot still carries damage, at what scale, and whether it goes on.
+- `ShotLaunch` (interface): interface ShotLaunch — Straight-line flight of a body, for a caller that only needs where it starts and how fast.
 - `ShotOriginPolicy` (type): type ShotOriginPolicy = | { kind: "converge"; muzzle?: EntityPosition; height?: number } | { kind: "eye"; height?: number } | { kind: "legacy" } | { kind: "entity" } | { kind: "entityOffset"; offset: EntityPosition } | { kind: "muzzle"; offset?: EntityPosition } | { kind: "camera"; origin: EntityPos… — How a shot's world-space origin (and optional direction) is resolved before prediction/settlement. - `converge` — the shot leaves the gun `muzzle` yet still passes through whatever the shooter's sightline (crosshair) covers: origin is the muzzle offset, direction is bent from the muzzle to the eye ray's aim point. The projectile system's default for a free `{ yaw, pitch }` aim, so a bullet visibly comes from the barrel without missing the reticle. Needs a scene raycast to find the aim point (`convergeShot`); a bare `resolveShot` degrades to a straight muzzle ray. Passes an explicit `{ origin, direction }` aim through untouched. - `eye` — `aim.origin` when present, else the shooter's entity position raised to eye height; the shot traces the shooter's sightline, so what the crosshair covers is what gets hit. - `legacy` — `aim.origin` when present, else the shooter's raw entity position (feet). - `entity` — always the shooter's entity position. - `entityOffset` / `muzzle` — entity-local offset rotated by the shooter's yaw (muzzle on a weapon model). - `camera` — explicit camera/reticle world origin (and optional direction override). - `world` — absolute world origin.
+- `ShotPenetration` (interface): interface ShotPenetration — Extra targets a hit passes through.
+- `ShotRicochet` (interface): interface ShotRicochet — Bounces off the first surface contacted.
+- `ShotSpec` (interface): interface ShotSpec — A shot as plain data: how it travels and what it does on arrival. Every field but `delivery.kind` is optional with a documented default, so a plain gun is three lines.
+- `ShotSplash` (interface): interface ShotSplash — Area damage around the contact point.
+- `ShotStatReader` (type): type ShotStatReader = (stat: string) => number | null — Reads a numeric stat by name; the shape every item registry already exposes.
+- `ShotTrace` (interface): interface ShotTrace — An instant trace: the shot resolves on the tick it is fired and never travels.
+- `ShotVec3` (type): type ShotVec3 = readonly [number, number, number] — 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.
 - `SpawnProvider` (type): type SpawnProvider = ( params: Readonly<Record<string, unknown>>, ctx: SpawnProviderContext, ) => readonly EncounterSpawnRequest[] — A spawn provider: given the phase's `params` and context, returns the spawn requests to emit on enter. Deterministic; reads authored scene points from `ctx.spawnPoints` rather than embedding coordinates.
 - `SpawnProviderContext` (interface): interface SpawnProviderContext — Evaluation context a spawn provider receives when its phase is entered.
 - `SquadCombat` (interface): interface SquadCombat — Drive a squad: cover by threat, flanking, fire discipline, suppression and retreat.
@@ -290,12 +312,18 @@
 - `resolveReceivedDamage` (function): function resolveReceivedDamage(input: ReceivedDamageInput): ReceivedDamageResult — Run receiver-side modifiers over an incoming hit, in ascending `order`, recording every step. Amplification, reduction, caps, conversion, redirection, and immunity are all data — the engine applies whichever policies the target's modifiers declare and never branches on channel names. Pure over serializable data with bounded work (one pass over the modifier list); an `immune` policy short-circuits the remaining modifiers.
 - `resolveResistance` (function): function resolveResistance<TCategory extends string = string, TProperty extends string = string>(matrix: ResistanceMatrix<TCategory, TProperty>, category: TCategory | string, targetProperties: readonly (TProperty | string)[]): ResistanceResult — ⚠ undocumented
 - `resolveShot` (function): function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy: ShotOriginPolicy = { kind: "eye" }): ResolvedShot | null — Resolves a shot's world origin and direction from the shooter's eye or muzzle and an {@link Aim}, ready for `ctx.scene.raycast` — the aim half of a hitscan weapon.
+- `resolveShotSpec` (function): function resolveShotSpec(spec: ShotSpec): ResolvedShotSpec — 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.
 - `resolveStatusApplication` (function): function resolveStatusApplication(input: StatusApplicationInput): StatusApplicationOutcome — Resolve one status application: reject on immunity, roll landing chance against injected RNG, scale magnitude/duration by the matchup, then fold into any existing instance per the stacking policy. Deterministic given a seeded `rng`; pure over serializable data, so authority can run it and replicate only the returned `instance`.
 - `resolveTableDamage` (function): function resolveTableDamage(table: DamageTableDef, input: { type: string; resistance: string; armor?: number; base?: number }): DamageTableRow — Resolve one hit through the table: type multiplier, then armor mitigation, and the base scaled by both. Formula order matters only for the numbers a UI shows — the product is the same.
 - `resolveVfxPreset` (function): function resolveVfxPreset(name: string | undefined, overrides?: Partial<VfxPreset>): VfxPreset — Resolve a named visual flavor into a concrete `{ kind, color, durationMs?, radius? }`, with any provided `overrides` winning field by field. An unknown name resolves to {@link DEFAULT_VFX_PRESET} rather than throwing, so a flavor typo degrades to a visible spark. Used by `ctx.scene.entity.vfx({ preset })`; call it directly when you need the raw numbers (e.g. to seed a retained `vfxInstance` from the same vocabulary).
 - `rollCheck` (function): function rollCheck(input: CheckInput, rng?: () => number): CheckResult — Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
 - `scoreCoverPoint` (function): function scoreCoverPoint(point: CoverPoint, query: CoverQuery): CoverChoice | null — Score one stand point against the threats the member remembers. `hidden` is the confidence-weighted share of remembered threats that cannot see the point, so a point that hides from the shooter that matters scores over one that hides from a fading one. Returns `null` when nothing it can hide from is worth considering.
 - `selectCover` (function): function selectCover(points: readonly CoverPoint[], query: CoverQuery): CoverChoice | null — The best of `points` under one {@link CoverQuery}, ties broken by point id. Pass the candidate set the injected query already bounded; this scores what it is given.
+- `shotArc` (function): function shotArc(shot: ResolvedShotSpec, origin: ShotVec3, direction: ShotVec3): ShotArc — 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.
+- `shotFalloffAt` (function): function shotFalloffAt(shot: ResolvedShotSpec, distance: number): number — Damage multiplier from falloff at `distance`; `1` with no falloff.
+- `shotFuseSeconds` (function): function shotFuseSeconds(shot: ResolvedShotSpec): number | null — Number of seconds the body flies before its fuse ends the flight, or `null` when it flies to contact.
+- `shotHitOutcome` (function): function shotHitOutcome(shot: ResolvedShotSpec, distance: number, hitIndex: number): ShotHitOutcome — 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.
+- `shotSpecFromStats` (function): function shotSpecFromStats(read: ShotStatReader): ShotSpec — Adapt the numeric stat keys older item data carries to a spec. This is the only place those keys are read, and delivery is decided by the keys that describe travel (`projectile.*`) alone: a splash radius or a damage number never turns a trace into a body.
 - `startEncounter` (function): function startEncounter<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, ctx: EncounterContext = {}): EncounterStep<TData> — Start a created encounter: enter the first root phase, descending to its first leaf, and return the initial enter/spawn events. A no-op (with no events) on an already-started or empty encounter. Mutates and returns `state`.
 - `statusEffectRemainingFraction` (function): function statusEffectRemainingFraction(view: StatusEffectView): number — Fraction of the countdown still remaining, clamped to `[0,1]` — the value a countdown ring fills to. Returns `0` when the duration is non-positive. Pure; safe to call every frame.
 - `threatsFromMemory` (function): function threatsFromMemory(perception: PerceptionService, observerId: string, nowMs: number, options: ThreatReadOptions = {}): ThreatReading[] — Read one member's threat list out of its perception memory — the only source of threat. Sorted by confidence, then recency, then id, and bounded by `max`, so a crowded memory cannot grow the tick.
@@ -627,7 +655,7 @@
 - `ProjectileObjectsDeps` (interface): interface ProjectileObjectsDeps { list(): readonly {instanceId: string; catalogId: string; position: readonly [number, number, number]; rotationY?: number;}[]; inBox?(min: EntityPosition, max: EntityPosition): readonly {instanceId: string; catalogId: string; position: rea… — ⚠ undocumented
 - `ProjectilePrediction` (interface): interface ProjectilePrediction { hits: ProjectileHit[]; blocked?: boolean; origin?: EntityPosition; direction?: EntityPosition; firstImpact?: ProjectileHit | null } — ⚠ undocumented
 - `ProjectileSettleReport` (interface): interface ProjectileSettleReport — Exactly-once settlement with launch identity and actual applied effects.
-- `ProjectileShotInput` (interface): interface ProjectileShotInput { from: string; via: EffectVia; aim: Aim; effect: string; originPolicy?: ShotOriginPolicy; travel?: ProjectileTravelConfig } — ⚠ undocumented
+- `ProjectileShotInput` (interface): interface ProjectileShotInput { from: string; via: EffectVia; spec?: ShotSpec; aim: Aim; effect: string; originPolicy?: ShotOriginPolicy; travel?: ProjectileTravelConfig } — ⚠ undocumented
 - `ProjectileShotState` (interface): interface ProjectileShotState — Serializable captured launch and settlement state.
 - `ProjectileSystem` (interface): interface ProjectileSystem { willHitProjectile(input: ProjectileShotInput): ProjectilePrediction; fireProjectile(input: ProjectileShotInput): string; settleProjectile(shotId: string): SettleResult; advanceProjectiles(dt: number, time: number): SettleResult[]; activeP… — ⚠ undocumented · used by `createProjectileSystem`: Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
 - `ProjectileSystemDeps` (interface): interface ProjectileSystemDeps { effects: EffectSystem; spatial: CombatSpatialDeps; getStat(itemId: string, stat: string): number | null; raycast?: Raycast; sceneRaycast?: SceneRaycastApi; objects?: ProjectileObjectsDeps; entityCollidersOf?(instanceId: string): EntityCol… — ⚠ undocumented · used by `createProjectileSystem`: Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
@@ -721,6 +749,38 @@
 - `eyeHeightFromColliders` (function): function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number — Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown.
 - `resolveShot` (function): function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy: ShotOriginPolicy = { kind: "eye" }): ResolvedShot | null — Resolves a shot's world origin and direction from the shooter's eye or muzzle and an {@link Aim}, ready for `ctx.scene.raycast` — the aim half of a hitscan weapon.
 
+## @jgengine/core/combat/shotSpec
+
+- `DEFAULT_FALLOFF_END_SCALE` (const): const DEFAULT_FALLOFF_END_SCALE: 0.5 — Damage multiplier left at the end of falloff when a shot names no end scale.
+- `DEFAULT_SHOT_PENETRATION` (const): const DEFAULT_SHOT_PENETRATION: 0 — Most extra hits a shot may pass through when it names no penetration.
+- `DEFAULT_SHOT_RADIUS` (const): const DEFAULT_SHOT_RADIUS: 0.5 — Hit-sphere radius of a body that names none, m.
+- `DEFAULT_SHOT_RANGE` (const): const DEFAULT_SHOT_RANGE: 100 — Furthest a shot resolves when the delivery names no range, m.
+- `DEFAULT_SHOT_SPEED` (const): const DEFAULT_SHOT_SPEED: 15 — Launch speed of a body that names none, m/s.
+- `ResolvedShotSpec` (interface): interface ResolvedShotSpec — A spec with every default filled in. Read `mode` and the branch it names, never the raw spec.
+- `SHOT_GRAVITY` (const): const SHOT_GRAVITY: 9.8 — Standard gravity used to scale `ShotBody.gravity`, m/s².
+- `ShotArc` (interface): interface ShotArc extends ShotLaunch — Where a body lands and how long it took, in the same numbers the runtime simulates.
+- `ShotBody` (interface): interface ShotBody — A travelling body simulated over time. Every dimension is stated; nothing is read off another field, so a slow arrow with a splash and a fast bullet without one are the same shape.
+- `ShotContact` (interface): interface ShotContact — What a shot does on contact: damage, falloff, penetration, splash, ricochet, statuses.
+- `ShotDamage` (interface): interface ShotDamage — One damage channel a shot applies on contact.
+- `ShotDelivery` (type): type ShotDelivery = ShotTrace | ShotBody — How the shot reaches its target.
+- `ShotFalloff` (interface): interface ShotFalloff — Linear damage falloff between two distances.
+- `ShotHitOutcome` (interface): interface ShotHitOutcome — What one contact does: whether the shot still carries damage, at what scale, and whether it goes on.
+- `ShotLaunch` (interface): interface ShotLaunch — Straight-line flight of a body, for a caller that only needs where it starts and how fast.
+- `ShotPenetration` (interface): interface ShotPenetration — Extra targets a hit passes through.
+- `ShotRicochet` (interface): interface ShotRicochet — Bounces off the first surface contacted.
+- `ShotSpec` (interface): interface ShotSpec — A shot as plain data: how it travels and what it does on arrival. Every field but `delivery.kind` is optional with a documented default, so a plain gun is three lines.
+- `ShotSplash` (interface): interface ShotSplash — Area damage around the contact point.
+- `ShotStatReader` (type): type ShotStatReader = (stat: string) => number | null — Reads a numeric stat by name; the shape every item registry already exposes.
+- `ShotTrace` (interface): interface ShotTrace — An instant trace: the shot resolves on the tick it is fired and never travels.
+- `ShotVec3` (type): type ShotVec3 = readonly [number, number, number] — 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.
+- `resolveShotSpec` (function): function resolveShotSpec(spec: ShotSpec): ResolvedShotSpec — 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.
+- `shotArc` (function): function shotArc(shot: ResolvedShotSpec, origin: ShotVec3, direction: ShotVec3): ShotArc — 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.
+- `shotFalloffAt` (function): function shotFalloffAt(shot: ResolvedShotSpec, distance: number): number — Damage multiplier from falloff at `distance`; `1` with no falloff.
+- `shotFuseSeconds` (function): function shotFuseSeconds(shot: ResolvedShotSpec): number | null — Number of seconds the body flies before its fuse ends the flight, or `null` when it flies to contact.
+- `shotHitOutcome` (function): function shotHitOutcome(shot: ResolvedShotSpec, distance: number, hitIndex: number): ShotHitOutcome — 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.
+- `shotSpecFromStats` (function): function shotSpecFromStats(read: ShotStatReader): ShotSpec — Adapt the numeric stat keys older item data carries to a spec. This is the only place those keys are read, and delivery is decided by the keys that describe travel (`projectile.*`) alone: a splash radius or a damage number never turns a trace into a body.
+- `shotSpecFromWeapon` (function): function shotSpecFromWeapon(definition: { delivery: | { kind: "hitscan"; maxRange: number } | { kind: "projectile"; speed: number; gravity?: number; drag?: number; lifetime: number; maxRange?: number }; damage: { type: string; base: number; statuses?: readonly string[] }; falloff?: ShotFalloff; }): … — 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.
+
 ## @jgengine/core/combat/squadCombat
 
 - `SquadCombat` (interface): interface SquadCombat — Drive a squad: cover by threat, flanking, fire discipline, suppression and retreat.

package/skills/jgengine-combat/capabilities.md

@@ -263,6 +263,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `filterOutcomeFor` (function) · `import { filterOutcomeFor } from "@jgengine/core/combat"`
 - `resolveClaim` (function) · `import { resolveClaim } from "@jgengine/core/combat"`
 
+## shot-spec — resolve one shot description into explicit travel and contact behaviour
+
+- `resolveShotSpec` (function) · `import { resolveShotSpec } from "@jgengine/core/combat"`
+
 ## spawn-instance-restore — rehydrate a creature stat instance from decoded snapshot data
 
 - `restoreSpawnInstance` (function) · `import { restoreSpawnInstance } from "@jgengine/core/stats/spawnLevelStats"`

package/skills/jgengine-combat/reference.md

@@ -164,6 +164,7 @@ With `events: ctx.game.events` and `healthOf`, every hit and status tick raises
 - **Reload states.** `reload()` starts or continues; `interruptReload()` suspends through `Magazine.pauseReload` keeping progress; `resumeReload()` continues from it; `cancelReload()` discards. `ammo()` returns loaded / capacity / reserve / state / reload fraction / burst remaining / cadence fraction, and `stats()` carries shots, rounds spent, pulls, reloads, drops and damage dealt — the whole ammo economy is readable without touching internals.
 - **State.** `snapshot()` / `restore()` carry aim, handling, magazine, trigger, burst, pellets and counters as plain data; `retune(definition)` swaps rate, feel, damage and capacity without losing ammo or aim (a shrinking magazine discards rounds above the new capacity); a `devtoolsName` registers a one-line probe.
 - **When to use which.** `createWeaponRuntime` (`combat/weaponFire`) is the minimal plumbing for a game that already owns its fire loop and raycaster; `createWeaponSystem` is the definition-driven version with fire modes, ballistics, reload states and ammo accounting. Both leave models, audio, muzzle flash, camera and input to the game; feel numbers come from `measureWeapon` and presentation from `weaponPresentation`.
+- **Anything that is not a gun** is a `ShotSpec` (`combat/shotSpec`): `delivery` is `{ kind: "trace", range? }` or `{ kind: "body", speed?, gravity?, drag?, lifetime?, radius?, fuse?: number | "impact", homing?, range? }`, and `contact` carries `damage`, `falloff`, `penetration { count, keepDamage? }`, `splash { radius, falloff?, damageScale? }`, `ricochet { count, angleDeg?, damageScale? }`. Every field but `delivery.kind` has a documented default, so a rifle is `{ delivery: { kind: "trace" }, contact: { damage: { type: "kinetic", base: 24 }, falloff: { start: 25, end: 75, endScale: 0.4 } } }` and a grenade is a body with `fuse: 2` and `splash`. `resolveShotSpec` fills the defaults once, `shotArc` solves the path, and `shotFalloffAt` / `shotHitOutcome` answer damage per distance and per penetrated target. `ProjectileShotInput.spec` takes one directly; `shotSpecFromStats` adapts older numeric item keys in one place and never reads a splash or damage field to decide delivery.
 - **Evidence** (`combat/weaponSystem.test.ts`): the test fixture at 600 rpm with a 30-round magazine empties in 2.9 s, climbs 17.0° pitch and 3.1° yaw over the magazine, is back to half climb in 0.37 s and within 5% in 0.6 s; bloom runs 2.0 → 8.0 → 12.0 mrad (cap) by the tenth shot and settles to base 0.63 s after the last shot. A hitscan and a projectile contact at the same distance produce the same 20 damage (30 on a 1.5x head zone), and one second of held fire cannot exceed four shots.
 
 ## Encounter sequencing

package/skills/jgengine-gameplay/api.md

@@ -922,6 +922,8 @@
 - `ModelMaterialOverride` (interface): interface ModelMaterialOverride extends MaterialSurfaceParameters — Per-entity PBR material override (#151.3) applied to every standard or physical material in the model's cloned scene graph.
 - `ModelPart` (interface): interface ModelPart — Static child model stacked at a fixed local offset under its parent's transform — no bone/rig resolution, unlike `ModelAttachment`. Assembles a compound entity (e.g. a modular castle wall + tower + roof) from several single-mesh kit pieces.
 - `ModelRimLight` (interface): interface ModelRimLight — Fresnel rim-light term added on top of a model's lighting — see {@link ModelMaterialOverride.rim}.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
 - `ModelWindConfig` (interface): interface ModelWindConfig — Wind sway for a foliage model; see {@link ModelConfig.wind}.
 - `MovementCommitFrame` (interface): interface MovementCommitFrame — One frame's movement resolution handed to `PlayerMovementConfig.beforeCommit`.
 - `MovementFeelConfig` (interface): interface MovementFeelConfig — Feel knobs for the built-in walk controller; see {@link PlayerMovementConfig.feel}.
@@ -2685,13 +2687,33 @@
 ## @jgengine/core/run/runLoop
 
 - `RunChange` (interface): interface RunChange<T> — One change the next run can open with. `T` is the game's own payload (a tighter rival line, an unlocked part, a route modifier) - the loop only draws and remembers which id was drawn.
+- `RunChoice` (interface): interface RunChoice<T> — One change a run could open with, in the shape a choice screen shows: the id and its payload.
 - `RunLoop` (interface): interface RunLoop<T> — A run's lifecycle: what it carries and can lose, and the change it hands the next run.
 - `RunLoopConfig` (interface): interface RunLoopConfig<T> — Configuration for {@link createRunLoop}.
 - `RunLoopState` (interface): interface RunLoopState — Everything a run loop stores as plain JSON: the run in progress plus lifetime totals.
 - `RunOffer` (interface): interface RunOffer<T> — The change a run opens with, and which run it is.
 - `RunOutcome` (type): type RunOutcome = "banked" | "lost" — How a run ended: what it carried reached the bank, or it was lost.
+- `RunProbe` (interface): interface RunProbe — Read-only handle a capture or devtools uses to prove a run loop is live, not merely imported.
+- `RunReadout` (interface): interface RunReadout — What the loop reports about the run it is playing, for a capture or devtools read.
 - `RunSettlement` (interface): interface RunSettlement<T> — What one closed run banked or lost, and what the next run changes.
 - `createRunLoop` (function): function createRunLoop<T>(config: RunLoopConfig<T>): RunLoop<T> — Bank-or-lose between runs, with one deterministic change per run drawn from an authored table.
+- `installRunProbe` (function): function installRunProbe<T>(loop: RunLoop<T>): () => void — 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.
+
+## @jgengine/core/run/sessionLoop
+
+- `SessionChoice` (interface): interface SessionChoice<T> — One option the next session could open with, in the shape a choice screen shows.
+- `SessionLoop` (interface): interface SessionLoop<T = never, I = void, R = void> — One session's lifecycle: open it, carry a quantity, close it at its boundary, and optionally open the next one with an option the game authored.
+- `SessionLoopConfig` (interface): interface SessionLoopConfig<T = never, I = void, R = void> — Configuration for {@link createSessionLoop}.
+- `SessionLoopState` (interface): interface SessionLoopState — Everything a session loop stores as plain JSON.
+- `SessionOffer` (interface): interface SessionOffer<T> — The option a session opens with, and which session it is.
+- `SessionOfferOption` (interface): interface SessionOfferOption<T> — One option the next session may open with. `T` is the game's own payload (a tighter rival line, an unlocked part, a shorter route) - the loop only draws and remembers which id was drawn.
+- `SessionPhase` (type): type SessionPhase = "idle" | "open" | "closed" — Where a session stands: not opened yet, in progress, or closed at its boundary.
+- `SessionProbe` (interface): interface SessionProbe — Read-only handle a capture or devtools uses to prove a session loop is live, not merely imported.
+- `SessionReadout` (interface): interface SessionReadout — What the loop reports about the session it is playing, for a capture or devtools read.
+- `SessionSettlement` (interface): interface SessionSettlement<R = void, T = never> — What closing one session did, and what the next session opens with.
+- `SettlingSession` (interface): interface SettlingSession<I = void> — The session closing, handed to a game's own `settle`.
+- `createSessionLoop` (function): function createSessionLoop<T = never, I = void, R = void>(config: SessionLoopConfig<T, I, R> = {}): SessionLoop<T, I, R> — The shared shape of a game session, with the game's own rules supplied as config: a session opens, it may carry a quantity, its boundary closes it, and the game's `settle` callback decides what happens to what it carried. A park day, a night shift and a wave are the same base with a different `settle`, a different `kind` and, where nothing is at stake, `carries: false`.
+- `installSessionProbe` (function): function installSessionProbe<T, I, R>(loop: SessionLoop<T, I, R>): () => void — Publish the loop's own readout on `window.__jgengineRun`, so a capture or devtools probe can state which session is live, its phase, what it carries and the option it offers. Reads only; it never starts, closes or changes a session. Returns the uninstaller.
 
 ## @jgengine/core/session/contestedChannel
 

package/skills/jgengine-gameplay/capabilities.md

@@ -649,9 +649,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `rerollRules` (function) · `import { rerollRules } from "@jgengine/core/gameplay"`
 - `selectRules` (function) · `import { selectRules } from "@jgengine/core/gameplay"`
 
-## run-loop — bank or lose what a run carries, with one deterministic change per run
+## run-loop — deprecated roguelike composition of session-loop - bank or lose what a run carries, with one deterministic change per run
 
 - `createRunLoop` (function) · `import { createRunLoop } from "@jgengine/core/run/runLoop"`
+- `installRunProbe` (function) · `import { installRunProbe } from "@jgengine/core/run/runLoop"`
 
 ## run-modifiers — a roguelike run built from stacking drafted modifier picks
 
@@ -677,6 +678,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `seededRng` (function) · `import { seededRng } from "@jgengine/core/gameplay"`
 
+## session-loop — open and close a game session, settle the quantity it carried and optionally draw the next session's authored option
+
+- `createSessionLoop` (function) · `import { createSessionLoop } from "@jgengine/core/run/sessionLoop"`
+- `installSessionProbe` (function) · `import { installSessionProbe } from "@jgengine/core/run/sessionLoop"`
+
 ## set — a bounded keyed value in a caller-owned serializable record
 
 - `setValue` (function) · `import { setValue } from "@jgengine/core/gameplay"`