@jgengine/core 0.12.0 → 0.13.0

package/dist/world/streets.js

@@ -197,3 +197,221 @@ export function sidewalkPoint(road, side, fraction) {
     const along = Math.max(0, Math.min(1, fraction)) * pathLength(path);
     return pointAlong(path, along).point;
 }
+/**
+ * The two curb lines of a road — offset polylines running along the outer edge of the asphalt on
+ * each side. Mesh these with a thin darker ribbon to give the road a curb/edge strip instead of a
+ * hard asphalt-to-terrain seam. `inset` (default 0) nudges the line inward off the raw edge so the
+ * strip straddles the border.
+ */
+export function curbPaths(road, inset = 0) {
+    const edge = road.width / 2 - inset;
+    return [offsetPath(road.path, edge), offsetPath(road.path, -edge)];
+}
+const EPS = 1e-6;
+/** Intersection point of segments a→b and c→d, or null when they don't cross (endpoints included). */
+function segmentIntersection(a, b, c, d) {
+    const r0 = b[0] - a[0];
+    const r1 = b[1] - a[1];
+    const s0 = d[0] - c[0];
+    const s1 = d[1] - c[1];
+    const denom = r0 * s1 - r1 * s0;
+    if (Math.abs(denom) < EPS)
+        return null; // parallel or degenerate
+    const t = ((c[0] - a[0]) * s1 - (c[1] - a[1]) * s0) / denom;
+    const u = ((c[0] - a[0]) * r1 - (c[1] - a[1]) * r0) / denom;
+    if (t < -EPS || t > 1 + EPS || u < -EPS || u > 1 + EPS)
+        return null;
+    return [a[0] + r0 * t, a[1] + r1 * t];
+}
+function unit(dx, dz) {
+    const len = Math.hypot(dx, dz) || 1;
+    return [dx / len, dz / len];
+}
+/**
+ * Add the arms a road contributes at junction point `p`: the road continues past `p` in each
+ * direction that still has centerline beyond it, so a mid-path crossing yields two opposing arms
+ * and a road that terminates at `p` (a T-junction) yields only the one inward arm.
+ */
+function armsAt(path, p, width, roadIndex) {
+    const arms = [];
+    // Nearest vertex "before" (toward path start) and "after" (toward path end) of p.
+    // Walk the path measuring where p falls; use the two adjacent tangents.
+    let hitSeg = -1;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const a = path[i];
+        const b = path[i + 1];
+        const abx = b[0] - a[0];
+        const abz = b[1] - a[1];
+        const lengthSq = abx * abx + abz * abz;
+        const t = lengthSq === 0 ? 0 : ((p[0] - a[0]) * abx + (p[1] - a[1]) * abz) / lengthSq;
+        const px = a[0] + abx * Math.max(0, Math.min(1, t));
+        const pz = a[1] + abz * Math.max(0, Math.min(1, t));
+        if (Math.hypot(p[0] - px, p[1] - pz) < 1e-3) {
+            hitSeg = i;
+            break;
+        }
+    }
+    if (hitSeg < 0)
+        return arms;
+    const a = path[hitSeg];
+    const b = path[hitSeg + 1];
+    const forward = unit(b[0] - a[0], b[1] - a[1]);
+    const atStart = Math.hypot(p[0] - path[0][0], p[1] - path[0][1]) < 1e-3;
+    const atEnd = Math.hypot(p[0] - path[path.length - 1][0], p[1] - path[path.length - 1][1]) < 1e-3;
+    // Arm toward path end exists unless p sits exactly at the end.
+    if (!atEnd)
+        arms.push({ roadIndex, direction: forward, width });
+    // Arm toward path start exists unless p sits exactly at the start.
+    if (!atStart)
+        arms.push({ roadIndex, direction: [-forward[0], -forward[1]], width });
+    return arms;
+}
+function mergeArm(arms, arm) {
+    for (const existing of arms) {
+        if (existing.roadIndex === arm.roadIndex) {
+            const dot = existing.direction[0] * arm.direction[0] + existing.direction[1] * arm.direction[1];
+            if (dot > 0.985)
+                return; // same road, near-identical direction — already have this arm
+        }
+    }
+    arms.push(arm);
+}
+/**
+ * Detect welded intersections across a set of roads: wherever two road centerlines cross (or a road
+ * terminates on another) within the same elevation band, emit a {@link RoadJunction} whose patch
+ * covers the crossing ribbons. Nearby crossings merge into one junction. Deterministic and bounded —
+ * O(roads² · segments²) with a `maxJunctions` cap — so a scene builds its intersections once.
+ */
+export function findRoadJunctions(roads, options = {}) {
+    const elevationBand = options.elevationBand ?? 0.12;
+    const mergeDistance = options.mergeDistance ?? 6;
+    const maxJunctions = options.maxJunctions ?? 256;
+    const radiusScale = options.radiusScale ?? 1.15;
+    const mergeSq = mergeDistance * mergeDistance;
+    const candidates = [];
+    const emit = (p, ri, ci) => {
+        if (candidates.length >= maxJunctions && findNear(candidates, p, mergeSq) === null)
+            return;
+        const roadA = roads[ri];
+        const roadB = roads[ci];
+        const half = Math.max(roadA.width, roadB.width) / 2;
+        const radius = half * radiusScale;
+        const elevation = Math.max(roadA.elevation, roadB.elevation);
+        const wider = roadA.width >= roadB.width ? roadA : roadB;
+        const near = findNear(candidates, p, mergeSq);
+        const arms = [
+            ...armsAt(roadA.path, p, roadA.width, ri),
+            ...armsAt(roadB.path, p, roadB.width, ci),
+        ];
+        if (near === null) {
+            const merged = [];
+            for (const arm of arms)
+                mergeArm(merged, arm);
+            candidates.push({
+                x: p[0],
+                z: p[1],
+                radius,
+                elevation,
+                color: wider.color,
+                colorWidth: wider.width,
+                arms: merged,
+            });
+        }
+        else {
+            near.radius = Math.max(near.radius, radius);
+            near.elevation = Math.max(near.elevation, elevation);
+            if (wider.width > near.colorWidth) {
+                near.color = wider.color;
+                near.colorWidth = wider.width;
+            }
+            for (const arm of arms)
+                mergeArm(near.arms, arm);
+        }
+    };
+    for (let i = 0; i < roads.length; i += 1) {
+        const roadA = roads[i];
+        if (roadA.path.length < 2)
+            continue;
+        for (let j = i + 1; j < roads.length; j += 1) {
+            const roadB = roads[j];
+            if (roadB.path.length < 2)
+                continue;
+            if (Math.abs(roadA.elevation - roadB.elevation) > elevationBand)
+                continue;
+            for (let si = 0; si < roadA.path.length - 1; si += 1) {
+                for (let sj = 0; sj < roadB.path.length - 1; sj += 1) {
+                    const hit = segmentIntersection(roadA.path[si], roadA.path[si + 1], roadB.path[sj], roadB.path[sj + 1]);
+                    if (hit !== null)
+                        emit(hit, i, j);
+                }
+            }
+        }
+    }
+    return candidates.map((c) => ({
+        center: [c.x, c.z],
+        radius: c.radius,
+        elevation: c.elevation,
+        color: c.color,
+        approaches: c.arms.map((arm) => ({ direction: arm.direction, width: arm.width })),
+    }));
+}
+function findNear(candidates, p, mergeSq) {
+    for (const c of candidates) {
+        const dx = c.x - p[0];
+        const dz = c.z - p[1];
+        if (dx * dx + dz * dz <= mergeSq)
+            return c;
+    }
+    return null;
+}
+/** Circular marking-exclusion zones for the junctions, sized to hide the center line under each patch. */
+export function junctionExclusions(junctions, pad = 0.5) {
+    return junctions.map((j) => ({ center: j.center, radius: j.radius + pad }));
+}
+/**
+ * Data-driven junction entry markings: a stop-line bar across each approach and a band of crosswalk
+ * bars just outside the welded patch. Each returned polyline is a thin centerline meant to be meshed
+ * with {@link buildRoadRibbon} at a small width. Fully skippable per-feature via the options.
+ */
+export function junctionMarkings(junction, options = {}) {
+    const wantStop = options.stopLines ?? true;
+    const wantCross = options.crosswalks ?? true;
+    const barCount = Math.max(1, Math.floor(options.crosswalkBars ?? 5));
+    const gap = options.gap ?? 0.6;
+    const depth = options.crosswalkDepth ?? 2.4;
+    const [cx, cz] = junction.center;
+    const stopLines = [];
+    const crosswalkBars = [];
+    for (const approach of junction.approaches) {
+        const [dx, dz] = approach.direction;
+        // Across-the-road axis, perpendicular to travel.
+        const ax = -dz;
+        const az = dx;
+        const half = approach.width / 2;
+        const stopDist = junction.radius + gap;
+        if (wantStop) {
+            const px = cx + dx * stopDist;
+            const pz = cz + dz * stopDist;
+            stopLines.push([
+                [px + ax * half, pz + az * half],
+                [px - ax * half, pz - az * half],
+            ]);
+        }
+        if (wantCross) {
+            const near = stopDist + 0.4;
+            const barWidth = half * 2 * 0.16;
+            const usable = half * 2 - barWidth;
+            for (let b = 0; b < barCount; b += 1) {
+                const frac = barCount === 1 ? 0 : b / (barCount - 1) - 0.5;
+                const offset = frac * usable;
+                const bx = cx + ax * offset;
+                const bz = cz + az * offset;
+                crosswalkBars.push([
+                    [bx + dx * near, bz + dz * near],
+                    [bx + dx * (near + depth), bz + dz * (near + depth)],
+                ]);
+            }
+        }
+    }
+    return { stopLines, crosswalkBars };
+}

package/dist/world/terrain.d.ts

@@ -1,4 +1,4 @@
-import type { BiomeBand, EnvironmentWorldFeature, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, TerrainMaterialMaps, WorldBounds, WorldFeature } from "./features.js";
+import type { BiomeBand, EnvironmentWorldFeature, RoadEnvironmentDescriptor, TerrainDetailConfig, TerrainEnvironmentConfig, TerrainEnvironmentDescriptor, TerrainIslandDescriptor, TerrainMaterial, TerrainMaterialMaps, WorldBounds, WorldFeature } from "./features.js";
 import type { AvoidZone } from "./geometry.js";
 import { type TerrainPathProfile } from "./pathTerrain.js";
 import type { TerraformSnapshot } from "./terraform.js";
@@ -107,6 +107,25 @@ export declare function flattenFieldAround(base: TerrainField, zones: readonly A
  * through the one seam every consumer already reads.
   * @internal
   */
+/**
+ * Drapes each `road()` ribbon's `elevation` onto the ground so a body standing on a road snaps to the
+ * road *surface* the renderer draws (`sampleHeight + elevation`), not the bare terrain beneath it. Without
+ * this the ground field and {@link RoadRibbons}/{@link CityRenderer} disagree by `elevation` per road, and
+ * anything grounded on a road — the player, NPCs, spawns via `groundHeightAt` — sinks by that offset into
+ * the asphalt. Overlapping ribbons (intersections) take the highest lift. Only `sampleHeight` is draped:
+ * the road ribbons are flat, so `sampleNormal` stays the smooth terrain normal — draping it too would spoof
+ * a near-vertical slope at every curb edge and trip slope-slide.
+ * @internal — reached through `environment({ roads })`; not called directly by games.
+ */
+export declare function roadDrapedField(base: TerrainField, roads: readonly RoadEnvironmentDescriptor[]): TerrainField;
+/**
+ * The full ground field for an environment world: base `terrain` composed with any `islands`, then
+ * any authored `sculpt` snapshot, then any `clearings`, then any `roads` draped on top — so an
+ * editor-sculpted heightfield drives both the rendered mesh and player collision, gameplay spots
+ * stay level, and anything grounded on a road stands on the drawn asphalt rather than the bare
+ * terrain beneath it, through the one seam every consumer already reads.
+ * @internal
+ */
 export declare function resolveEnvironmentField(feature: EnvironmentWorldFeature): TerrainField;
 export interface TerrainSlopeSample {
     /** Unit XZ direction pointing downhill; `[0, 0]` on level ground. */

package/dist/world/terrain.js

@@ -1,5 +1,5 @@
 import { withPathProfiles } from "./pathTerrain.js";
-import { nearestOnPath } from "./roads.js";
+import { isOnRoad, nearestOnPath } from "./roads.js";
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -308,15 +308,54 @@ export function flattenFieldAround(base, zones) {
  * through the one seam every consumer already reads.
   * @internal
   */
+/**
+ * Drapes each `road()` ribbon's `elevation` onto the ground so a body standing on a road snaps to the
+ * road *surface* the renderer draws (`sampleHeight + elevation`), not the bare terrain beneath it. Without
+ * this the ground field and {@link RoadRibbons}/{@link CityRenderer} disagree by `elevation` per road, and
+ * anything grounded on a road — the player, NPCs, spawns via `groundHeightAt` — sinks by that offset into
+ * the asphalt. Overlapping ribbons (intersections) take the highest lift. Only `sampleHeight` is draped:
+ * the road ribbons are flat, so `sampleNormal` stays the smooth terrain normal — draping it too would spoof
+ * a near-vertical slope at every curb edge and trip slope-slide.
+ * @internal — reached through `environment({ roads })`; not called directly by games.
+ */
+export function roadDrapedField(base, roads) {
+    if (roads.length === 0)
+        return base;
+    const sampleHeight = (x, z) => {
+        let lift = 0;
+        for (const road of roads) {
+            if (road.elevation > lift && isOnRoad(road.path, road.width, x, z))
+                lift = road.elevation;
+        }
+        return base.sampleHeight(x, z) + lift;
+    };
+    return {
+        sampleHeight,
+        sampleNormal: base.sampleNormal,
+        ...(base.bounds === undefined ? {} : { bounds: base.bounds }),
+        ...(base.waterLevel === undefined ? {} : { waterLevel: base.waterLevel }),
+    };
+}
+/**
+ * The full ground field for an environment world: base `terrain` composed with any `islands`, then
+ * any authored `sculpt` snapshot, then any `clearings`, then any `roads` draped on top — so an
+ * editor-sculpted heightfield drives both the rendered mesh and player collision, gameplay spots
+ * stay level, and anything grounded on a road stands on the drawn asphalt rather than the bare
+ * terrain beneath it, through the one seam every consumer already reads.
+ * @internal
+ */
 export function resolveEnvironmentField(feature) {
     const base = feature.terrain === undefined ? null : resolveTerrainField(feature.terrain);
     const composed = feature.islands === undefined || feature.islands.length === 0
         ? base ?? flatField()
         : composeIslandFields(base, feature.islands);
     const sculpted = feature.sculpt === undefined ? composed : sculptedField(composed, feature.sculpt);
-    return feature.clearings === undefined || feature.clearings.length === 0
+    const cleared = feature.clearings === undefined || feature.clearings.length === 0
         ? sculpted
         : flattenFieldAround(sculpted, feature.clearings);
+    return feature.roads === undefined || feature.roads.length === 0
+        ? cleared
+        : roadDrapedField(cleared, feature.roads);
 }
 /** Local slope from the field's normal — the input for gravity-roll, ski acceleration, and slide checks (#284.6).
  * @internal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "jgengine core — agent-first game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/SKILL.md

@@ -42,6 +42,7 @@ World content routes editor-first: any request that adds, moves, restyles, or re
 
 Within each selected domain:
 
+0. Fastest start for a common composition: `npx jgengine recipe <name>` prints a vetted, SDK-typechecked snippet (imports + wired code) for `combat-loop`, `boss-telegraph`, `loot`, `quest`, `coop-presence`, `third-person-camera`; `npx jgengine recipe` lists them. Copy that instead of reconning per-file.
 1. Search `capabilities.md` by intent; it maps needs to imports.
 2. Open `api.md` only when exact signatures or export inventory are needed.
 3. Open the linked reference only for a deeper recipe or trap.

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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -38,7 +38,7 @@
 - `WorldFeature` (type): type WorldFeature = | PlaceWorldFeature | ({ kind: "biomes" } & BiomesWorldConfig) | ({ kind: "voxel" } & VoxelWorldConfig) | ({ kind: "plots" } & PlotsWorldConfig) | ({ kind: "tilemap" } & TilemapWorldConfig) | EnvironmentWorldFeature | { kind: "flat" } — A declared world shape passed to `defineGame`. The preferred model is the place feature from `world()` (`@jgengine/core/world/place`): substrate + laws, with all dressing authored in the editor. The remaining members — biomes, voxel grid, plots, tilemap, environment, flat — are the legacy code-declared shapes kept for existing games.
 - `auditManifest` (function): function auditManifest(manifest: SceneOwnershipManifest): OwnershipDiagnostic[] — Audit every declaration in a manifest, keying diagnostics by each object's provenance id. An empty result means the manifest declares all of its content cleanly — every object is authored, generated, bakeable, or a reasoned runtime/transient object.
 - `biomes` (function): function biomes(config: BiomesWorldConfig): WorldFeature — Declares a biome-painted world — the whole-world alternative to a single `environment()` terrain.
-- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style.
+- `building` (function): function building(config: BuildingEnvironmentConfig = {}): BuildingEnvironmentDescriptor — Declares a cluster of procedurally-massed buildings for `environment()` — count, footprint, stories, style. Pass `along` to line road frontage instead of gridding around `position`.
 - `classifyOwnership` (function): function classifyOwnership(declaration: SceneOwnershipDeclaration): OwnershipVerdict — Resolve one declaration into a single boundary verdict.
 - `collectOwnershipDiagnostics` (function): function collectOwnershipDiagnostics(entries: Iterable<readonly [string, SceneOwnershipDeclaration]>): OwnershipDiagnostic[] — Audit a keyed set of declarations and return one diagnostic per object that breaks the boundary contract (a `reject` verdict carrying a `violation`). Deterministic: diagnostics come back in the iteration order of `entries`.
 - `contextVerb` (function): function contextVerb(label: string, command: string, args?: Record<string, unknown>): ContextVerb — Builds a {@link ContextVerb} for a right-click menu entry.
@@ -209,11 +209,18 @@
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
+## @jgengine/core/devtools/urlFlags
+
+- `readUrlFlag` (function): function readUrlFlag(param: string): boolean — True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`).
+- `readUrlParam` (function): function readUrlParam(param: string): string | null — The current query value of `param`, or null when absent (or no DOM).
+- `subscribeUrlChange` (function): function subscribeUrlChange(listener: () => void): () => void — Fires `listener` whenever the query string may have changed out from under a flag — browser back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+- `writeUrlParam` (function): function writeUrlParam(param: string, value: string | null): void — Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with `history.replaceState` so the rest of the query and the hash survive and no history entry is pushed. No-ops without a DOM, and skips the write when the URL already matches.
+
 ## @jgengine/core/meta/changelog
 
 - `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.12.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.13.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -276,7 +283,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 - `createGameContext` (function): function createGameContext<TAssetRef extends ModelAssetRef, TMultiplayer>(options: GameContextOptions<TAssetRef, TMultiplayer>): GameContext — ⚠ undocumented
 
@@ -307,7 +314,7 @@
 - `SceneObjectContext` (interface): interface SceneObjectContext extends ObjectStore — ⚠ undocumented
 - `SceneWorldItemContext` (interface): interface SceneWorldItemContext — ⚠ undocumented
 - `TelegraphInput` (interface): interface TelegraphInput — ⚠ undocumented
-- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst; `from`/`to` accept an instance id or a world point, `color` is a `0xRRGGBB` tint, and `durationMs` defaults per `kind`.
+- `VfxInput` (interface): interface VfxInput — Request a transient spell/ability VFX burst. The easy path is a named `preset` — `vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with no color or archetype tuning; `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` and the rest of {@link vfxPresets} likewise just work. `from`/`to` accept an instance id (the shell follows its live pose) or a fixed world point. Anything you also pass — `kind`, `color` (`0xRRGGBB`), `radius`, `durationMs` — overrides the preset; supply `kind` + `color` yourself for a fully custom burst with no preset. `durationMs` defaults per `kind`.
 - `WorldItemPickupResult` (type): type WorldItemPickupResult = | { status: "ok"; record: WorldItemRecord } | { status: "rejected"; reason: string } — ⚠ undocumented
 
 ## @jgengine/core/runtime/gameRuntime
@@ -322,6 +329,7 @@
 
 ## @jgengine/core/runtime/headlessRunner
 
+- `HeadlessCommandInterface` (interface): interface HeadlessCommandInterface — Canvas-free command/intent surface for {@link HeadlessRunner} — invoke a game's registered UI commands and read the resulting reactive state off `ctx`.
 - `HeadlessInput` (interface): interface HeadlessInput — One step's worth of player intent handed to {@link HeadlessRunner.step} — the held-action set and pointer state the shell would otherwise publish from the browser each frame.
 - `HeadlessRunner` (interface): interface HeadlessRunner — A renderer-free driver for a game loop: builds a {@link GameContext} from a {@link GameDefinition}, runs the init hooks, then advances the simulation one step at a time from injected input. No React, R3F, or three.js — the whole play path (time, input, `onTick`, behaviour nav, optional player movement) runs from `core` primitives alone, so a non-React host (a server tick, a test, a CLI replay) can play a real game and read its world snapshot. The shell's FrameDriver is one such driver bolted to `useFrame`; this is the same step distilled out of the render tree.
 - `HeadlessRunnerOptions` (interface): interface HeadlessRunnerOptions<TAssetRef extends ModelAssetRef, TMultiplayer> — ⚠ undocumented

package/skills/jgengine-combat/SKILL.md

@@ -14,7 +14,21 @@ Search [capabilities.md](capabilities.md), then use [api.md](api.md) for signatu
 Existing projects keep their resource state and follow the
 [portable stat-pool recipe](recipes/portable-stat-pools.md). Adapt the caller's
 store through `StatPoolAccess`; do not require `StatValueMap`, `GameContext`, or
-a parallel entity store.
+a parallel entity store. To bolt firing onto an existing game, compose
+`createWeaponRuntime` (cadence + magazine + the caller's own raycast + portable
+`resolveDamageHit`) per the
+[portable weapon-plumbing recipe](recipes/portable-weapon-plumbing.md); never add
+a default gun or FPS kit.
+
+Damage commitment accepts the same structural pool adapter while the matchup,
+receiver, interceptor, and status stages remain pure. Follow the
+[portable damage/effects recipe](recipes/portable-damage-effects.md) to compose
+them over an existing store, clock, RNG, spatial index, and death flow.
+
+Closure-backed magazines and stat modifiers expose plain snapshot/restore
+state for caller-owned saves, rollback, replay, and workers. Follow the
+[portable runtime-state recipe](recipes/portable-runtime-state.md); the caller
+keeps its clock, reserve state, schema, and authority.
 
 ## Canonical pipeline
 

package/skills/jgengine-combat/api.md

@@ -28,6 +28,7 @@
 - `DEFAULT_FIRE_PULSE_SECONDS` (const): const DEFAULT_FIRE_PULSE_SECONDS: 0.12 — Default `RenderCueTuning.firePulseSeconds`.
 - `DEFAULT_HIT_PULSE_SECONDS` (const): const DEFAULT_HIT_PULSE_SECONDS: 0.2 — Default `RenderCueTuning.hitPulseSeconds`.
 - `DEFAULT_RENDER_CUES` (const): const DEFAULT_RENDER_CUES: Readonly<EntityRenderCues> — Neutral starting cue set: idle, unarmed, undamaged.
+- `DEFAULT_VFX_PRESET` (const): const DEFAULT_VFX_PRESET: VfxPresetName — The fallback flavor used when a `vfx()` call names an unknown preset — so a typo still shows a spark instead of nothing.
 - `DamageChannelId` (type): type DamageChannelId = string — Caller-owned id for a damage channel — `"fire"`, `"ballistic"`, `"physical"`, `"corrosive"`. The engine never branches on the value; a channel is whatever a game's data declares.
 - `DamageClampConfig` (interface): interface DamageClampConfig — Caller data for a flat per-hit damage cap.
 - `DamageContext` (interface): interface DamageContext — The facts a received-damage modifier predicates over: the incoming `channel`, who dealt it, the statuses the target currently carries, and any caller tags. All caller-owned strings; the engine never assigns meaning to a channel, source, status, or tag.
@@ -50,6 +51,8 @@
 - `EntityRenderCues` (interface): interface EntityRenderCues — Per-entity render cues: the motion/animation signal a custom `renderEntity` or first-person viewmodel component needs to drive gait, muzzle flash, reload poses, and hit reactions — without diffing the parent group's position itself or reading a game-side module map for attack timing.
 - `EventMeter` (interface): interface EventMeter — ⚠ undocumented
 - `EventMeterFeedResult` (interface): interface EventMeterFeedResult — ⚠ undocumented
+- `FireCadence` (interface): interface FireCadence — A minimal minimum-interval rate gate for a repeated action — weapon fire, ability spam, any "no faster than N per second" rule. Deterministic and serializable: its whole state is the elapsed time since the last action, exposed via {@link FireCadence.elapsedMs}.
+- `FireCadenceConfig` (interface): interface FireCadenceConfig — Tuning for {@link createFireCadence}: the minimum interval between actions and whether it starts ready.
 - `FrameRange` (interface): interface FrameRange — ⚠ undocumented
 - `HitReactionConfig` (interface): interface HitReactionConfig — ⚠ undocumented
 - `ImmunityWindow` (interface): interface ImmunityWindow — A per-target timed immunity policy: an interceptor plus grant/query/serialize controls, toggled by transitions.
@@ -58,7 +61,9 @@
 - `InterceptRecord` (interface): interface InterceptRecord — One row of provenance: which interceptor acted, what it decided, and the amount before/after it acted.
 - `MAX_INTERCEPT_STEPS` (const): const MAX_INTERCEPT_STEPS: 256 — Upper bound on interceptor evaluations for a single resolution; guards against runaway `split`/`redirect` loops.
 - `Magazine` (interface): interface Magazine — A per-weapon magazine: discrete loaded rounds, a timed reload that refills from a reserve pool, and the reserve-pool interaction itself — the primitive that replaces hand-rolling mag size, reload delay, and reserve bookkeeping per game (#536.2).
+- `MagazineConfig` (interface): interface MagazineConfig — Tuning for `createMagazine`: mag capacity, reload delay, and where reserve ammo is drawn from.
 - `MagazineReserve` (interface): interface MagazineReserve — Draws ammo for a `Magazine`'s reload from wherever the reserve pool actually lives.
+- `MagazineSnapshot` (interface): interface MagazineSnapshot — Complete serializable state for a {@link Magazine}; `reserve: null` means infinite reserve.
 - `MatchupOutputs` (interface): interface MatchupOutputs — The independent, typed outputs a channel-vs-trait matchup can scale. Every field is an optional multiplier that defaults to `1` (identity), so a matchup entry names only the axes it bends. `impact` scales the direct hit, `applyChance` the odds a status lands, `magnitude` and `duration` the applied status itself, and `extra` carries any further caller-defined scalar (knockback, stagger, heat) the engine forwards without interpreting.
 - `MeterAddResult` (interface): interface MeterAddResult — ⚠ undocumented
 - `ObjectRaycastHit` (interface): interface ObjectRaycastHit — ⚠ undocumented
@@ -95,6 +100,7 @@
 - `StatPoolInput` (interface): interface StatPoolInput — Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero.
 - `StatPoolPatch` (interface): interface StatPoolPatch — Partial update applied without mutating the previous pool.
 - `Stats` (interface): interface Stats<TStat extends string> — ⚠ undocumented
+- `StatsSnapshot` (interface): interface StatsSnapshot<TStat extends string> — Complete plain-data state for a {@link Stats} runtime.
 - `StatusApplicationOutcome` (interface): interface StatusApplicationOutcome — The result of one status application: the outcome, the resulting instance (if any), and the roll.
 - `StatusApplicationSpec` (interface): interface StatusApplicationSpec — A serializable, effect-agnostic description of a status a hit tries to apply: an opaque `status` id the game routes to its own effect/DoT pipeline, a base landing `chance`, and the duration/ticks/magnitude/attribution/stacking data the resolver needs. The engine never interprets `status` — it is a reference, not a built-in condition.
 - `StatusImmunity` (interface): interface StatusImmunity — Statuses a target cannot receive at all — the immunity half of application policy.
@@ -108,6 +114,12 @@
 - `ThresholdMark` (interface): interface ThresholdMark — Generic numeric threshold-crossing tracker (#931).
 - `ThresholdTracker` (interface): interface ThresholdTracker — A stateful crossing tracker over one numeric source.
 - `ThresholdTrackerSnapshot` (interface): interface ThresholdTrackerSnapshot — Serializable tracker state for save/load.
+- `VfxPreset` (interface): interface VfxPreset — A named visual flavor for a one-shot `combat.vfx` burst: the archetype (`kind`), a `0xRRGGBB` tint, and optional default `durationMs`/`radius`. Purely presentation — a preset never touches damage, range, or any authoritative value; it just answers "what does this attack look like" so a game does not hand-roll colors and archetypes.
+- `VfxPresetName` (type): type VfxPresetName = keyof typeof vfxPresets — A named key into {@link vfxPresets} (`"arrow" | "fireball" | "lightning" | "web" | "slash" | "shield" | "heal" | ...`).
+- `WeaponFireResult` (interface): interface WeaponFireResult<THit> — The result of a {@link WeaponRuntime.fire} attempt. On `"fired"`, `hits` is whatever the caller's raycast returned and `resolutions` holds the portable damage provenance for each hit that produced a {@link DamageHitInput}; on any blocked status both are empty and no round was spent.
+- `WeaponFireStatus` (type): type WeaponFireStatus = "fired" | "cooling" | "empty" | "reloading" — Why a {@link WeaponRuntime.fire} attempt resolved the way it did.
+- `WeaponRuntime` (interface): interface WeaponRuntime<TAim, THit> — A composed weapon fire controller: a {@link FireCadence} gate, an optional {@link Magazine}, the caller's raycast, and portable {@link resolveDamageHit} damage resolution wired together. The caller retains ownership of models, animations, muzzle flash, audio, input, camera, aiming, and the raycaster itself.
+- `WeaponRuntimeConfig` (interface): interface WeaponRuntimeConfig<TAim, THit> — Configuration for {@link createWeaponRuntime}. Everything time/ammo-related is plain data; the two callbacks are where the caller keeps ownership of aiming, its own raycaster/projectile query, and how a hit maps to damage. There is deliberately no default weapon, projectile, or damage table here — those are game content.
 - `activePhaseId` (function): function activePhaseId<TData>(state: EncounterState<TData>): string | null — The deepest active phase id — the completion cursor a HUD reads to label the current wave/phase — or null before start and once done.
 - `advanceCombo` (function): function advanceCombo(input: AdvanceComboInput): AdvanceComboResult — ⚠ undocumented
 - `advanceMotionCues` (function): function advanceMotionCues(cues: EntityRenderCues, speed: number, dt: number, tuning?: RenderCueTuning): EntityRenderCues — Advances `bobPhase` and decays `recoil` from a live `speed` sample (e.g. `groundSpeed(entity)`); leaves event-driven fields untouched.
@@ -133,9 +145,10 @@
 - `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`.
 - `createDownedState` (function): function createDownedState(config: DownedConfig): DownedState — A downed/bleed-out state that ticks toward death and that teammates can revive before the timer runs out.
-- `createEffectSystem` (function): function createEffectSystem(deps: EffectSystemDeps): EffectSystem — Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+- `createEffectSystem` (function): function createEffectSystem(deps: EffectSystemDeps): EffectSystem — Resolve direct or area resource effects through caller-owned stat pools, including ordered absorption, restoration, modifiers, and lethal context.
 - `createEncounterState` (function): function createEncounterState<TData>(config: EncounterConfig<TData>): EncounterState<TData> — Build the initial, serializable state for an encounter from its config. Deep-copies the authored phase tree (so later injection never mutates the config), verifies phase ids are unique, and leaves every node pending. Does not enter the first phase — call {@link startEncounter} for that.
 - `createEventMeter` (function): function createEventMeter(config: EventMeterConfig): EventMeter — A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shooters and fighters hand-roll.
+- `createFireCadence` (function): function createFireCadence(config: FireCadenceConfig): FireCadence — Build a {@link FireCadence} rate gate. Reach for this instead of hand-tracking a `lastFiredAt` timestamp and comparing against a fire interval per game.
 - `createImmunityWindow` (function): function createImmunityWindow(id = "immunity"): ImmunityWindow — A per-target immunity/invulnerability window as an ordinary damage policy — granted and cleared by state transitions (i-frames, phase invuln), rejecting damage while active. Deterministic (time is passed in) and serializable.
 - `createMagazine` (function): function createMagazine(config: MagazineConfig): Magazine — Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.
 - `createProjectileSystem` (function): function createProjectileSystem(deps: ProjectileSystemDeps): ProjectileSystem — Spawn and advance projectiles each frame, resolving travel, lifetime, and hits.
@@ -145,6 +158,7 @@
 - `createStatPool` (function): function createStatPool(input: StatPoolInput): StatPool — Normalize caller data into a complete plain-data pool.
 - `createStats` (function): function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat> — A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
 - `createThresholdTracker` (function): function createThresholdTracker(config: ThresholdCrossingConfig): ThresholdTracker — Track a numeric source against named thresholds and emit ordered crossing events with direction, hysteresis, once/repeat policy, and skipped-threshold handling. Deterministic and serializable; drives phase transitions, armor breaks, resource warnings, and any other threshold consumer.
+- `createWeaponRuntime` (function): function createWeaponRuntime<TAim, THit>(config: WeaponRuntimeConfig<TAim, THit>): WeaponRuntime<TAim, THit> — Compose a portable weapon fire controller from the existing generic primitives — a {@link FireCadence} gate, an optional {@link Magazine}, a caller-provided raycast, and portable {@link resolveDamageHit} damage resolution. No `GameContext`, entity store, renderer, or default weapon is involved; the caller owns aiming, its raycaster, and all presentation, and the result carries full damage provenance for authority to apply and replicate.
 - `encounterProgress` (function): function encounterProgress<TData>(state: EncounterState<TData>): { completed: number; total: number; done: boolean; } — Progress across the whole tree: how many phases have completed out of the total node count, plus whether the encounter has finished. Counts injected phases.
 - `eyeHeightFromColliders` (function): function eyeHeightFromColliders(set: EntityColliderSet | null | undefined): number — Eye height derived from a collider set: 90% of the tallest hitbox top, or the humanoid default when unknown.
 - `filterOutcomeFor` (function): function filterOutcomeFor(outcome: AllocationOutcome, viewerId: string): AllocationOutcome — Project an allocation outcome for one viewer, enforcing replication authoritatively: private grants belonging to other recipients are dropped, and pools the viewer cannot claim (not eligible, or reserved for someone else) are hidden — so private rewards never leak across the wire while provenance on the viewer's own grants is preserved.
@@ -167,10 +181,12 @@
 - `resolveResistance` (function): function resolveResistance<TCategory extends string = string, TProperty extends string = string>(matrix: ResistanceMatrix<TCategory, TProperty>, category: TCategory | string, targetProperties: readonly (TProperty | string)[]): ResistanceResult — ⚠ undocumented
 - `resolveShot` (function): function resolveShot(deps: ShotOriginDeps, from: string, aim: Aim, policy: ShotOriginPolicy = { kind: "eye" }): ResolvedShot | null — ⚠ undocumented
 - `resolveStatusApplication` (function): function resolveStatusApplication(input: StatusApplicationInput): StatusApplicationOutcome — Resolve one status application: reject on immunity, roll landing chance against injected RNG, scale magnitude/duration by the matchup, then fold into any existing instance per the stacking policy. Deterministic given a seeded `rng`; pure over serializable data, so authority can run it and replicate only the returned `instance`.
+- `resolveVfxPreset` (function): function resolveVfxPreset(name: string | undefined, overrides?: Partial<VfxPreset>): VfxPreset — Resolve a named visual flavor into a concrete `{ kind, color, durationMs?, radius? }`, with any provided `overrides` winning field by field. An unknown name resolves to {@link DEFAULT_VFX_PRESET} rather than throwing, so a flavor typo degrades to a visible spark. Used by `ctx.scene.entity.vfx({ preset })`; call it directly when you need the raw numbers (e.g. to seed a retained `vfxInstance` from the same vocabulary).
 - `rollCheck` (function): function rollCheck(input: CheckInput, rng: () => number = Math.random): CheckResult — Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
 - `startEncounter` (function): function startEncounter<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, ctx: EncounterContext = {}): EncounterStep<TData> — Start a created encounter: enter the first root phase, descending to its first leaf, and return the initial enter/spawn events. A no-op (with no events) on an already-started or empty encounter. Mutates and returns `state`.
 - `tierAt` (function): function tierAt(value: number, tiers: readonly MeterTier[]): string | null — The highest tier id whose `at` threshold `value` has reached, or `null` below every tier — the pure lookup `createAccumulatorMeter`/`createEventMeter` call on every `add`/`tick`.
 - `updateEncounter` (function): function updateEncounter<TData>(config: EncounterConfig<TData>, state: EncounterState<TData>, dt: number, ctx: EncounterContext = {}): EncounterStep<TData> — Advance an encounter by `dt` seconds against the caller `ctx`. Accumulates time, then repeatedly: evaluates the cursor node's completion predicate; on completion, either re-runs its subtree (`repeat`) or marks it complete and advances to the next sibling — bubbling up to parent groups whose children are exhausted — entering the next chain and emitting enter/spawn/complete events. Emits a final `done` event when the last phase completes. Bounded per call by node count; mutates and returns `state`.
+- `vfxPresets` (const): const vfxPresets: { readonly arrow: { readonly kind: "projectile"; readonly color: 14207392; }; readonly bolt: { readonly kind: "projectile"; readonly color: 16777215; }; readonly fireball: { readonly kind: "projectile"; readonly color: 16738842; readonly durationMs: 460; }; readonly firebolt: { rea… — Ready-made visual flavors for the things players actually shoot, swing, and cast — so `ctx.scene.entity.vfx({ preset: "arrow", from, to })` renders a visible bolt with zero tuning, and `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` likewise just work. Each entry only picks a `kind` (`projectile | beam | nova | glow | spark`), a color, and a lifetime; it is visual vocabulary (like named CSS colors), not a gameplay archetype — combat numbers stay in the caller's own effect/ability data. Any field passed to `vfx()` overrides the preset, and unknown names fall back to `spark` so a flavor typo still shows *something* rather than nothing.
 
 ## @jgengine/core/combat/abilityKit
 
@@ -350,7 +366,7 @@
 - `ReceiveMap` (type): type ReceiveMap = Record<string, ReceiveRule> — ⚠ undocumented
 - `ReceiveRule` (interface): interface ReceiveRule — ⚠ undocumented
 - `SingleTargetEffectInput` (interface): interface SingleTargetEffectInput — ⚠ undocumented
-- `createEffectSystem` (function): function createEffectSystem(deps: EffectSystemDeps): EffectSystem — Apply, stack, and tick timed status effects — buffs, debuffs, DoTs — on entities.
+- `createEffectSystem` (function): function createEffectSystem(deps: EffectSystemDeps): EffectSystem — Resolve direct or area resource effects through caller-owned stat pools, including ordered absorption, restoration, modifiers, and lethal context.
 - `resolveAreaTargets` (function): function resolveAreaTargets(spatial: CombatSpatialDeps, input: AreaTargetInput, accept?: (instanceId: string) => boolean): AreaTarget[] — ⚠ undocumented
 
 ## @jgengine/core/combat/encounterSequence
@@ -400,6 +416,7 @@
 - `Magazine` (interface): interface Magazine — A per-weapon magazine: discrete loaded rounds, a timed reload that refills from a reserve pool, and the reserve-pool interaction itself — the primitive that replaces hand-rolling mag size, reload delay, and reserve bookkeeping per game (#536.2).
 - `MagazineConfig` (interface): interface MagazineConfig — Tuning for `createMagazine`: mag capacity, reload delay, and where reserve ammo is drawn from.
 - `MagazineReserve` (interface): interface MagazineReserve — Draws ammo for a `Magazine`'s reload from wherever the reserve pool actually lives.
+- `MagazineSnapshot` (interface): interface MagazineSnapshot — Complete serializable state for a {@link Magazine}; `reserve: null` means infinite reserve.
 - `createMagazine` (function): function createMagazine(config: MagazineConfig): Magazine — Builds a {@link Magazine}: discrete loaded ammo, a timed reload, and reserve-pool interaction.
 
 ## @jgengine/core/combat/projectiles
@@ -526,6 +543,25 @@
 - `ThresholdTrackerSnapshot` (interface): interface ThresholdTrackerSnapshot — Serializable tracker state for save/load.
 - `createThresholdTracker` (function): function createThresholdTracker(config: ThresholdCrossingConfig): ThresholdTracker — Track a numeric source against named thresholds and emit ordered crossing events with direction, hysteresis, once/repeat policy, and skipped-threshold handling. Deterministic and serializable; drives phase transitions, armor breaks, resource warnings, and any other threshold consumer.
 
+## @jgengine/core/combat/vfxPresets
+
+- `DEFAULT_VFX_PRESET` (const): const DEFAULT_VFX_PRESET: VfxPresetName — The fallback flavor used when a `vfx()` call names an unknown preset — so a typo still shows a spark instead of nothing.
+- `VfxPreset` (interface): interface VfxPreset — A named visual flavor for a one-shot `combat.vfx` burst: the archetype (`kind`), a `0xRRGGBB` tint, and optional default `durationMs`/`radius`. Purely presentation — a preset never touches damage, range, or any authoritative value; it just answers "what does this attack look like" so a game does not hand-roll colors and archetypes.
+- `VfxPresetName` (type): type VfxPresetName = keyof typeof vfxPresets — A named key into {@link vfxPresets} (`"arrow" | "fireball" | "lightning" | "web" | "slash" | "shield" | "heal" | ...`).
+- `resolveVfxPreset` (function): function resolveVfxPreset(name: string | undefined, overrides?: Partial<VfxPreset>): VfxPreset — Resolve a named visual flavor into a concrete `{ kind, color, durationMs?, radius? }`, with any provided `overrides` winning field by field. An unknown name resolves to {@link DEFAULT_VFX_PRESET} rather than throwing, so a flavor typo degrades to a visible spark. Used by `ctx.scene.entity.vfx({ preset })`; call it directly when you need the raw numbers (e.g. to seed a retained `vfxInstance` from the same vocabulary).
+- `vfxPresets` (const): const vfxPresets: { readonly arrow: { readonly kind: "projectile"; readonly color: 14207392; }; readonly bolt: { readonly kind: "projectile"; readonly color: 16777215; }; readonly fireball: { readonly kind: "projectile"; readonly color: 16738842; readonly durationMs: 460; }; readonly firebolt: { rea… — Ready-made visual flavors for the things players actually shoot, swing, and cast — so `ctx.scene.entity.vfx({ preset: "arrow", from, to })` renders a visible bolt with zero tuning, and `"lightning"`, `"web"`, `"slash"`, `"shield"`, `"heal"`, `"explosion"` likewise just work. Each entry only picks a `kind` (`projectile | beam | nova | glow | spark`), a color, and a lifetime; it is visual vocabulary (like named CSS colors), not a gameplay archetype — combat numbers stay in the caller's own effect/ability data. Any field passed to `vfx()` overrides the preset, and unknown names fall back to `spark` so a flavor typo still shows *something* rather than nothing.
+
+## @jgengine/core/combat/weaponFire
+
+- `FireCadence` (interface): interface FireCadence — A minimal minimum-interval rate gate for a repeated action — weapon fire, ability spam, any "no faster than N per second" rule. Deterministic and serializable: its whole state is the elapsed time since the last action, exposed via {@link FireCadence.elapsedMs}.
+- `FireCadenceConfig` (interface): interface FireCadenceConfig — Tuning for {@link createFireCadence}: the minimum interval between actions and whether it starts ready.
+- `WeaponFireResult` (interface): interface WeaponFireResult<THit> — The result of a {@link WeaponRuntime.fire} attempt. On `"fired"`, `hits` is whatever the caller's raycast returned and `resolutions` holds the portable damage provenance for each hit that produced a {@link DamageHitInput}; on any blocked status both are empty and no round was spent.
+- `WeaponFireStatus` (type): type WeaponFireStatus = "fired" | "cooling" | "empty" | "reloading" — Why a {@link WeaponRuntime.fire} attempt resolved the way it did.
+- `WeaponRuntime` (interface): interface WeaponRuntime<TAim, THit> — A composed weapon fire controller: a {@link FireCadence} gate, an optional {@link Magazine}, the caller's raycast, and portable {@link resolveDamageHit} damage resolution wired together. The caller retains ownership of models, animations, muzzle flash, audio, input, camera, aiming, and the raycaster itself.
+- `WeaponRuntimeConfig` (interface): interface WeaponRuntimeConfig<TAim, THit> — Configuration for {@link createWeaponRuntime}. Everything time/ammo-related is plain data; the two callbacks are where the caller keeps ownership of aiming, its own raycaster/projectile query, and how a hit maps to damage. There is deliberately no default weapon, projectile, or damage table here — those are game content.
+- `createFireCadence` (function): function createFireCadence(config: FireCadenceConfig): FireCadence — Build a {@link FireCadence} rate gate. Reach for this instead of hand-tracking a `lastFiredAt` timestamp and comparing against a fire interval per game.
+- `createWeaponRuntime` (function): function createWeaponRuntime<TAim, THit>(config: WeaponRuntimeConfig<TAim, THit>): WeaponRuntime<TAim, THit> — Compose a portable weapon fire controller from the existing generic primitives — a {@link FireCadence} gate, an optional {@link Magazine}, a caller-provided raycast, and portable {@link resolveDamageHit} damage resolution. No `GameContext`, entity store, renderer, or default weapon is involved; the caller owns aiming, its raycaster, and all presentation, and the result carries full damage provenance for authority to apply and replicate.
+
 ## @jgengine/core/stats/accumulatorMeter
 
 - `AccumulatorMeter` (interface): interface AccumulatorMeter — ⚠ undocumented
@@ -569,6 +605,7 @@
 - `StatModifier` (interface): interface StatModifier — ⚠ undocumented
 - `StatModifierSet` (type): type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>> — ⚠ undocumented
 - `Stats` (interface): interface Stats<TStat extends string> — ⚠ undocumented
+- `StatsSnapshot` (interface): interface StatsSnapshot<TStat extends string> — Complete plain-data state for a {@link Stats} runtime.
 - `createStats` (function): function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat> — A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
 
 ## @jgengine/core/stats/statPool

package/skills/jgengine-combat/capabilities.md

@@ -120,6 +120,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEventMeter` (function) · `import { createEventMeter } from "@jgengine/core/combat"`
 
+## fire-cadence — a serializable minimum-interval rate gate for repeated actions (weapon fire, ability spam)
+
+- `createFireCadence` (function) · `import { createFireCadence } from "@jgengine/core/combat"`
+
 ## immunity-window — reject damage during a per-target invulnerability window installed by transitions
 
 - `createImmunityWindow` (function) · `import { createImmunityWindow } from "@jgengine/core/combat"`
@@ -204,10 +208,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `resolveStatusApplication` (function) · `import { resolveStatusApplication } from "@jgengine/core/combat"`
 
-## status-effects — apply and tick timed status effects and buffs on entities
+## status-effects — commit direct or area effects through caller-owned stat pools with ordered spillover and lethal results
 
 - `createEffectSystem` (function) · `import { createEffectSystem } from "@jgengine/core/combat"`
 
 ## threshold-crossings — emit ordered crossing events as a numeric source passes named thresholds with hysteresis and once/repeat policy
 
 - `createThresholdTracker` (function) · `import { createThresholdTracker } from "@jgengine/core/combat"`
+
+## vfx-preset-resolve — turn a named attack flavor into concrete vfx kind/color/duration with per-field overrides
+
+- `resolveVfxPreset` (function) · `import { resolveVfxPreset } from "@jgengine/core/combat"`
+
+## vfx-presets — render a named attack visual (arrow, fireball, lightning, web, slash, shield, heal, explosion) in one call
+
+- `vfxPresets` (const) · `import { vfxPresets } from "@jgengine/core/combat"`
+
+## weapon-runtime — compose cadence, magazine, a caller-owned raycast, and portable damage resolution into a fire controller
+
+- `createWeaponRuntime` (function) · `import { createWeaponRuntime } from "@jgengine/core/combat"`