@jgengine/core 0.26.0 → 0.27.0

package/dist/loot/lootWeapon.d.ts

@@ -0,0 +1,35 @@
+import { type WeaponDefinition } from "../combat/weaponDefinition.js";
+import type { LootItem } from "./lootGen.js";
+/**
+ * Which rolled stat feeds which part of a {@link WeaponDefinition}. Every field is a stat id from the
+ * item; an omitted field keeps the template's value, so a catalog only maps what it rolls.
+ */
+export interface LootWeaponStatMap {
+    roundsPerMinute?: string;
+    damage?: string;
+    pellets?: string;
+    /** Requires the template to declare a magazine. */
+    magazineCapacity?: string;
+    reloadMs?: string;
+    /** Spread half-angle in radians, clamped to `0..PI/2`. */
+    spreadBase?: string;
+    /** Hitscan range, or a projectile's hard distance cap. */
+    maxRange?: string;
+    /** Projectile launch speed. */
+    projectileSpeed?: string;
+}
+/** A base weapon definition plus the stat map a rolled item overrides. */
+export interface LootWeaponProjection {
+    template: WeaponDefinition;
+    stats: LootWeaponStatMap;
+    /** Definition id override; defaults to `loot.<baseId>.<rarity>`. */
+    id?: string;
+}
+/**
+ * Project a rolled item onto a plain weapon definition: copy the template, then write the mapped
+ * stats into rate, damage, magazine, spread, range and projectile speed. The result is a
+ * {@link WeaponDefinition}, so `assertWeaponDefinition` and `createWeaponSystem` accept it unchanged.
+ *
+ * @capability loot-weapon feed a rolled item into a weapon definition so generated gear fires through the weapon system
+ */
+export declare function lootWeaponDefinition(item: LootItem, projection: LootWeaponProjection): WeaponDefinition;

package/dist/loot/lootWeapon.js

@@ -0,0 +1,70 @@
+import { MAX_WEAPON_PELLETS_PER_SHOT, } from "../combat/weaponDefinition.js";
+function statOf(item, statId) {
+    if (statId === undefined)
+        return undefined;
+    const value = item.stats[statId];
+    if (value === undefined)
+        throw new RangeError(`Loot weapon projection names stat "${statId}" but the item does not roll it`);
+    if (!Number.isFinite(value))
+        throw new RangeError(`Loot weapon projection stat "${statId}" is ${String(value)}`);
+    return value;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Project a rolled item onto a plain weapon definition: copy the template, then write the mapped
+ * stats into rate, damage, magazine, spread, range and projectile speed. The result is a
+ * {@link WeaponDefinition}, so `assertWeaponDefinition` and `createWeaponSystem` accept it unchanged.
+ *
+ * @capability loot-weapon feed a rolled item into a weapon definition so generated gear fires through the weapon system
+ */
+export function lootWeaponDefinition(item, projection) {
+    const template = projection.template;
+    const map = projection.stats;
+    const definition = {
+        ...template,
+        id: projection.id ?? `loot.${item.baseId}.${item.rarity}`,
+        delivery: { ...template.delivery },
+        handling: { ...template.handling, spread: { ...template.handling.spread } },
+        damage: { ...template.damage },
+        ...(template.magazine === undefined ? {} : { magazine: { ...template.magazine } }),
+        ...(template.burst === undefined ? {} : { burst: { ...template.burst } }),
+        ...(template.falloff === undefined ? {} : { falloff: { ...template.falloff } }),
+    };
+    const rate = statOf(item, map.roundsPerMinute);
+    if (rate !== undefined)
+        definition.roundsPerMinute = Math.max(Number.MIN_VALUE, rate);
+    const damage = statOf(item, map.damage);
+    if (damage !== undefined)
+        definition.damage.base = Math.max(Number.MIN_VALUE, damage);
+    const pellets = statOf(item, map.pellets);
+    if (pellets !== undefined) {
+        definition.pellets = clamp(Math.round(pellets), 1, MAX_WEAPON_PELLETS_PER_SHOT);
+    }
+    const capacity = statOf(item, map.magazineCapacity);
+    const reloadMs = statOf(item, map.reloadMs);
+    if (capacity !== undefined || reloadMs !== undefined) {
+        if (definition.magazine === undefined) {
+            throw new RangeError('Loot weapon projection maps magazineCapacity or reloadMs but the template has no magazine');
+        }
+        if (capacity !== undefined)
+            definition.magazine.capacity = Math.max(1, Math.round(capacity));
+        if (reloadMs !== undefined)
+            definition.magazine.reloadMs = Math.max(0, reloadMs);
+    }
+    const spread = statOf(item, map.spreadBase);
+    if (spread !== undefined)
+        definition.handling.spread.base = clamp(spread, 0, Math.PI / 2);
+    const range = statOf(item, map.maxRange);
+    if (range !== undefined)
+        definition.delivery.maxRange = Math.max(Number.MIN_VALUE, range);
+    const speed = statOf(item, map.projectileSpeed);
+    if (speed !== undefined) {
+        if (definition.delivery.kind !== "projectile") {
+            throw new RangeError('Loot weapon projection maps projectileSpeed but the template is hitscan');
+        }
+        definition.delivery.speed = Math.max(Number.MIN_VALUE, speed);
+    }
+    return definition;
+}

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.26.0";
+export declare const VERSION = "0.27.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,43 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.26.0";
+export const VERSION = "0.27.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.27.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.27.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.24.0`; `@jgengine/github` is `0.14.0`.",
+        ],
+        added: [
+            "`rollLoot` (`@jgengine/core/loot/lootGen`) rolls a named item from a caller `LootCatalog`: bases with mount slots, parts, affix pools, weighted rarity tiers, manufacturer personalities and a `levelScale` curve. Stats are `base × rarity.statScale × levelScale`, then part stats/multipliers, maker `bias`/`scale`, then additive and multiplicative affixes; additive affix rolls scale with level, multiplicative ones do not.",
+            "`createLootRoller` wraps a validated catalog with roll counts per rarity, `snapshot()`/`restore()`/`reset()` and an optional devtools probe; `assertLootCatalog` rejects duplicate ids, unresolvable pools, empty item slots and a non-ascending level curve at construction.",
+            "`validateLootItem` returns coded issues (`unknown-base`, `manufacturer-base`, `missing-slot-part`, `part-category`, `unknown-affix`, `empty-name`, …) and `compareLootItems` returns sorted per-stat deltas plus a weighted score with caller-named `lowerIsBetter` stats.",
+            "`lootWeaponDefinition` (`@jgengine/core/loot/lootWeapon`) projects a rolled item onto a `WeaponDefinition` through a caller stat map, so a generated gun runs in `createWeaponSystem` after `assertWeaponDefinition`.",
+            "`defineXpCurve` (`@jgengine/core/gameplay`) resolves one authored growth rule (`flat`, `linear`, `power`, `geometric`, `table`) plus a `maxLevel` cap into per-level thresholds, lifetime totals, a plain-words rule string and a `leveling` track.",
+            "`createSkillTree` spends and refunds points over authored nodes with `cost`, `requires`, `excludes`, passives, actives and multi-node `synergies`; `resolved()` returns the stat modifiers and actions, and state snapshots/restores as `{ points, ranks }`.",
+            "`gearScore` / `compareGearSets` score a whole loadout from stat weights, level, rarity and slot coverage.",
+            "`lootStatContributions` and `scoreLootStats` expose the weight policy `compareLootItems` already used.",
+            "`createEquipment` (`@jgengine/core/inventory/equipment`) wears gear by slot: slot defs declare accepted kinds and the slots they block, item defs declare the slots an item may occupy, a filled slot swaps and hands back the replaced item, and a two-handed item and the slot it blocks cannot both be filled. `state()` / `restore()` round-trip the worn set; a devtools probe reports filled slots.",
+            "`characterLoad` and `canCarry` (`@jgengine/core/inventory/carryLoad`) weigh carried inventories plus worn gear against a capacity and hand back the shared encumbrance bands (tier, `moveMultiplier`, sprint/jump gates, `remaining`), so a stash left out of `carried` adds no weight.",
+            "`fitShapedItem` (`@jgengine/core/inventory/shapedGrid`) places a shaped item at its first fit or names why not: `too-large` (with both sizes), `no-space`, `budget-exceeded`.",
+            "`InventorySet.snapshot()` / `restore()` / `reset()` (`@jgengine/core/inventory/inventoryModel`) save and reload every declared inventory as detached plain data, so a bag and a stash never share live slots.",
+            "`splitStack` takes an optional stack `limit`, rejecting `over-stack` instead of merging past the max stack.",
+            "`createLaneGraph` and `laneGraphFromDocument` (`@jgengine/core/world`) read an authored lane graph out of the scene document: `traffic_lane` paths are one directed span each, `road` paths (the street bake) become a lane per direction split where streets cross, `traffic_intersection` markers carry signal phases and right-of-way in `meta`, and `traffic_parking` markers place kerbside spots.",
+            "`createTraffic` (`@jgengine/core/world`) runs cars on that graph: IDM car following and braking, one car at a time through each intersection box behind a signal phase or first-come right-of-way, lane changes across authored neighbours, parking that reserves a spot, deterministic injected variety, `snapshot`/`restore`, and a devtools probe.",
+            "`Traffic.setDemand(count)` is the fleet target; the time-of-day curve stays the caller's policy.",
+            "`applyVehicleParts` (`@jgengine/core/world`) composes data-driven tuning parts onto a `KinematicVehicleTuning` — stat multipliers/addends applied in install order plus an optional tire grip curve — and returns the composed tuning, the installed ids, and a `VehicleFeel` (top speed, drive, brakes, turn rate, handbrake grip, and the grip curve's peak/slide). `withPart` swaps a part within its slot and `feelOf` reads the numbers out of any tuning.",
+            "`createVehicleDamage` (`@jgengine/core/world`) is fixed-zone crash damage wired to handling and visuals: impacts accumulate into discrete stages, each stage costs grip/drive/brakes/top speed/drag and pulls the steering (`effect`), and each zone shows one bounded dent (`deformation`) that never exceeds its authored `deform`. Parts can detach at a set stage, a total impulse can disable the vehicle, and `snapshot`/`restore` resume mid-crash. `damagedTuning` and `damagedAxis` fold the effect into a tuning or an input, and `modifiers()` carries it as per-tick overrides.",
+            "`KinematicVehicleTuning.weightTransfer` (`@jgengine/core/world`) adds load-transfer grip: longitudinal transfer under braking/traction and lateral transfer under cornering cut the tire grip curve (tire load sensitivity), so braking into a corner holds less slide than coasting through it. Each tick reports `weightTransfer` and `loadGrip`; omitting the block keeps the previous flat-grip model exactly.",
+            "`KinematicVehicleModifiers.gripScale` scales the grip curve for one tick, mirroring `VehicleDynamicsModifiers.gripScale` so a damage layer drives either sim.",
+            "`decal` scene kind (`@jgengine/core/world/decalKind`) and its renderer (`@jgengine/shell/scene/DecalRenderer`): dirt, cracks, paint and blood decals authored as placed markers, draped on the live terrain or standing on an authored tilt, with a deterministic procedural texture per style+seed.",
+            "`TerrainMaterialLayer.material` (`@jgengine/core/world/terraform`): a material library name whose scanned color map paints that terrain layer. The runtime samples up to four layer maps at each layer's `tiling` and blends them through the authored mask weights (`createTerrainDetailMaterial`'s `layerMaps`), so painted terrain blends between authored layers instead of tiling one flat map.",
+            "`grass_field` volumes now paint a ground-cover mat under their blades (`groundCover` rule, `@jgengine/shell/terrain/GrassCover`), so an authored patch reads as turf rather than bare ground with stubble. `GrassEnvironmentConfig.groundCover` does the same for `grass()` patches.",
+            "`ModelConfig.wind` (`@jgengine/core/game/playableGame`) and `applyModelWind` (`@jgengine/shell/render/modelWind`): per-model foliage sway with height-ramped travel, shared gust clock and per-model strength/speed/direction.",
+        ],
+        changed: [
+            "The player shell re-renders only for the ctx slices it reads — the possessed entity and the touch control mode — instead of on every `ctx` write. Subscribing the shell root to the raw ctx version reconciled the canvas, the whole actor tree and the HUD on each per-frame entity pose write, which is what `subscribeMembership` and the markers' imperative `useFrame` pose reads exist to avoid (#625). Scrap Signal: 86.6 ms → 16.7 ms per frame at the same 621 draws; Harbor Heat: 102.8 ms → 46.2 ms at the same ~7.2k draws.",
+            "The `ocean()` environment feature passes the live ground to its shader, so the sea shades shallow→deep and its shoreline foam band lands where the bed meets the surface.",
+        ],
+        removed: [],
+    },
     "0.26.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.26.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.23.0`; `@jgengine/github` is `0.13.0`.",

package/dist/nav/laneGraph.d.ts

@@ -0,0 +1,178 @@
+import type { EditorDocument } from "../editor/types.js";
+import type { Waypoint } from "./pathFollow.js";
+/** A junction where lane spans meet. */
+export interface LaneNode {
+    id: string;
+    at: Waypoint;
+}
+/** One directed lane span to resolve into the graph. */
+export interface LaneEdgeConfig {
+    id: string;
+    /** World-space centerline, in travel order. */
+    points: readonly Waypoint[];
+    /** Junction ids; omitted endpoints are joined geometrically by {@link LaneGraphConfig.joinRadius}. */
+    from?: string;
+    to?: string;
+    /** Speed limit in world units per second. */
+    speed?: number;
+    width?: number;
+    /** Ids of the parallel lanes on either side, used for lane changes. */
+    left?: string;
+    right?: string;
+    /** Arc positions, in metres, of parking spots on this lane. */
+    parking?: readonly number[];
+    /** Allowed as a traffic spawn point. */
+    entry?: boolean;
+    /** Allowed as a traffic removal point. */
+    exit?: boolean;
+}
+/** Signal timing for one intersection; phases list the in-lanes each green window serves. */
+export interface LaneSignalProgram {
+    greenSeconds: number;
+    yellowSeconds: number;
+    /** Red-for-all interval between phases. Default 0. */
+    allRedSeconds?: number;
+    /**
+     * In-lane ids served by each green phase, in cycle order. Omitted lets the traffic runtime derive
+     * them: one green per line of travel, so opposite approaches share a window.
+     */
+    phases?: readonly (readonly string[])[];
+}
+/** How an intersection resolves which approach may enter next. */
+export type LaneRightOfWay = "signal" | "priority";
+/** Right-of-way and signal timing for one authored crossing. */
+export interface LaneIntersectionConfig {
+    node: string;
+    /** Default `"priority"` (first come, first served) unless a signal program is given. */
+    kind?: LaneRightOfWay;
+    signal?: LaneSignalProgram;
+    /** Metres before the lane end where a car holds at the stop line. Default 6. */
+    stopLine?: number;
+    /** Seconds the signal cycle is shifted, to unsynchronize a street of intersections. Default 0. */
+    offsetSeconds?: number;
+}
+/** A resolved lane span: centerline, arc lengths, limit and adjacency. */
+export interface LaneSpan {
+    id: string;
+    from: string;
+    to: string;
+    points: readonly Waypoint[];
+    /** Per-segment lengths; one fewer than `points`. */
+    segmentLengths: readonly number[];
+    length: number;
+    speed: number;
+    width: number;
+    left: string | null;
+    right: string | null;
+    parking: readonly number[];
+    entry: boolean;
+    exit: boolean;
+}
+/** A resolved crossing: the lanes that feed it, the lanes that leave it, and its right-of-way. */
+export interface LaneIntersection {
+    node: string;
+    at: Waypoint;
+    kind: LaneRightOfWay;
+    inLanes: readonly string[];
+    outLanes: readonly string[];
+    stopLine: number;
+    signal: LaneSignalProgram | null;
+    offsetSeconds: number;
+}
+/** A parking spot projected onto one lane at an arc position. */
+export interface LaneSpot {
+    id: string;
+    lane: string;
+    /** Arc, in metres, along the lane where a car stands parked. */
+    arc: number;
+}
+/** World pose of a lane at an arc position. */
+export interface LanePose {
+    laneId: string;
+    arc: number;
+    position: Waypoint;
+    /** Yaw of travel, matching engine `rotationY`. */
+    heading: number;
+}
+/** The authored lane graph: junctions, directed spans, crossings and parking spots. */
+export interface LaneGraphConfig {
+    /** Junction positions; lanes may name them in `from`/`to` instead of joining by geometry. */
+    nodes?: readonly LaneNode[];
+    lanes: readonly LaneEdgeConfig[];
+    intersections?: readonly LaneIntersectionConfig[];
+    spots?: readonly LaneSpot[];
+    /** Distance within which two lane endpoints are the same junction. Default 3. */
+    joinRadius?: number;
+}
+/**
+ * Authored lane topology: junctions, directed spans with speed limits and arc lengths, crossings with
+ * their right-of-way, and parking spots. Positions come from the spans themselves, so a traffic
+ * runtime never re-derives geometry or runs a path search per vehicle.
+ */
+export interface LaneGraph {
+    node(id: string): LaneNode | null;
+    lane(id: string): LaneSpan | null;
+    laneIds(): readonly string[];
+    nodeIds(): readonly string[];
+    outLanes(nodeId: string): readonly string[];
+    inLanes(nodeId: string): readonly string[];
+    intersection(nodeId: string): LaneIntersection | null;
+    intersections(): readonly LaneIntersection[];
+    spots(): readonly LaneSpot[];
+    spot(id: string): LaneSpot | null;
+    /** Lanes a car may spawn on: an authored entry, or a lane whose start has no inbound traffic. */
+    entries(): readonly string[];
+    /** Lanes that leave the graph: an authored exit, or a lane that ends where nothing continues. */
+    exits(): readonly string[];
+    /** World pose at `arc` metres, shifted `lateral` metres to the driver's left. */
+    pose(laneId: string, arc: number, lateral?: number): LanePose | null;
+    /** Arc on `laneId` nearest a world XZ point, clamped to the span. */
+    project(laneId: string, x: number, z: number): number;
+    /** Travel heading at `arc` along a lane, in radians. */
+    heading(laneId: string, arc: number): number;
+}
+/**
+ * Write the world pose at `arc` along a lane into a caller-owned record — the allocation-free form
+ * {@link LaneGraph.pose} wraps, for a runtime that poses hundreds of cars per tick.
+ * @internal
+ */
+export declare function lanePoseInto(lane: LaneSpan, arc: number, lateral: number, out: {
+    x: number;
+    y: number;
+    z: number;
+    heading: number;
+}): void;
+/**
+ * Read handle over the graph resolved once at construction. The build mutates its working set; this
+ * object never changes, so a save system rebuilds it from the scene document instead of serializing it.
+ *
+ * @capability lane-graph directed lane topology with junctions, signals and parking for vehicle traffic
+ */
+export declare function createLaneGraph(config: LaneGraphConfig): LaneGraph;
+/** How the document reader recognizes authored lane content. */
+export interface LaneGraphDocumentOptions {
+    /** Path kinds authored as one directed lane each. Default `["traffic_lane"]`. */
+    laneKinds?: readonly string[];
+    /** Path kinds authored as a two-way road centerline, expanded into a lane per direction. Default `["road"]`. */
+    roadKinds?: readonly string[];
+    /** Marker kinds that carry an intersection's right-of-way in `meta`. Default `["traffic_intersection"]`. */
+    intersectionKinds?: readonly string[];
+    /** Marker kinds that place a parking spot. Default `["traffic_parking"]`. */
+    parkingKinds?: readonly string[];
+    /** Distance within which lane endpoints and markers join a junction. Default 3. */
+    joinRadius?: number;
+    /** Speed limit, in world units per second, by authored `meta.level`. */
+    speedByLevel?: Readonly<Record<string, number>>;
+    /** Speed limit for a path with no recognized level. Default 13. */
+    defaultSpeed?: number;
+}
+/**
+ * Read a lane graph out of an authored scene document. `traffic_lane` paths are one directed lane each;
+ * `road` paths (the editor's street bake) become a lane per direction, offset onto their own side of
+ * the road; `traffic_intersection` markers carry a signal program and right-of-way in `meta`;
+ * `traffic_parking` markers place parking spots. Runtime positions come from the paths, so editing a
+ * road moves its traffic instead of leaving a duplicate lane behind.
+ *
+ * @capability lane-graph-from-scene read an authored lane graph, signals and parking out of the scene document
+ */
+export declare function laneGraphFromDocument(doc: Pick<EditorDocument, "paths" | "markers">, options?: LaneGraphDocumentOptions): LaneGraph;