@jgengine/core 0.26.0 → 0.27.0

package/dist/world/decalKind.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `decal` marker: a surface-grime decal authored as a placed marker (dirt, cracks, paint, blood).
+ * Its position, facing (`rotationY`), tilt (0 lies on the ground, 90 stands on a wall), size, opacity
+ * and seed live in the scene document, so decals are placed in the editor like any other authored
+ * content and a game never hardcodes a stain. Pure config here; the procedural texture and the
+ * draped/standing quad live in the `shell` renderer.
+ *
+ * @capability decal editor-authored surface decal
+ */
+import { type ParamSchema, type SceneKindObject } from "../scene/sceneKinds.js";
+/** The editor marker kind marking a surface decal. */
+export declare const DECAL_KIND = "decal";
+/** The four authored decal looks; each has its own deterministic procedural texture. */
+export declare const DECAL_STYLES: readonly ["dirt", "cracks", "paint", "blood"];
+/** One of the four authored decal looks. */
+export type DecalStyle = (typeof DECAL_STYLES)[number];
+/** Fully-defaulted decal params parsed from a marker's `meta`. */
+export interface DecalRules {
+    style: DecalStyle;
+    /** Decal width/height in metres. */
+    size: number;
+    /** 0 lies flat on the ground, 90 stands on a wall; 45 leans. */
+    tilt: number;
+    /** Vertical offset of the decal centre above the placed point, in metres. */
+    lift: number;
+    /** Push along the decal's own normal, so a wall decal clears the wall it sits on. */
+    offset: number;
+    /** 0..1 overall alpha. */
+    opacity: number;
+    /** Deterministic shape seed. */
+    seed: string;
+}
+/** Default decal rules: a small dirt smudge lying on the ground. */
+export declare const DECAL_DEFAULTS: DecalRules;
+/** The decal parameter schema — drives the inspector and the `meta` parse. */
+export declare const DECAL_SCHEMA: ParamSchema;
+/** Parse a marker's `meta` into fully-defaulted decal rules. @internal */
+export declare function readDecalRules(meta: Record<string, unknown> | undefined): DecalRules;
+/** A resolved decal: its placed point/facing plus fully-defaulted rules. */
+export interface ResolvedDecal {
+    position: readonly [number, number, number];
+    rotationY: number;
+    rules: DecalRules;
+}
+/** Resolve a decal marker into a placed, fully-defaulted decal; null without a position. @internal */
+export declare function resolveDecalObject(object: SceneKindObject): ResolvedDecal | null;
+/** Registers the `decal` scene kind. Called by {@link registerBuiltinSceneKinds}. @internal */
+export declare function registerDecalKind(): void;

package/dist/world/decalKind.js

@@ -0,0 +1,86 @@
+/**
+ * `decal` marker: a surface-grime decal authored as a placed marker (dirt, cracks, paint, blood).
+ * Its position, facing (`rotationY`), tilt (0 lies on the ground, 90 stands on a wall), size, opacity
+ * and seed live in the scene document, so decals are placed in the editor like any other authored
+ * content and a game never hardcodes a stain. Pure config here; the procedural texture and the
+ * draped/standing quad live in the `shell` renderer.
+ *
+ * @capability decal editor-authored surface decal
+ */
+import { registerSceneKind } from "../scene/sceneKinds.js";
+/** The editor marker kind marking a surface decal. */
+export const DECAL_KIND = "decal";
+/** The four authored decal looks; each has its own deterministic procedural texture. */
+export const DECAL_STYLES = ["dirt", "cracks", "paint", "blood"];
+/** Default decal rules: a small dirt smudge lying on the ground. */
+export const DECAL_DEFAULTS = {
+    style: "dirt",
+    size: 2.4,
+    tilt: 0,
+    lift: 0.02,
+    offset: 0.04,
+    opacity: 0.9,
+    seed: "",
+};
+/** The decal parameter schema — drives the inspector and the `meta` parse. */
+export const DECAL_SCHEMA = {
+    fields: [
+        { type: "select", key: "style", label: "style", options: DECAL_STYLES.map((value) => ({ value })), default: DECAL_DEFAULTS.style },
+        { type: "range", key: "size", label: "size", min: 0.3, max: 24, step: 0.1, default: DECAL_DEFAULTS.size, unit: "m" },
+        { type: "range", key: "tilt", label: "tilt", min: 0, max: 90, step: 1, default: DECAL_DEFAULTS.tilt, unit: "°" },
+        { type: "range", key: "lift", label: "height", min: 0, max: 30, step: 0.05, default: DECAL_DEFAULTS.lift, unit: "m" },
+        { type: "range", key: "offset", label: "surface offset", min: 0, max: 2, step: 0.01, default: DECAL_DEFAULTS.offset, unit: "m" },
+        { type: "range", key: "opacity", label: "opacity", min: 0.05, max: 1, step: 0.01, default: DECAL_DEFAULTS.opacity },
+        { type: "seed", key: "seed", label: "seed", default: DECAL_DEFAULTS.seed },
+    ],
+};
+function number(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function text(meta, key, fallback) {
+    const value = meta?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+/** Parse a marker's `meta` into fully-defaulted decal rules. @internal */
+export function readDecalRules(meta) {
+    const style = text(meta, "style", DECAL_DEFAULTS.style);
+    return {
+        style: DECAL_STYLES.includes(style) ? style : DECAL_DEFAULTS.style,
+        size: Math.min(24, Math.max(0.3, number(meta, "size", DECAL_DEFAULTS.size))),
+        tilt: Math.min(90, Math.max(0, number(meta, "tilt", DECAL_DEFAULTS.tilt))),
+        lift: Math.max(0, number(meta, "lift", DECAL_DEFAULTS.lift)),
+        offset: Math.max(0, number(meta, "offset", DECAL_DEFAULTS.offset)),
+        opacity: Math.min(1, Math.max(0.05, number(meta, "opacity", DECAL_DEFAULTS.opacity))),
+        seed: text(meta, "seed", DECAL_DEFAULTS.seed),
+    };
+}
+/** Resolve a decal marker into a placed, fully-defaulted decal; null without a position. @internal */
+export function resolveDecalObject(object) {
+    const position = object.position ?? object.center;
+    if (position === undefined)
+        return null;
+    return {
+        position: [position.x, position.y, position.z],
+        rotationY: object.rotationY ?? 0,
+        rules: readDecalRules(object.meta),
+    };
+}
+/** Registers the `decal` scene kind. Called by {@link registerBuiltinSceneKinds}. @internal */
+export function registerDecalKind() {
+    registerSceneKind({
+        kind: DECAL_KIND,
+        target: "marker",
+        label: "Decal",
+        addCategory: "Studios",
+        accent: "#b5793c",
+        schema: DECAL_SCHEMA,
+        resolve: (object) => resolveDecalObject(object),
+        note: (object) => {
+            const resolved = resolveDecalObject(object);
+            if (resolved === null)
+                return "Place the marker on a surface.";
+            return `${resolved.rules.style} · ${resolved.rules.size.toFixed(1)} m ${resolved.rules.tilt >= 45 ? "wall" : "ground"} decal`;
+        },
+    });
+}

package/dist/world/features.d.ts

@@ -288,6 +288,8 @@ export interface GrassEnvironmentConfig {
     colorVariation?: number;
     /** 0..1 blend of blade normals toward straight-up (shell default 0.6). Low values light each blade plane individually and go dark when side-lit; high values light the field like a soft carpet. */
     normalLift?: number;
+    /** 0..1 strength of the turf ground-cover mat painted under the blades (shell default 0.9); 0 leaves the ground bare. */
+    groundCover?: number;
 }
 export interface OceanEnvironmentConfig {
     bounds?: WorldBounds;
@@ -459,7 +461,7 @@ export type SnowEnvironmentDescriptor = {
 } & Required<Pick<SnowEnvironmentConfig, "area" | "density" | "speed" | "flakeSize" | "drift" | "wind" | "color" | "opacity">>;
 export type GrassEnvironmentDescriptor = {
     kind: "grass";
-} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift">;
+} & Required<Pick<GrassEnvironmentConfig, "area" | "density" | "bladeHeight" | "bladeWidth" | "windStrength" | "colors">> & Pick<GrassEnvironmentConfig, "seed" | "bladeBend" | "tuftRadius" | "colorVariation" | "normalLift" | "groundCover">;
 export type OceanEnvironmentDescriptor = {
     kind: "ocean";
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;

package/dist/world/features.js

@@ -201,6 +201,7 @@ export function grass(config = {}) {
         ...(config.tuftRadius === undefined ? {} : { tuftRadius: config.tuftRadius }),
         ...(config.colorVariation === undefined ? {} : { colorVariation: config.colorVariation }),
         ...(config.normalLift === undefined ? {} : { normalLift: config.normalLift }),
+        ...(config.groundCover === undefined ? {} : { groundCover: config.groundCover }),
     };
 }
 /** Declares an ocean water body for `environment()` — bounds, level, and wave tuning. */

package/dist/world/grassKind.d.ts

@@ -40,6 +40,11 @@ export interface GrassRules {
     windGust: number;
     /** Blade material roughness, 0..1. */
     roughness: number;
+    /**
+     * Ground-cover mat strength, 0..1: the patch paints a turf surface over its footprint instead of
+     * leaving the ground beneath the blades bare. 0 keeps blades only.
+     */
+    groundCover: number;
     /** Seed string; same seed reproduces the same blade layout. */
     seed: string;
 }

package/dist/world/grassKind.js

@@ -28,6 +28,7 @@ export const GRASS_DEFAULTS = {
     windSpeed: 1.6,
     windGust: 0.16,
     roughness: 0.85,
+    groundCover: 0.9,
     seed: "",
 };
 /** The grass parameter schema — drives the inspector and `meta` parse via the studio seam. */
@@ -48,6 +49,7 @@ export const GRASS_SCHEMA = {
         { type: "range", key: "windSpeed", label: "wind speed", min: 0, max: 4, step: 0.05, default: GRASS_DEFAULTS.windSpeed },
         { type: "range", key: "windGust", label: "gust scale", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.windGust },
         { type: "range", key: "roughness", label: "roughness", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.roughness },
+        { type: "range", key: "groundCover", label: "ground cover", min: 0, max: 1, step: 0.02, default: GRASS_DEFAULTS.groundCover },
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
@@ -81,6 +83,7 @@ export function readGrassRules(meta) {
         windSpeed: metaNumber(meta, "windSpeed", GRASS_DEFAULTS.windSpeed),
         windGust: metaNumber(meta, "windGust", GRASS_DEFAULTS.windGust),
         roughness: metaNumber(meta, "roughness", GRASS_DEFAULTS.roughness),
+        groundCover: Math.max(0, Math.min(1, metaNumber(meta, "groundCover", GRASS_DEFAULTS.groundCover))),
         seed: metaString(meta, "seed", GRASS_DEFAULTS.seed),
     };
 }

package/dist/world/terraform.d.ts

@@ -57,6 +57,14 @@ export interface TerrainMaterialLayer {
     tint?: string;
     /** Layer master opacity 0..1 — scales this layer's blend weight everywhere. */
     opacity?: number;
+    /**
+     * Material library name (e.g. `"foliage/grass"`) whose scanned PBR color map paints this layer,
+     * as authored. The editor resolves it into {@link TerrainMaterialLayer.materialUrl} so the runtime
+     * needs no asset-library lookup.
+     */
+    material?: string;
+    /** Resolved URL of the layer's scanned color map, written by the editor from {@link TerrainMaterialLayer.material}. */
+    materialUrl?: string;
 }
 export interface TerraformSnapshot {
     bounds: Aabb;

package/dist/world.d.ts

@@ -31,6 +31,7 @@ export { MOVEMENT_TUNING, type CollisionObstacle } from "./movement/movementMode
 export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/playerMovement.js";
 export { POSE_HITBOX, createPoseState, type MovementPose } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
+export { createLaneGraph, laneGraphFromDocument, type LaneEdgeConfig, type LaneGraph, type LaneGraphConfig, type LaneGraphDocumentOptions, type LaneIntersection, type LaneIntersectionConfig, type LaneNode, type LanePose, type LaneRightOfWay, type LaneSignalProgram, type LaneSpan, type LaneSpot, } from "./nav/laneGraph.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { createNavCrowd, type NavCrowd, type NavCrowdAgentSpec, type NavCrowdAgentView, type NavCrowdOptions, type NavCrowdRevalidate, type NavCrowdSnapshot, type NavCrowdStats, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
@@ -38,6 +39,7 @@ export { createNavGrid, findPath, slopeStepCost, type NavGrid, type NavPoint } f
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, type NavMeshAdjacency, type NavMeshData, type NavMeshLink, type NavMeshPath, type NavMeshQuery, type NavMeshQueryOptions, type NavMeshQuerySnapshot, } from "./nav/navMesh.js";
 export { createNavRuntime, navMeshFromBake, type AuthoredNavLink, type NavLinkKind, type NavRebuildStats, type NavRegion, type NavRuntime, type NavRuntimeOptions, type NavRuntimeSnapshot, type SceneBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, type PathFollowConfig, type PathFollowProgress, type PathFollowState, type PathProgress, type Waypoint, } from "./nav/pathFollow.js";
+export { createTraffic, type Traffic, type TrafficCarView, type TrafficOptions, type TrafficRoutePolicy, type TrafficSignalState, type TrafficSnapshot, type TrafficStats, type TrafficTuning, } from "./nav/traffic.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, type AttackMoveOrderPayload, type EmptyOrderPayload, type EngagementKindConfig, type EngagementOrderState, type MoveOrderPayload, type OrderKindConfig, type OrderMoveResult, type OrderMover, type OrderTargeting, type PatrolOrderPayload, type PatrolOrderState, type TargetedOrderPayload, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, type Order, type OrderCancelReason, type OrderEvent, type OrderIssueResult, type OrderKind, type OrderOutcome, type OrderPhase, type OrderProgress, type OrderQueue, type OrderQueueOptions, type OrderQueuePolicy, type OrderQueueState, type OrderRegistry, type OrderRejection, type OrderRequest, type OrderStartResult, type OrderTickReport, type OrderVec3, } from "./orders/orderQueue.js";
 export { createBallisticSweep, type BallisticSweep, type BallisticSweepHit } from "./physics/ballisticSweep.js";
@@ -48,14 +50,16 @@ export { tickDrivableVehicle } from "./physics/drivableVehicle.js";
 export { createAircraftDynamics, type AircraftAxis, type AircraftDynamics, type AircraftKind, type AircraftOptions, type AircraftStep, type AircraftTuning, type FlightControlInput, type FlightControlRates, type FlightVector, } from "./physics/flightDynamics.js";
 export { ForceVolume, PlatformCarry } from "./physics/forceVolume.js";
 export { combineGravity, pointGravity, uniformGravity, type GravityField, type GravityVector, type PointGravityOptions, } from "./physics/gravityField.js";
-export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, } from "./physics/kinematicVehicle.js";
+export { createKinematicVehicle, type KinematicChassisTuning, type KinematicDynamicsTuning, type KinematicPowertrainTuning, type KinematicSteeringTuning, type KinematicVehicle, type KinematicVehicleStep, type KinematicVehicleTuning, type KinematicWeightTransferTuning, } from "./physics/kinematicVehicle.js";
 export { PhysicsWorld, SHAPE_BOX, SHAPE_SPHERE, type AddBodyOptions, type CollisionEvent, type PhysicsStats, } from "./physics/physicsWorld.js";
 export { createRagdoll } from "./physics/ragdoll.js";
 export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph, type CollapseEvent, type StructureMaterial } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve, type GripCurve } from "./physics/vehicleBody.js";
+export { createVehicleDamage, damagedAxis, damagedTuning, type VehicleDamage, type VehicleDamageConfig, type VehicleDamageEffect, type VehicleDamageEffectResolved, type VehicleDamageState, type VehicleDamageTransition, type VehicleDamageZone, type VehicleDamageZoneState, type VehicleDeformation, } from "./physics/vehicleDamage.js";
 export { createVehicleObstacleClamp, type VehicleImpact, type VehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export { applyVehicleParts, feelOf, withPart, type VehicleFeel, type VehiclePart, type VehiclePartEffect, type VehicleSetup, type VehicleStat, } from "./physics/vehicleParts.js";
 export { type ObjectSlotRejection, type ObjectSlotResult, type ObjectSlotTransfer, type SceneObjectSlots, } from "./runtime/context/objectSlots.js";
 export { createAssetCatalog, type AssetCatalog, type ModelAssetRef, type ModelDims } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator, type GeneratedAsset, type GeneratedPart } from "./scene/assetGenerator.js";

package/dist/world.js

@@ -31,6 +31,7 @@ export { MOVEMENT_TUNING } from "./movement/movementModel.js";
 export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/playerMovement.js";
 export { POSE_HITBOX, createPoseState } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
+export { createLaneGraph, laneGraphFromDocument, } from "./nav/laneGraph.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
 export { createNavCrowd, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
@@ -38,6 +39,7 @@ export { createNavGrid, findPath, slopeStepCost } from "./nav/navGrid.js";
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, } from "./nav/navMesh.js";
 export { createNavRuntime, navMeshFromBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, } from "./nav/pathFollow.js";
+export { createTraffic, } from "./nav/traffic.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, } from "./orders/orderQueue.js";
 export { createBallisticSweep } from "./physics/ballisticSweep.js";
@@ -55,7 +57,9 @@ export { SpatialGrid } from "./physics/spatialGrid.js";
 export { StructureGraph } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve } from "./physics/vehicleBody.js";
+export { createVehicleDamage, damagedAxis, damagedTuning, } from "./physics/vehicleDamage.js";
 export { createVehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export { applyVehicleParts, feelOf, withPart, } from "./physics/vehicleParts.js";
 export {} from "./runtime/context/objectSlots.js";
 export { createAssetCatalog } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator } from "./scene/assetGenerator.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.26.0",
+  "version": "0.27.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.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.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.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-combat/SKILL.md

@@ -24,7 +24,9 @@ spread, damage — hand the definition to `createWeaponSystem`
 (`combat/weaponSystem`): it runs single/auto/burst, hitscan or ballistic
 projectiles, interrupted reloads and a readable ammo economy, and resolves both
 deliveries through `createDamageRuntime`. Generated guns (rolled parts) are the
-same `WeaponDefinition`; see
+same `WeaponDefinition`: `loot/lootGen` rolls the item and `loot/lootWeapon`'s
+`lootWeaponDefinition` maps its stats onto one, so no second weapon type exists;
+see
 [reference.md](reference.md#weapons-as-data).
 For scene-backed `createProjectileSystem`, inject authoritative `rng`; spread
 samples independent pellet rays and prediction stays on the center ray. The

package/skills/jgengine-gameplay/SKILL.md

@@ -38,6 +38,37 @@ Pins consume no choice RNG and must satisfy the same pool and constraints;
 incompatible pins backtrack earlier unpinned choices or return `unsatisfiable`
 within the configured attempt and pick budgets.
 
+Roll whole named gear from an authored catalog with `rollLoot`
+(`loot/lootGen`): bases with mount slots, parts, affix pools, weighted rarity
+tiers, manufacturer stat personalities and a level curve, all caller data.
+`validateLootItem` names each defect, `compareLootItems` returns per-stat deltas
+and a weighted score, and `lootWeaponDefinition` (`loot/lootWeapon`) projects a
+rolled item onto a `WeaponDefinition` for `createWeaponSystem`. `createLootRoller`
+counts drops per rarity for a debug probe and snapshots its counters. Sample
+catalog, distribution check and generated-weapon proof are in
+[reference-systems.md](reference-systems.md#procedural-gear).
+
+Resolve an authored XP curve with `defineXpCurve` (`progression/xpCurve`): one growth rule
+(`flat`, `linear`, `power`, `geometric`, `table`), a `maxLevel` cap and a stated `rule` string;
+`table()` and `totalXpFor()` read the same data, and `track()` hands those thresholds to
+`leveling`. Spend a character's points in `createSkillTree` (`progression/skillTree`): nodes carry
+a point `cost`, `requires`, `excludes`, `passives` and `actives`, `synergies` pay off two or more
+ranked nodes together, `respec()` refunds exactly the points spent, and `resolved()` returns the
+`StatModifierSet` plus ability-slot-shaped actives to feed `createStats` / `createAbilityKit`.
+Score a whole loadout with `gearScore` (`progression/gearScore`) on the same weight policy as
+`compareLootItems`. [reference-systems.md](reference-systems.md#progression-and-gear-score) shows
+the data shapes and a two-build comparison.
+
+Wear gear with `createEquipment` (`inventory/equipment`): slot defs own accepted kinds and the slots
+they block, item defs own the slots an item may occupy, a filled slot swaps and hands back the
+replaced item, and `state()` / `restore()` round-trip the worn set. Weigh a character with
+`characterLoad` (`inventory/carryLoad`), which turns carried inventories plus worn gear into the
+shared encumbrance bands (`moveMultiplier`, sprint/jump gates, `remaining`), so `canCarry` gates a
+pickup. Declare a stash as its own inventory (`tier: "banked"`) and move items with
+`InventorySet.move`; `snapshot()` / `restore()` save both as detached data. The bag and stash render
+through `<InventoryGrid>` with `<EquipmentSlots>` above it. See
+[inventory, equipment and weight](reference-systems.md#inventory-equipment-and-weight).
+
 Validate generated quest catalogs with `validateQuestCatalog` (`game/questCatalog`).
 Follow the [quest authoring recipe](recipes/quest-authoring.md) for bounded batches,
 canonical facts, external unlock declarations, and precise repair diagnostics.