@jgengine/core 0.27.0 → 0.29.0

package/dist/vfx/particleBudget.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The graphics-tier particle budget. A tier caps the live particle count across every effect on
+ * screen; when the requested effects do not fit, whole effects are dropped in a defined order
+ * (lowest {@link ParticleBudgetEntry.priority} first) rather than every effect thinning out.
+ */
+/** One effect asking for particle capacity this frame. */
+export interface ParticleBudgetEntry {
+    /** Emitter or burst id; unique within the request. */
+    id: string;
+    /** Drop order: higher survives, lower is dropped first. */
+    priority: number;
+    /** Particles this effect wants (its pool maximum, or a burst's count). */
+    requested: number;
+}
+/** An admitted effect and the particles it may hold. */
+export interface ParticleBudgetGrant {
+    id: string;
+    particles: number;
+}
+/** What the tier cap admits, and what it drops. */
+export interface ParticleBudgetPlan {
+    /** Admitted effects in priority order, each with its granted particle count. */
+    grants: ParticleBudgetGrant[];
+    /** Dropped effect ids, lowest priority first — the defined drop order. */
+    dropped: string[];
+    /** Sum of the granted particle counts, never above the cap. */
+    particles: number;
+}
+/**
+ * Allocate a tier's particle cap across the effects that want it.
+ *
+ * Effects are visited highest priority first (ties keep authoring order) and each takes
+ * `min(requested, remaining)`. An effect that receives nothing is dropped, so the drop list comes
+ * out lowest priority first: ambient dressing (dust, weather) yields before gameplay-loud effects
+ * (explosions, muzzle flashes). The granted total never exceeds the cap, so the live particle
+ * count cannot either.
+ *
+ * @capability plan-particle-budget cap live particles to a graphics tier and drop whole effects lowest-priority-first when over budget
+ */
+export declare function planParticleBudget(entries: readonly ParticleBudgetEntry[], cap: number): ParticleBudgetPlan;

package/dist/vfx/particleBudget.js

@@ -0,0 +1,39 @@
+/**
+ * The graphics-tier particle budget. A tier caps the live particle count across every effect on
+ * screen; when the requested effects do not fit, whole effects are dropped in a defined order
+ * (lowest {@link ParticleBudgetEntry.priority} first) rather than every effect thinning out.
+ */
+function count(value, fallback = 0) {
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, Math.floor(value)) : fallback;
+}
+/**
+ * Allocate a tier's particle cap across the effects that want it.
+ *
+ * Effects are visited highest priority first (ties keep authoring order) and each takes
+ * `min(requested, remaining)`. An effect that receives nothing is dropped, so the drop list comes
+ * out lowest priority first: ambient dressing (dust, weather) yields before gameplay-loud effects
+ * (explosions, muzzle flashes). The granted total never exceeds the cap, so the live particle
+ * count cannot either.
+ *
+ * @capability plan-particle-budget cap live particles to a graphics tier and drop whole effects lowest-priority-first when over budget
+ */
+export function planParticleBudget(entries, cap) {
+    const limit = count(cap);
+    const ordered = entries
+        .map((entry, index) => ({ entry, index, priority: Number.isFinite(entry.priority) ? entry.priority : 0, wanted: count(entry.requested) }))
+        .sort((a, b) => (b.priority - a.priority) || (a.index - b.index));
+    const grants = [];
+    const dropped = [];
+    let remaining = limit;
+    for (const { entry, wanted } of ordered) {
+        const particles = Math.min(wanted, remaining);
+        if (particles <= 0) {
+            dropped.push(entry.id);
+            continue;
+        }
+        grants.push({ id: entry.id, particles });
+        remaining -= particles;
+    }
+    dropped.reverse();
+    return { grants, dropped, particles: limit - remaining };
+}

package/dist/vfx/particleDirector.d.ts

@@ -1,3 +1,4 @@
+import { type EffectOverride } from "./effectLibrary.js";
 import { type EmitterConfig, type ParticleEvent, type Vec3 } from "./particles.js";
 /** How a particle effect composites on screen: `additive` for sparks/fire/glow, `normal` for smoke/dust. */
 export type ParticleBlendHint = "additive" | "normal";
@@ -17,6 +18,8 @@ export interface ParticleBurst {
     blending?: ParticleBlendHint;
     emitterId?: string;
     options?: ParticleAttachOptions;
+    /** Graphics-tier drop order; higher survives. Default 0. */
+    priority?: number;
 }
 /** A bounded collision child effect; children cannot spawn further collision children. */
 export interface ParticleCollisionEffect {
@@ -43,6 +46,8 @@ export interface ParticleAttachOptions {
         maxAcceleration?: number;
         mask?: number;
     };
+    /** Graphics-tier drop order: higher survives, lower is dropped first. Default 0. */
+    priority?: number;
 }
 /** A keyed continuous emitter owned by the director until detached. */
 export interface ParticleEmitterSpec extends ParticleAttachOptions {
@@ -52,6 +57,11 @@ export interface ParticleEmitterSpec extends ParticleAttachOptions {
     offset?: Vec3;
     blending?: ParticleBlendHint;
 }
+/** A library effect played by name: where it plays, plus per-call overrides. */
+export interface EffectRequest extends EffectOverride {
+    /** Entity id a standing emitter tracks each frame (plus `offset`). */
+    follow?: string;
+}
 /** A cosmetic simulation event, labelled with its emitting effect. */
 export interface ParticleDirectorEvent extends ParticleEvent {
     emitterId: string;
@@ -87,6 +97,12 @@ export interface ParticleDirector {
     stop(id: string): void;
     /** Emit once through a named emitter's existing pool, including when stopped. */
     burstNamed(id: string, count: number): void;
+    /** Play a library effect by name once, as a one-shot burst at the request's position. */
+    play(name: string, request?: EffectRequest): void;
+    /** Create or replace a standing emitter from a library effect name under `id`. */
+    attachEffect(id: string, name: string, request?: EffectRequest): void;
+    /** The named effects a caller can play, from the shared library. */
+    effectNames(): readonly string[];
     /** Renderer-to-game cosmetic event exchange, bounded by the director's event limit. */
     reportEvents(id: string, events: readonly ParticleEvent[]): void;
     drainEvents(): ParticleDirectorEvent[];

package/dist/vfx/particleDirector.js

@@ -1,3 +1,4 @@
+import { effectNames, resolveEffect } from "./effectLibrary.js";
 import { validateEmitterConfig } from "./particles.js";
 /**
  * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
@@ -24,6 +25,7 @@ export function createParticleDirector(options = {}) {
         bursts.push({ seq: nextSeq++, config: structuredClone(config), count: wanted,
             ...(blending === undefined ? {} : { blending }),
             ...(emitterId === undefined ? {} : { emitterId }),
+            priority: Number.isFinite(attachOptions?.priority) ? attachOptions.priority : 0,
             ...(attachOptions === undefined ? {} : { options: structuredClone(attachOptions) }) });
         notify();
     }
@@ -64,6 +66,20 @@ export function createParticleDirector(options = {}) {
             const { id: _, config, ...options } = spec;
             queue(config, count, spec.blending, id, options);
         },
+        play(name, request) {
+            const effect = resolveEffect(name, request);
+            const follow = request?.follow ?? effect.options.follow;
+            queue(effect.config, effect.burst, effect.blending, undefined, { ...effect.options, ...(follow === undefined ? {} : { follow }) });
+        },
+        attachEffect(id, name, request) {
+            const effect = resolveEffect(name, request);
+            if (!emitters.has(id) && emitters.size >= maxEmitters)
+                throw new RangeError(`Particle emitter capacity ${maxEmitters} exceeded by ${id}`);
+            const follow = request?.follow ?? effect.options.follow;
+            emitters.set(id, { id, config: effect.config, ...effect.options, ...(follow === undefined ? {} : { follow }) });
+            notify();
+        },
+        effectNames,
         reportEvents(id, next) {
             for (let i = 0, n = Math.min(next.length, maxEvents - events.length); i < n; i++) {
                 events.push({ ...structuredClone(next[i]), emitterId: id });
@@ -129,6 +145,8 @@ export function validateParticleAttachOptions(value) {
         errors.push("space must be world or local");
     if (options.active !== undefined && typeof options.active !== "boolean")
         errors.push("active must be boolean");
+    if (options.priority !== undefined && (typeof options.priority !== "number" || !Number.isFinite(options.priority)))
+        errors.push("priority must be a finite number");
     const output = (render, blending, prefix) => {
         if (blending !== undefined && blending !== "normal" && blending !== "additive")
             errors.push(`${prefix}blending must be normal or additive`);

package/dist/world/authoredSimulation.js

@@ -89,7 +89,13 @@ export function createAuthoredSimulation(options) {
             const previous = config.emitters?.find((entry) => entry.id === emitter.id);
             if (emitterIds.includes(id) && JSON.stringify(previous) === JSON.stringify(emitter))
                 continue;
-            options.particles?.attach(id, { ...emitter.config, position: [emitter.position.x, emitter.position.y, emitter.position.z] }, { ...emitter.options, ...(emitter.fireAreaId === undefined ? {} : { active: emitter.options?.active !== false && nextFires.get(emitter.fireAreaId).burning > 0 }) });
+            const position = [emitter.position.x, emitter.position.y, emitter.position.z];
+            const fire = emitter.fireAreaId === undefined ? undefined : { active: emitter.options?.active !== false && nextFires.get(emitter.fireAreaId).burning > 0 };
+            const request = { position, options: { ...emitter.options, ...(fire ?? {}) } };
+            if (emitter.effect !== undefined)
+                options.particles?.attachEffect(id, emitter.effect, request);
+            else
+                options.particles?.attach(id, { ...emitter.config, position }, request.options);
         }
         emitterIds = nextEmitterIds;
         document = nextDocument;

package/dist/world/captureCamera.d.ts

@@ -0,0 +1,30 @@
+import type { CameraRigKind } from "../game/playableGame.js";
+import type { CameraRigConfig } from "../runtime/cameraDirector.js";
+/**
+ * Per-session capture-camera override — the harness counterpart of `?cam=`/`?look=`, and the same
+ * install-style seam as `world/spawnOverride`: the runner installs one, the shell reads it, nothing
+ * changes until one is installed.
+ *
+ * It exists because a game that owns its camera wins by other routes: a static `camera` config
+ * swapped by the harness only reaches the rig until the game selects its own rig at runtime
+ * (`ctx.camera.setRig`, a persisted settings camera, a director cinematic), and the capture then
+ * silently photographs the game's camera. This override is read above every one of those, so a
+ * framed capture stays framed; a game's own camera is untouched the moment the page loads without
+ * the param.
+ */
+export interface CaptureCameraOverride {
+    kind: CameraRigKind;
+    config: CameraRigConfig;
+}
+/**
+ * Install (or, with `null`, clear) the capture camera. Idempotent; last write wins. It outranks the
+ * game's static camera config and any runtime `ctx.camera` rig selection, and it is never saved —
+ * it is a property of this capture session, not of the game.
+ *
+ * @capability capture force a framed capture camera over a game that owns its camera
+ */
+export declare function installCaptureCamera(override: CaptureCameraOverride | null): void;
+/** Clear any installed capture camera. */
+export declare function clearCaptureCamera(): void;
+/** The installed capture camera, or `null` when the game's own camera should render. */
+export declare function readCaptureCamera(): CaptureCameraOverride | null;

package/dist/world/captureCamera.js

@@ -0,0 +1,19 @@
+let installed = null;
+/**
+ * Install (or, with `null`, clear) the capture camera. Idempotent; last write wins. It outranks the
+ * game's static camera config and any runtime `ctx.camera` rig selection, and it is never saved —
+ * it is a property of this capture session, not of the game.
+ *
+ * @capability capture force a framed capture camera over a game that owns its camera
+ */
+export function installCaptureCamera(override) {
+    installed = override;
+}
+/** Clear any installed capture camera. */
+export function clearCaptureCamera() {
+    installed = null;
+}
+/** The installed capture camera, or `null` when the game's own camera should render. */
+export function readCaptureCamera() {
+    return installed;
+}

package/dist/world/features.d.ts

@@ -70,16 +70,20 @@ export interface TerrainDetailConfig {
 }
 /**
  * PBR map URLs for a real ground texture — the same shape
- * `buildMaterialCatalog({ basePath }).resolve(id)!.maps` from `@jgengine/assets` returns. Kept
- * dependency-free here so `core` never imports the assets package; any URLs (pulled maps, a CDN, a
- * data URI) satisfy it. Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
+ * `libraryTerrainMaterial(name).maps` from `@jgengine/assets` returns. Kept dependency-free here so
+ * `core` never imports the assets package; any URLs (pulled maps, a CDN, a data URI) satisfy it.
+ * Omitted roughness keeps the terrain scalar; omitted AO skips occlusion sampling.
  */
 export interface TerrainMaterialMaps {
     color: string;
     normal: string;
     roughness?: string;
     ao?: string;
-    displacement: string;
+    /**
+     * Height map for callers that displace geometry themselves. The terrain detail shader never
+     * samples it, so pass the URL only when the pulled set actually ships one — never invent it.
+     */
+    displacement?: string;
 }
 /**
  * Real PBR texture applied over the ground surface — the seam that lets a game put a
@@ -102,6 +106,13 @@ export interface TerrainDetailMaterialConfig {
      * hand-tinted world wants from a stock PBR set.
      */
     tint?: number;
+    /**
+     * What a failed map load does. Scanned maps are pulled by a game's asset step, not committed, so a
+     * checkout without them looks exactly like a broken one. `"procedural"` (default) keeps the
+     * authored procedural ground and logs one warning naming the map; `"fail"` hands the error to the
+     * presentation retry screen, which is what a view that cannot render without the scan asks for.
+     */
+    missing?: "procedural" | "fail";
 }
 export interface TerrainFlattenMask {
     center: EnvironmentVec2;

package/dist/world/terrain.d.ts

@@ -201,6 +201,7 @@ export interface ResolvedTerrainDetailMaterial {
     repeat: number;
     strength: number;
     tint: number;
+    missing: "procedural" | "fail";
 }
 /** A {@link TerrainDetailConfig} with every field resolved to a concrete value — the shape the shell's detail material consumes. */
 export type ResolvedTerrainDetail = Required<Omit<TerrainDetailConfig, "waterLevel" | "material" | "sweeps">> & {

package/dist/world/terrain.js

@@ -487,6 +487,7 @@ const IMPLICIT_TERRAIN_DETAIL = {
 const DEFAULT_TERRAIN_MATERIAL_REPEAT = 4;
 const DEFAULT_TERRAIN_MATERIAL_STRENGTH = 1;
 const DEFAULT_TERRAIN_MATERIAL_TINT = 1;
+const DEFAULT_TERRAIN_MATERIAL_MISSING = "procedural";
 /** Sand-band level for a terrain with no water: far below any ground, so no beach is painted. */
 const NO_WATER_SAND_LEVEL = -1e6;
 /** Fill a `TerrainDetailConfig` with defaults; `waterLevel` falls back to the terrain's own water level,
@@ -520,6 +521,7 @@ export function resolveTerrainDetail(config, terrainWaterLevel) {
                     repeat: config.material.repeat ?? DEFAULT_TERRAIN_MATERIAL_REPEAT,
                     tint: clamp01(config.material.tint ?? DEFAULT_TERRAIN_MATERIAL_TINT),
                     strength: clamp01(config.material.strength ?? DEFAULT_TERRAIN_MATERIAL_STRENGTH),
+                    missing: config.material.missing ?? DEFAULT_TERRAIN_MATERIAL_MISSING,
                 },
             }),
     };

package/dist/world.d.ts

@@ -1,6 +1,7 @@
-export { type HeatConfig, type HeatGain, type HeatLevelDef, type HeatState } from "./ai/heatSystem.js";
+export { type HeatConfig, type HeatGain, type HeatLevelDef, type HeatPoint, type HeatState } from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, type InterestCensus, type InterestCensusAccumulator, type InterestGateInput, type InterestGateState, type InterestGateStep, type InterestSchedulerConfig, type InterestState, type InterestTier, } from "./ai/interestScheduler.js";
 export { type Job, type JobDef, type JobReport } from "./ai/jobBoard.js";
+export { DEFAULT_POLICE_TIERS, DEFAULT_POLICE_TUNING, createPoliceResponse, policeRoadsFromLaneGraph, type PoliceLaneHit, type PoliceResponse, type PoliceResponseConfig, type PoliceResponseKind, type PoliceResponseState, type PoliceRoadblockSite, type PoliceRoads, type PoliceRoadsOptions, type PoliceSearchArea, type PoliceSighting, type PoliceStats, type PoliceStep, type PoliceTickContext, type PoliceTier, type PoliceTuning, type PoliceWitness, } from "./ai/policeResponse.js";
 export { createRvoCrowd, type RvoAgentSpec, type RvoAgentView, type RvoCrowd, type RvoCrowdOptions, type RvoSnapshot, type RvoTunables, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, type SpawnDirectorConfig, type SpawnDirectorState, type SpawnEntry, type SpawnRequest, type WaveManifest, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, type AcquisitionEnvelope, type AcquisitionPolicy, type AcquisitionResult, type AcquisitionRetention, type TargetAcquirer, } from "./ai/targetAcquisition.js";

package/dist/world.js

@@ -1,6 +1,7 @@
 export {} from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, } from "./ai/interestScheduler.js";
 export {} from "./ai/jobBoard.js";
+export { DEFAULT_POLICE_TIERS, DEFAULT_POLICE_TUNING, createPoliceResponse, policeRoadsFromLaneGraph, } from "./ai/policeResponse.js";
 export { createRvoCrowd, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, } from "./ai/targetAcquisition.js";

package/package.json

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

package/skills/jgengine-combat/SKILL.md

@@ -44,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

@@ -73,6 +73,25 @@ Validate generated quest catalogs with `validateQuestCatalog` (`game/questCatalo
 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).
@@ -102,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
@@ -151,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