@jgengine/core 0.25.0 → 0.27.0

package/skills/jgengine-gameplay/capabilities.md

@@ -36,12 +36,15 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `cancelJob` (function) · `import { cancelJob } from "@jgengine/core/gameplay"`
 
-## carry-encumbrance — carried mass vs capacity into movement penalty tiers and a speed multiplier
+## carry-encumbrance — gate a pickup against the carrier's remaining capacity
 
+- `canCarry` (function) · `import { canCarry } from "@jgengine/core/inventory/carryLoad"`
+- `characterLoad` (function) · `import { characterLoad } from "@jgengine/core/inventory/carryLoad"`
 - `resolveEncumbrance` (function) · `import { resolveEncumbrance } from "@jgengine/core/inventory/encumbrance"`
 
-## carry-load — sum carried mass from item stacks via an injected mass resolver
+## carry-load — read carried stacks out of one or more inventories for a weight query
 
+- `carriedEntries` (function) · `import { carriedEntries } from "@jgengine/core/inventory/carryLoad"`
 - `totalLoad` (function) · `import { totalLoad } from "@jgengine/core/inventory/encumbrance"`
 
 ## cell-grid — immutable 2D board of cells with row clears, gravity collapse, and match runs
@@ -148,6 +151,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `enqueue` (function) · `import { enqueue } from "@jgengine/core/gameplay"`
 
+## equipment-slot-inventory — wear gear by slot with item-kind rules, two-handed blocking and replace-on-equip
+
+- `createEquipment` (function) · `import { createEquipment } from "@jgengine/core/inventory/equipment"`
+
 ## event-bus — typed publish/subscribe bus for gameplay events
 
 - `createGameEvents` (function) · `import { createGameEvents } from "@jgengine/core/gameplay"`
@@ -188,6 +195,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/core/gameplay"`
 
+## gear-score — score a loadout from stat weights, level, rarity and slot coverage
+
+- `gearScore` (function) · `import { gearScore } from "@jgengine/core/gameplay"`
+
 ## group-credits — turn a flat list of credited things into ordered credit sections
 
 - `groupCredits` (function) · `import { groupCredits } from "@jgengine/core/game/credits"`
@@ -212,7 +223,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEmptyInventory` (function) · `import { createEmptyInventory } from "@jgengine/core/inventory/inventoryModel"`
 
-## inventory-split — split a stack into a target or first-empty slot
+## inventory-split — split a stack into a target or first-empty slot, honoring a stack limit
 
 - `splitStack` (function) · `import { splitStack } from "@jgengine/core/inventory/inventoryModel"`
 
@@ -287,20 +298,45 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `RarityStyle` (interface) · `import { RarityStyle } from "@jgengine/core/gameplay"`
 
+## loot-comparison — compare two rolled items with per-stat deltas and a weighted score
+
+- `compareLootItems` (function) · `import { compareLootItems } from "@jgengine/core/gameplay"`
+
 ## loot-filter — filter and highlight drops by rarity/name rules
 
 - `evaluateLootFilter` (function) · `import { evaluateLootFilter } from "@jgengine/core/gameplay"`
 
+## loot-generation — roll a named item from bases, parts, affixes, rarity weights, manufacturer personalities and level scaling
+
+- `rollLoot` (function) · `import { rollLoot } from "@jgengine/core/gameplay"`
+
 ## loot-pipeline — compose ordered loot pools with fallbacks, roll modifiers, and provenance
 
 - `createLootPipeline` (function) · `import { createLootPipeline } from "@jgengine/core/gameplay"`
 - `defineLootPipeline` (function) · `import { defineLootPipeline } from "@jgengine/core/gameplay"`
 
+## loot-roller — roll items from one validated catalog while counting drops per rarity for a debug probe
+
+- `createLootRoller` (function) · `import { createLootRoller } from "@jgengine/core/gameplay"`
+
+## loot-score — split one stat block into per-stat weighted contributions
+
+- `lootStatContributions` (function) · `import { lootStatContributions } from "@jgengine/core/gameplay"`
+- `scoreLootStats` (function) · `import { scoreLootStats } from "@jgengine/core/gameplay"`
+
 ## loot-table — register loot tables and roll weighted randomized drops
 
 - `createLootRegistry` (function) · `import { createLootRegistry } from "@jgengine/core/gameplay"`
 - `lootTable` (function) · `import { lootTable } from "@jgengine/core/gameplay"`
 
+## loot-validation — check a rolled item against its catalog and report each defect with its code
+
+- `validateLootItem` (function) · `import { validateLootItem } from "@jgengine/core/gameplay"`
+
+## loot-weapon — feed a rolled item into a weapon definition so generated gear fires through the weapon system
+
+- `lootWeaponDefinition` (function) · `import { lootWeaponDefinition } from "@jgengine/core/gameplay"`
+
 ## maturation-stage — resolve the baby/juvenile/adolescent/adult stage from elapsed maturation
 
 - `maturationStage` (function) · `import { maturationStage } from "@jgengine/core/game/breeding"`
@@ -329,6 +365,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `freezeNarrativeCanon` (function) · `import { freezeNarrativeCanon } from "@jgengine/core/game/narrativeAuthoring"`
 
+## near-agents — nav crowd plus per-agent needs and utility brains for on-screen residents
+
+- `createNearAgents` (function) · `import { createNearAgents } from "@jgengine/core/gameplay"`
+
+## needs — decaying needs an agent reads by index to decide what it wants next
+
+- `createNeedSet` (function) · `import { createNeedSet } from "@jgengine/core/gameplay"`
+
 ## notice-feed — serializable tone-tagged notice/event feed bounded by count and age (toasts, life events, killfeed)
 
 - `appendFeed` (function) · `import { appendFeed } from "@jgengine/core/gameplay"`
@@ -343,6 +387,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `evaluateObjective` (function) · `import { evaluateObjective } from "@jgengine/core/gameplay"`
 
+## offscreen-world — schedules agents near the player as real state and far ones as cheap state
+
+- `createOffScreenWorld` (function) · `import { createOffScreenWorld } from "@jgengine/core/gameplay"`
+
 ## param-layers — register parameter layers by stable id and resolve serialized selections
 
 - `createLayerRegistry` (function) · `import { createLayerRegistry } from "@jgengine/core/gameplay"`
@@ -470,6 +518,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createVfxInstanceStore` (function) · `import { createVfxInstanceStore } from "@jgengine/core/gameplay"`
 
+## routine-timeline — authored daily routines (home, work, meal) resolved against the world clock
+
+- `resolveRoutine` (function) · `import { resolveRoutine } from "@jgengine/core/gameplay"`
+
 ## rule-selection — register rules and bridge a selection to its contributed parameter layers
 
 - `createRuleRegistry` (function) · `import { createRuleRegistry } from "@jgengine/core/gameplay"`
@@ -507,11 +559,16 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## shaped-placement — find a shaped inventory item's first fit with ordered rotations, row-major placement, and an explicit search budget
 
 - `findShapedPlacement` (function) · `import { findShapedPlacement } from "@jgengine/core/inventory/shapedGrid"`
+- `fitShapedItem` (function) · `import { fitShapedItem } from "@jgengine/core/inventory/shapedGrid"`
 
 ## shop-grid — serializable vendor/shop stock with buy/sell over a caller-owned wallet — finite/unlimited qty, sell-back, restock/setPrice, snapshot/restore
 
 - `createShopStock` (function) · `import { createShopStock } from "@jgengine/core/gameplay"`
 
+## skill-tree — spend, refuse and refund points over an authored tree with passives, actives and synergies
+
+- `createSkillTree` (function) · `import { createSkillTree } from "@jgengine/core/gameplay"`
+
 ## social-emotes — emotes and social interactions between nearby players
 
 - `createSocial` (function) · `import { createSocial } from "@jgengine/core/gameplay"`
@@ -644,3 +701,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## work-queued-jobs — list jobs waiting for a slot, in selection order
 
 - `queuedJobs` (function) · `import { queuedJobs } from "@jgengine/core/gameplay"`
+
+## xp-curve — resolve an authored xp growth rule into per-level thresholds, totals and a level cap
+
+- `defineXpCurve` (function) · `import { defineXpCurve } from "@jgengine/core/gameplay"`

package/skills/jgengine-gameplay/reference-systems.md

@@ -28,6 +28,124 @@ and level state, then emits every reached level in ascending order. State stays
 in the caller's save format and round-trips as ordinary JSON. See the
 [portable XP/leveling recipe](recipes/portable-xp-leveling.md).
 
+## Procedural gear
+
+`loot/lootGen` rolls a whole named item from a caller-authored `LootCatalog`:
+bases (`baseStats`, affix `pools`, mount `slots`), parts, affix pools, weighted
+`RarityTier`s, `LootManufacturerDef`s (name, flat `bias`, per-stat `scale`,
+favored pools) and a `levelScale` curve of `[level, multiplier]` points. A roll
+picks maker, base, rarity, one part per slot and `affixCount` affixes; stats are
+`base × rarity.statScale × levelScale`, plus part stats/multipliers, maker
+personality, then additive affixes and multiplicative ones. Additive affix
+rolls scale with level; multiplicative ones do not. Names follow one rule:
+maker, rarity word, first part word, first prefix affix, base name, first suffix
+affix. Every random draw uses the injected `rng`, so a seed reproduces the item.
+
+```ts
+import { compareLootItems, createLootRoller, lootWeaponDefinition, seededRng } from "@jgengine/core/gameplay";
+
+const roller = createLootRoller(catalog, { devtoolsName: "loot" });
+const item = roller.roll(seededRng(dropSeed), { level: 30 });
+const delta = compareLootItems(item, equipped, { lowerIsBetter: ["reload"] });
+const weapon = lootWeaponDefinition(item, { template, stats: { damage: "power", roundsPerMinute: "cadence" } });
+```
+
+`validateLootItem` returns coded issues (`unknown-base`, `part-category`,
+`missing-slot-part`, `unknown-affix`, `empty-name`…) and the roller's counters
+snapshot/restore as plain data. Register a roll through
+`proceduralLootEntry` into `item/itemInstanceRegistry` and hand its runtime id
+to `game/lootTable`; the weapon projection only maps stats it is told to, so a
+catalog without weapon stats stays usable for non-weapon gear. Check a
+distribution with a fixed seed over 10,000 drops against each tier's 4σ
+binomial bound rather than eyeballing shares.
+
+## Progression and gear score
+
+`progression/xpCurve` turns one authored growth rule into the level table, the cap and a
+plain-words rule line, so the balance lives in save-visible data:
+
+```ts
+import { createSkillTree, defineXpCurve, gearScore } from "@jgengine/core/gameplay";
+
+const xp = defineXpCurve({ growth: "power", step: 100, growthRate: 1.5, maxLevel: 40, round: "floor" });
+// rule: "power: 100 x level^1.5, floor (levels 1-40)"; xpForLevel(2) is 282, xpForLevel(40) is 0
+xp.levelForXp(xp.totalXpFor(7)).level; // 7
+xp.track(); // the same thresholds as a `leveling` track for a stat adapter
+
+const tree = createSkillTree({ nodes, synergies, points: 6 }, { devtoolsName: "skills" });
+tree.spend("strike"); // { ok: true, spent: 1, pointsAvailable: 5 }
+tree.canSpend("sight"); // { ok: false, reason: "requires", detail: '...needs rank 1 of "focus"' }
+const { stats, actives, synergies: live } = tree.resolved();
+tree.respec(); // { refunded: 6, pointsAvailable: 6 }
+```
+
+A `SkillNodeDef` is `{ id, branch?, cost?, maxRank?, requires?, requiresPointsInBranch?,
+excludes?, passives?, actives?, tags? }`; a `SkillSynergyDef` lists at least two `requires` and
+adds passives/actives only while they all hold. `excludes` is symmetric, so two nodes named as
+alternatives block each other in both directions. Actives are `{ id, cooldownMs?, resourceCost?,
+castType?, groups? }`, shaped to bind into `createAbilityKit` slots. Snapshot/restore carries
+`{ points, ranks }`; restore refuses unknown nodes, over-ranked nodes and negative points without
+mutating. A tree where breadth beats depth is the point: in the test fixture, four points down
+`strike` give `damage +3`, while the same four points in `strike x2`, `focus`, `sight` give
+`damage +4` plus the `overload` synergy and its action.
+
+`gearScore(set, options)` scores `slot -> { stats, level?, rarity? }` as
+`Σ_stat value × weight × (lowerIsBetter ? -1 : 1) + levelWeight × level + rarityScore[rarity]`,
+summed over filled slots, minus `emptySlotPenalty` per expected-but-empty slot; it also returns
+`bySlot`, `byStat`, `average`, `coverage` and `emptySlots`. `compareGearSets` ranks two loadouts.
+The stat term comes from `lootStatContributions`, the same function behind `scoreLootStats` and
+`compareLootItems`, so per-item and whole-loadout scores cannot drift apart.
+
+## Inventory, equipment and weight
+
+A carried bag and a stash are two declared inventories, so they hold separate plain state from the
+first frame and persist as `InventorySet.snapshot()`:
+
+```ts
+import { createInventorySet } from "@jgengine/core/inventory/inventoryModel";
+import { canCarry, characterLoad } from "@jgengine/core/inventory/carryLoad";
+import { createEquipment } from "@jgengine/core/inventory/equipment";
+
+const items = createInventorySet({ bag: { slots: 24 }, stash: { slots: 60 } }, traits);
+items.move("bag", 3, "stash", 0); // across inventories; a rejected move leaves both untouched
+const saved = items.snapshot(); // detached; JSON-safe; restore() refuses a bad save without mutating
+
+const gear = createEquipment(
+  [{ id: "weapon", blocks: ["offhand"] }, { id: "offhand" }, { id: "chest", accepts: ["armor"] }],
+  (itemId) => baseDefs[registry.get(itemId)?.baseId ?? itemId]?.gear, // rolled item -> its base's gear facts
+  { devtoolsName: "gear" },
+);
+gear.equip("chest", "plate"); // { status: "ok", replaced: null, ... }
+gear.equipBest("greatsword"); // first free preferred slot, else the first one it may replace
+
+const load = characterLoad({
+  carried: [items.state("bag")],
+  worn: gear.worn().map((entry) => entry.itemId),
+  weightOf: (itemId) => baseDefs[itemId]?.weight ?? 0,
+  capacity: 60 + stats.value("carryCapacity"),
+});
+load.moveMultiplier; // 1 unencumbered, decays across the soft band, 0 at capacity
+canCarry(load, 12); // gate a pickup; the overload policy stays the game's
+```
+
+`EquipSlotDef` owns `accepts` (item kinds) and `blocks` (slots it occupies while filled), and
+`EquipItemDef` owns the `slots` an item may occupy plus its `kind`; a filled slot swaps and returns
+the replaced item, so nothing is silently destroyed, and `state()` / `restore()` carry
+`{ slots: [[slotId, itemId]] }`. The stash is simply left out of `carried`, so its contents add no
+weight, and declaring it `tier: "banked"` keeps it out of `partitionOnDeath`'s lost half.
+
+For a footprint bag, `fitShapedItem` (`inventory/shapedGrid`) places the first legal spot or names
+why it does not fit — `too-large` with both sizes, `no-space` for a full board, `budget-exceeded` for
+an exhausted search. Stack rules stay in `ItemTraits`: `putItem` fills partial stacks then opens new
+ones up to the max stack, `moveItem` merges with a remainder, and `splitStack(..., limit)` refuses an
+`over-stack` merge instead of breaking the cap.
+
+The rendered side is the engine's: `<InventoryGrid inventoryId="bag" />` (`packages/react`) binds a
+live declared inventory with drag, swap, merge and split through the `inventory.move` /
+`inventory.split` commands, and `<EquipmentSlots items={...} />` paints the worn slots from
+`gear.worn()`. What the grid cannot yet do is drag from one inventory to another (bag to stash), so a
+stash transfer goes through `InventorySet.move` behind a button or command.
+
 ## Coherent authored content
 
 Keep stable ids and canonical facts for characters, factions, places, and world rules in the game's authored data. Record each chapter's prerequisites, consequences, and which facts it may introduce or change. The game's creative pillars, story voice, content palette, and desired player experience come from its author; generated prose, items, art, and assets must serve those constraints. Reuse constrained generation and validation code across games while each game owns its content and visual identity; do not fill catalogs from default genre kits or mass generic content.

package/skills/jgengine-world/SKILL.md

@@ -59,7 +59,13 @@ NPC decisions are a `decisionGraph` behavior: the graph and its blackboard are d
 
 For a bounded local detour over movement collision geometry, use `planSolidRoute` (`nav/solidRoute`) with an indexed `solidObstaclesNear` or `sourceObstaclesNear` query. Handle `no-path` and `budget` separately; retain caller movement, goals, terrain and retry policy. See [reference.md](reference.md#local-collision-routes) for limits.
 
-Route on a polygon nav mesh through one `createNavMeshQuery(mesh)` per mesh; price terrain and gate doors with `areaCosts` via `retune`, and keep `maxNodes` bounded so a long request returns a `partial` route instead of stalling a frame.
+Route on an editor-baked polygon nav mesh through `createNavRuntime` (`nav/navRuntime`): read the bake off the scene document with `navMeshFromBake(document.bakes)`, price terrain and gate doors with `areaCosts`, author doors, ladders and jumps as `AuthoredNavLink` world points, and call `applyMesh(nextBake)` after an edit — polygons that survive keep their identity through the returned `remap`, so only routes crossing changed polygons need re-planning (`createNavCrowd`'s `revalidate`). A bare `createNavMeshQuery` per mesh is still the lower-level seam; keep `maxNodes` bounded so a long request returns a `partial` route instead of stalling a frame.
+
+Move many agents across that mesh with `createNavCrowd` (`nav/navCrowd`): it plans corridors, follows the funnel-smoothed waypoints, keeps them apart with `createRvoCrowd` (`ai/rvo`) reciprocal velocity obstacles, bounds path searches to a per-tick time and count budget, and serializes through `snapshot`/`restore`. Give a crowd converging on one spot a `spread` radius so agents fan out (`ai/crowd`'s stable per-id offset) instead of stacking. Avoidance keeps agents inside the mesh's outer bounds; interior walls remain the game's collision layer.
+
+### Street traffic
+
+Vehicles on roads do not path-find: they follow authored lane spans. `createLaneGraph` (`nav/laneGraph`) resolves those spans — `traffic_lane` paths, or `road` paths from the editor's street bake, split where streets cross — into junctions, crossings with a signal program or first-come right-of-way, and parking spots; `laneGraphFromDocument` reads that straight off the scene document, so editing a road moves its traffic. `createTraffic` (`nav/traffic`) then drives cars on it: IDM car following and braking, one car at a time through each intersection box (only once the exit lane has room, which is what keeps a blocked crossing from wedging the network), signals with phases, lane changes across authored `left`/`right` neighbours, parking that reserves a spot, and `setDemand(count)` for fleet size — the time-of-day curve is the caller's, not the engine's. Cars are posed, not driven: when a player or a chase needs real handling, feed intent into `physics/kinematicVehicle` and let this seam keep the ambient city.
 
 ### Fallback-seam diagnostics