@jgengine/core 0.26.0 → 0.28.0

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
@@ -42,6 +44,12 @@ compose through `createDamageRuntime` (`combat/damageRuntime`): a readable table
 time-to-kill quotes, and status ticks that follow the declared stack rule. It
 snapshots/restores as plain data; see
 [reference.md](reference.md#damage-runtime-armor-crits-and-statuses).
+Both damage paths raise `combat.damage` on `ctx.game.events`, one event per target
+application: the runtime with the table `type`, and `ctx.scene.entity.effect` with
+the effect id as `type` and `remaining` read from the last pool in the receive
+order. Use the runtime for new damage that needs types, zones or armor; keep the
+effect path for games that already drain `receive` pools. Neither delegates to
+the other, so a hit never raises the event twice.
 
 Closure-backed magazines expose snapshot/restore and `retune` for capacity/reload
 changes without reconstructing ammo state; capacity overflow is explicit.

package/skills/jgengine-combat/api.md

@@ -69,7 +69,7 @@
 - `DamageTableDef` (interface): interface DamageTableDef — A serializable damage table: damage types scored against resistance classes, plus the armor curve those rows are read with. It is data a generated gun (B3.1) and a weapon runtime (B2.3) pass in; the engine holds no built-in elemental chart.
 - `DamageTableRow` (interface): interface DamageTableRow — One readable row: a type against a resistance class at a given armor value.
 - `DamageTypeDef` (interface): interface DamageTypeDef — One damage type's row in a damage table: a caller-owned id (`"kinetic"`, `"fire"`) and how it fares against each resistance class a target can present (`"flesh"`, `"shield"`, `"armor"`). Values below `1` are resisted, `1` is neutral, above `1` is a weakness, and `0` is immune.
-- `DeathReason` (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; via?: { item?: string } } | { kind: "environment"; source: string } | { kind: "self"; source: string } — Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event.
+- `DeathReason` (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; source?: string; via?: { item?: string } } | { kind: "environment"; source: string; attacker?: string } | { kind: "self"; source: string } — Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event. `source` names what dealt it: a player kill's killer instance id, or the hazard/item of an environment death; `attacker` carries the non-player entity's instance id when one dealt it.
 - `DefenseResolution` (interface): interface DefenseResolution — Result of resolving an incoming hit against a defensive window: `outcome` is the graded defense (`"parry"`/`"block"`/`"iframe"`/`"hit"`) and `perfect` is true when the input landed inside the tight just-frame at the window's start rather than its wider active span.
 - `DuplicateDamageTypeError` (class): class DuplicateDamageTypeError extends Error — Raised when a table lists the same damage type twice, which would make the winner depend on order.
 - `EncounterConfig` (interface): interface EncounterConfig<TData = unknown> — Non-serializable configuration for an encounter: the authored phase tree plus predicate and spawn-provider registries. Re-supplied alongside a loaded {@link EncounterState}, the way `advanceSpawnDirector` pairs config with state, so the state itself stays pure data.
@@ -243,7 +243,7 @@
 - `createCoverField` (function): function createCoverField(options: CoverFieldOptions): CoverField — Cover over authored boxes: derive the stand points once, re-derive them after an edit, and answer bounded nearest-cover queries. `walkable` is injected, so the seam checks the game's own ground test (`nav.findPolygon(point) !== null`) instead of assuming a flat floor.
 - `createDamageClamp` (function): function createDamageClamp(config: DamageClampConfig): DamageInterceptor — A stateless interceptor that caps any single application at `maxPerHit`.
 - `createDamagePipeline` (function): function createDamagePipeline(initial?: readonly DamageInterceptor[]): DamagePipeline — Create a mutable damage interception chain that state transitions install into and remove from — e.g. add an invulnerability interceptor on phase enter and drop it on phase exit. Evaluation order is install order.
-- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet.
+- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
 - `createDeathSystem` (function): function createDeathSystem(deps: DeathSystemDeps): DeathSystem — Resolve entity death and the on-death consequences — drops, respawn eligibility, kill credit.
 - `createDefensiveWindow` (function): function createDefensiveWindow(config: DefensiveWindowConfig): DefensiveWindow — Open a timed defensive window — block, parry, or i-frames — and test incoming hits against it.
 - `createDotField` (function): function createDotField(): DotField — Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`.
@@ -462,7 +462,7 @@
 - `TargetProfile` (interface): interface TargetProfile — What a target presents to the table: one resistance class and its armor points.
 - `TimeToKill` (interface): interface TimeToKill — A quoted time to kill for one fixed hit against one health pool.
 - `UnknownTargetProfileError` (class): class UnknownTargetProfileError extends Error — Raised when a hit names a target that was never registered — a wiring error, not a 0-damage hit.
-- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet.
+- `createDamageRuntime` (function): function createDamageRuntime(config: DamageRuntimeConfig): DamageRuntime — Build a damage model from data. The number a hit lands is `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the same table and armor, so a burn on an armored target is mitigated like a bullet. Every application — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type, amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
 
 ## @jgengine/core/combat/damageTable
 
@@ -501,7 +501,7 @@
 
 ## @jgengine/core/combat/deathReason
 
-- `DeathReason` (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; via?: { item?: string } } | { kind: "environment"; source: string } | { kind: "self"; source: string } — Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event.
+- `DeathReason` (type): type DeathReason = | { kind: "player_kill"; killerUserId: string; source?: string; via?: { item?: string } } | { kind: "environment"; source: string; attacker?: string } | { kind: "self"; source: string } — Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event. `source` names what dealt it: a player kill's killer instance id, or the hazard/item of an environment death; `attacker` carries the non-player entity's instance id when one dealt it.
 
 ## @jgengine/core/combat/defensiveWindow
 
@@ -541,6 +541,7 @@
 - `AreaTarget` (interface): interface AreaTarget { instanceId: string; scale: number } — ⚠ undocumented
 - `AreaTargetInput` (interface): interface AreaTargetInput { at: EntityPosition; radius: number; falloff?: "linear" | "none"; los?: boolean } — ⚠ undocumented
 - `CombatSpatialDeps` (interface): interface CombatSpatialDeps { inRadius(center: EntityPosition, radius: number): string[]; hasLineOfSight(from: EntityPosition | string, to: string): boolean; positionOf(instanceId: string): EntityPosition | undefined } — ⚠ undocumented
+- `EffectDamageApplication` (interface): interface EffectDamageApplication — One effect application that drained a target's pools, as an announcer needs it. The effect path has no damage table, so the caller names the channel (`effect`) and reads health its own way.
 - `EffectInput` (type): type EffectInput = SingleTargetEffectInput | AreaEffectInput — ⚠ undocumented
 - `EffectResult` (interface): interface EffectResult { instanceId: string; effect: string; applied: AppliedPoolDelta[]; lethal: boolean; slain?: SlainIdentity } — ⚠ undocumented
 - `EffectSystem` (interface): interface EffectSystem { canReceive(instanceId: string, effect: string, magnitude?: number): string | null; preview(input: SingleTargetEffectInput): number; applyEffect(input: EffectInput): EffectResult[] } — ⚠ undocumented · used by `createEffectSystem`: Resolve direct or area resource effects through caller-owned stat pools, including ordered absorption, restoration, modifiers, and lethal co…

package/skills/jgengine-combat/reference.md

@@ -49,6 +49,8 @@ AoE: `inRadius(at, radius)` → LoS filter (default on) → `canReceive` per tar
 
 Each per-target `EffectResult` carries `{ instanceId, effect, applied, lethal }`. On a **lethal** hit it additionally carries `slain: { catalogId, name?, userId? }` — the victim's identity captured **before** the death system despawns it, so kill credit / XP reads the slain kind straight off the call result without a spawn-time id→kind registry (a non-lethal hit omits `slain`). This is the synchronous complement to the `entity.died` event: use `slain` when the code awarding the kill is the same code that fired the effect; use `entity.died` for decoupled listeners (quests, feeds, leaderboards).
 
+Every draining application also raises one `combat.damage` (`DamageAppliedEvent`) on `ctx.game.events` per target it lands on: `source` is the effect's `from`, `type` is the effect id, `amount` is the total drained, `absorbed` is the incoming magnitude the receive modifiers and depleted pools stopped, and `remaining`/`lethal` read the **last** stat in the receive order — the pool whose exhaustion counts as death. A restorative application (`via: { amount: -n }`) raises no damage event.
+
 `canReceive`'s optional signed `magnitude` makes the check direction-aware: positive (or omitted) keeps the standard `"pools-depleted"` check; negative checks the opposite direction and returns `"pools-full"` only when every stat in the receive order is already at max — so a heal (`via: { amount: -n }`) correctly reaches a fully-depleted target and is rejected only when there's nothing left to restore.
 
 **Projectiles** (aim-based — no target ids):
@@ -145,6 +147,8 @@ Genre systems layered over the same effects/projectiles/targeting/loot primitive
 
 `createDamageRuntime` (`combat/damageRuntime`) is the stateful in-process composition of the table, the zones, the armor curve, and carried statuses. A number reads as `base × zone multiplier × type multiplier × (1 − armor mitigation)`; `hit()` returns every stage, `tick()` ticks statuses through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones, or definitions without dropping either. For multiplayer authority, keep the pure stages (`resolveMatchup`, `resolveReceivedDamage`, `resolveStatusApplication`) and replicate their results instead.
 
+With `events: ctx.game.events` and `healthOf`, every hit and status tick raises one `combat.damage` carrying the table `type`, the final `amount`, what resistance stopped (`absorbed`), and `remaining`/`lethal`. The runtime and the effect path each announce their own application; neither calls the other, so a game that uses both gets one event per blow, not two. Prefer the runtime for damage that needs types, zones, armor or time-to-kill; the effect path stays for pools drained directly through the entity catalog's `receive` rules and now announces the same event with the effect id as `type`.
+
 - **Type × resistance table** (`combat/damageTable`) — `{ types: [{ id, vs: { armor: 2, flesh: 0.5 }, bypassArmor? }], armor: { halfValue, maxMitigation }, defaultMultiplier? }`. `typeMultiplier` reads one pair; `resolveTableDamage` folds type, armor, and base into a row; `readDamageTable` returns every row at given armor values and `formatDamageTable` prints them. Armor uses `armor / (armor + halfValue)` — armor equal to `halfValue` halves the hit — so a designer reads the number rather than guessing a percentage per point. Unknown types throw; unknown resistance classes use the default.
 - **Hit zones and crits** (`combat/hitZones`) — `{ zones: [{ id, multiplier?, critChance?, critMultiplier? }], defaultZone, critChance?, critMultiplier? }`. `resolveHitZone(table, zone, rng)` rolls once and returns **one** multiplier: a crit replaces the zone's normal multiplier (head 1.5× normal, 2.5× crit → 2.5×, never 3.75×). `hitZoneMultiplier(table, zone, crit)` quotes the same number without a roll, which is what `timeToKill({ crit: true })` uses.
 - **Statuses** (`combat/statusRuntime`) — `createStatusRuntime({ statuses, rng?, applyDamage? })`; each `StatusDef` declares `{ id, stack, durationMs, intervalMs?, magnitude?, effect?, chance? }`. `stack` is the existing `StatusStackPolicy` (`refresh` / `stack` to `max` / `replace` / `ignore`), and it is the only thing that changes stacks: a tick deals `magnitude × stacks`, so two burns at 4 per tick deal 8, never 16. `effect` is `{ kind: "damage", channel }` (routed through `applyDamage`, so resistances and armor apply) or `{ kind: "stat", stat }` (read with `statDelta`, e.g. negative `moveSpeed` for slow or negative `armor` for corrode). Reapplication restarts the tick clock instead of banking a burst; ticks per call are bounded and the remainder carries. `dotField` stays the cheap no-stacking scheduler.

package/skills/jgengine-gameplay/SKILL.md

@@ -38,10 +38,60 @@ 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.
 
+Run a mission with `createMissionRuntime` (`mission/mission`): a mission is data — a graph of
+objectives the machine walks, with named fail states, per-objective timers, conditional branches and
+rewards. `escortMission`, `chaseMission` and `defendMission` (`mission/compositions`) are compositions
+of the same `reach`/`interact`/`survive`/`pursue`/`kill`/`collect` kinds, not archetypes: an escort is
+a `reach` with an `actor-died` guard, a defend is a `survive` with a survivor floor, a chase is a
+`pursue` with an escape guard. Start, advance and fail missions from authored scene markers with
+`registerMissionTriggerActions` and `createMissionTriggerBridge` (`mission/triggers`); positional
+objectives read `missionMarkers(document)`. Rewards route through the quest appliers and the loot
+registry (`applyMissionRewards`). `validateMissionCatalog` is the content gate and it fails a mission
+whose success path is counters alone — `createMissionRuntime` runs it at construction, so a
+counter-only mission throws instead of shipping.
+
+Report what happened instead of polling your own counters: `tick(dt, { events })` takes
+`MissionWorldEvent`s (`kill`/`collect`/`deliver` with a target, actor and tags), an objective's `match`
+filter credits only matching ones - a decoy, a wrong weapon or a rival's kill does not advance it - and
+a `failOn` of kind `event` or `left-area` ends the run on a matching event or on an actor leaving an
+authored marker. `view()` is everything a HUD needs: label, `remaining`, `counted`/`count`,
+`step`/`steps`, `outcome` and `reason`.
+
 For cross-catalog sources and skill gates, compose `validateContentReferences` and
 `validateContentProgression` (`game/contentValidation`) with `validateRecipeCatalog`
 (`crafting/recipeCatalog`). Follow [content validation](reference-content-validation.md).
@@ -71,6 +121,10 @@ Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities.
 
 `createNearAgents` (`sim/nearAgents`) is the default near half: a nav crowd with a need set and a utility brain per agent, counting its decisions for tests and probes. Give it the same need definitions the off-screen world decays, or the two halves disagree at the boundary.
 
+`createVisitorPopulation` (`sim/population`) is the crowd a scene reports, and it is the bodies: a visitor joins only when your `VisitorWorld.admit` has made its body, and only while `VisitorWorld.has` holds it, so `onSite()` is the member count a HUD reads in O(1) and `arrivalsToday()` is the sum of the admissions the world accepted rather than a tally kept beside them. Arrival rate, capacity (a number or a function of the clock), the leaving rule and the `inside` bounds check are game policy; a refused body or one placed outside the bounds is released and never counted. `rollDay()` closes the day without emptying the park, `adopt` takes over a body a save or a seed made, and a restore only brings back members the world still holds.
+
+Rides and their lines are `createRideSystem` and `createWaitQueue` (`sim/rides`, `sim/queue`): a ride cycles load → ride → unload at its own capacity, wears against its own breakdown curve, and reports boards, alights, breakdowns and repair costs through a sink; the wait a guest faces comes from the queue's own measured boarding throughput, not a configured constant. Guest choice stays on the utility brain — `rideChoiceOptions` compiles a guest's `RideTaste` (intensity comfort, nausea comfort, queue tolerance) and the park's ratings into options, `rideChoiceCandidates` costs each one by its own line's wait, and `createRideChooser` wires both to one guest. Ratings, cycle times, breakdown curves and costs are caller data, and `retune` changes them in play.
+
 For staffed production, use `stationOutputRate` (`work/staffedStation`) to resolve
 caller-owned worker stats and efficiency, then feed the rate to `tickProduction`.
 Keep staffing and production progress in the same serializable store; the
@@ -120,6 +174,38 @@ A character kit-bashed from primitives/`ModelPart`s (no skeleton, no clips) anim
 - `ctx.game.chat.send(userId, text)` targets global chat; `recent({ limit })` returns at most 100 messages. The default is 240 characters and one message per author per channel every two seconds. Rejected messages need visible UI feedback.
 - Hosts reuse `validateChatMessage` and `decideRateWindow`, storing the rate window transactionally with each accepted operation. Preserve chat rate windows when saving/restoring chat state.
 
+Price goods with `createMarket` (`economy/market`): `price = clamp(basePrice × (coverPeriods × demand / max(stock, 1))^elasticity)`
+between `basePrice × minFactor` and `basePrice × maxFactor`, over finite integer
+stock. `sell` refuses a sale it cannot cover and names the shortfall, `restock`
+lowers the price, `recordDemand(unitsSold, unitsUnmet)` moves demand from what
+buyers actually took, and `priceCurve`/`retune` change the policy. Amounts are
+integer minor units, so a long simulation never drifts.
+
+Keep the books with `createTransactionLedger` (`economy/transactionLedger`):
+per-account balances in integer minor units plus a journal recording every
+movement, the balance it produced and a caller-owned `reason`. `post` is the one
+money path, and `totals()` keeps a per-reason count and net past the `maxEntries`
+journal cap. Register upkeep, rent or a subscription with `addCharge` and settle
+it on its cadence with `chargeDue` — bounded per charge and per advance, and a
+cycle with no funds is counted as missed rather than overdrawing.
+
+Lend and borrow with `buildLoanSchedule` / `createLoanBook` (`economy/loanBook`):
+a schedule in integer minor units (`"amortized"` or `"flat"`), the principal
+posted on the draw, interest and principal posted as separate reason-tagged
+entries, and arrears that count once per advance until the loan defaults at
+`maxMissed`. `repay` pays principal early; a save stores terms and progress and
+the schedule is rebuilt on restore.
+
+One document saves the whole world. `createGameSave` (`game/gameSave`) holds one versioned
+`GameSaveDocument` with a section per registered system, named slots, caller-policy autosave and a
+`migrate` path, over the same injected `SaveBackend` `createSaveStore` uses. Register each stateful
+system once by `name` with its `snapshot()`/`restore()`; `capture()` builds the document,
+`save()`/`touch()` persist it, `load()`/`switchSlot()` restore every section, and
+`digest()`/`digests()` hash the state for a save/reload determinism test. Pass `rng: { seed, stream }`
+so the world's shared seed and cursor survive the save. A snapshot field that means "never" must
+serialize as `null` and be mapped back on restore - `Infinity` becomes `null` through JSON, which
+silently changes a restored run.
+
 For timed away missions, compose the pure transitions in `work/expedition` with
 your existing `defineStore` and clock. The [expedition recipe](recipes/expeditions.md)
 keeps bounded offline catch-up, finite supplies, return/death, capacity and RNG