@jgengine/core 0.36.0 → 0.37.0

package/dist/physics/physicsWorld.js

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

package/dist/run/runLoop.d.ts

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

package/dist/run/runLoop.js

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

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.37.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.37.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.37.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.