@jgengine/core 0.12.0 → 0.13.0

package/skills/jgengine-combat/recipes/portable-damage-effects.md

@@ -0,0 +1,197 @@
+# Apply damage to caller-owned resources
+
+Use this recipe when an existing JavaScript/TypeScript game wants JGengine's
+damage math, ordered interceptors, status resolution, shield spillover, and
+lethal result without adopting `GameContext`, the entity store, renderer, React,
+or JGengine's game loop.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core
+```
+
+```ts
+import {
+  createEffectSystem,
+  type ReceiveMap,
+} from "@jgengine/core/combat/effects";
+import {
+  createDamageClamp,
+  resolveDamage,
+} from "@jgengine/core/combat/damageInterceptors";
+import { resolveDamageHit } from "@jgengine/core/combat/damageResolution";
+import {
+  createStatPool,
+  type StatPool,
+  type StatPoolAccess,
+} from "@jgengine/core/stats/statPool";
+import { seededRng } from "@jgengine/core/random/rng";
+```
+
+## Caller-owned state and adapter
+
+This example uses an immutable store-shaped object. A Redux, Zustand, ECS, or
+custom store can implement the same two methods without copying its entities
+into JGengine.
+
+```ts
+interface UnitState {
+  pools: Record<string, StatPool>;
+  receive: ReceiveMap;
+  statuses: Record<string, unknown>;
+}
+
+interface ExistingSave {
+  units: Record<string, UnitState>;
+}
+
+let save: ExistingSave = {
+  units: {
+    enemy_7: {
+      pools: {
+        shield: createStatPool({ current: 25, max: 25 }),
+        vitality: createStatPool({ current: 80, max: 80 }),
+      },
+      receive: { damage: { order: ["shield", "vitality"] } },
+      statuses: {},
+    },
+  },
+};
+
+const statPools: StatPoolAccess = {
+  get(ownerId, statId) {
+    return save.units[ownerId]?.pools[statId] ?? null;
+  },
+  set(ownerId, statId, next) {
+    const unit = save.units[ownerId];
+    if (unit === undefined) return false;
+    save = {
+      ...save,
+      units: {
+        ...save.units,
+        [ownerId]: { ...unit, pools: { ...unit.pools, [statId]: next } },
+      },
+    };
+    return true;
+  },
+};
+```
+
+`set` receives a complete plain replacement pool. The SDK never asks for the
+store itself and never mutates an entity object behind the adapter.
+
+## Build the effect committer
+
+```ts
+const existingEventQueue: unknown[] = [];
+const existingEvents = {
+  emit(name: string, payload: unknown) {
+    existingEventQueue.push({ name, payload });
+  },
+};
+
+const effects = createEffectSystem({
+  resolveReceive: (unitId) => save.units[unitId]?.receive,
+  statPools,
+  getStat: (_itemId, _statId) => null,
+  spatial: {
+    inRadius: (_center, _radius) => [],
+    hasLineOfSight: (_from, _to) => true,
+    positionOf: (_unitId) => undefined,
+  },
+  onLethal(unitId, context) {
+    existingEvents.emit("unit-defeated", { unitId, context });
+  },
+});
+```
+
+The spatial adapter is only used by area effects. Connect those three methods
+to the existing project's spatial index and line-of-sight query when needed;
+single-target effects do no world scan.
+
+## Resolve and apply a hit
+
+Keep resolution and commitment explicit. The pure stages return provenance and
+status state; authority decides what to persist and then routes final
+applications into the structural effect committer.
+
+```ts
+const seededRandom = seededRng("shot-2048");
+const simulationNowMs = 4_000;
+
+const hit = resolveDamageHit({
+  channel: "arc",
+  impact: 40,
+  source: "player",
+  target: "enemy_7",
+  targetTraits: ["shielded"],
+  status: { status: "charged", chance: 0.35, durationMs: 2_000 },
+  rng: seededRandom, // caller-owned deterministic stream
+});
+
+const intercepted = resolveDamage(
+  [createDamageClamp({ id: "per-hit-cap", maxPerHit: 30 })],
+  {
+    source: "player",
+    target: "enemy_7",
+    amount: hit.impact,
+    tag: hit.channel,
+  },
+  { nowMs: simulationNowMs }, // caller-owned deterministic clock
+);
+
+for (const application of intercepted.applications) {
+  effects.applyEffect({
+    from: application.source,
+    to: application.target,
+    effect: "damage",
+    via: { amount: application.amount },
+  });
+}
+
+if (hit.status?.instance !== null && hit.status?.instance !== undefined) {
+  save.units.enemy_7!.statuses[hit.status.instance.status] = hit.status.instance;
+}
+```
+
+`intercepted.provenance` records each ordered policy decision. `hit.matchup`,
+`hit.received`, and `hit.status` retain the pure resolution evidence. The effect
+result lists exact per-pool deltas in the receive order and reports lethality
+when the final pool reaches its minimum.
+
+## Save and restore
+
+The authoritative pools and returned status instances are already plain data:
+
+```ts
+const encoded = JSON.stringify(save);
+save = JSON.parse(encoded) as ExistingSave;
+```
+
+Recreate the small adapters over the restored store. Interceptor functions and
+catalog rules are configuration, so re-supply them rather than serializing
+closures. Persist any stateful interceptor records separately when their API
+exposes serializable state.
+
+## Ownership
+
+The existing project retains entity identity, resource names, store updates,
+save schema, status collection, authority, spatial queries, death/despawn,
+events, clock, RNG, content, presentation, and its update loop. JGengine owns
+the pure resolution stages, bounded ordered interception, pool spillover math,
+and inspectable results.
+
+## Common traps
+
+- Use positive effect magnitudes to drain pools and negative magnitudes to
+  restore them; the receive rule determines which named pools participate.
+- Put shields or other absorbers before the final lethal pool in `order`.
+- Pass final interceptor applications to `applyEffect`; do not apply the
+  pre-interceptor impact as well.
+- Persist the returned status `instance`; `resolveDamageHit` is intentionally
+  pure and does not hide a status store.
+- Use a bounded spatial index for `inRadius`; do not add a full-world scan per
+  area effect.
+- Keep audio, particles, hit flashes, animations, camera shake, and models in
+  the existing project. Drive them from the returned results and provenance.

package/skills/jgengine-combat/recipes/portable-runtime-state.md

@@ -0,0 +1,154 @@
+# Save and restore closure-backed combat runtimes
+
+Use this recipe when an existing project wants JGengine's convenient magazine
+or stat-modifier runtime but keeps its own save system, clock, entities, and
+authority. Both runtimes expose detached plain snapshots; no JGengine store or
+`GameContext` is required.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core
+```
+
+```ts
+import {
+  createMagazine,
+  type MagazineSnapshot,
+} from "@jgengine/core/combat/magazine";
+import {
+  createStats,
+  type StatsSnapshot,
+} from "@jgengine/core/stats/statModifiers";
+```
+
+## Caller-owned save data
+
+```ts
+type VehicleStat = "speed" | "handling";
+
+interface VehicleRuntimeSave {
+  magazine: MagazineSnapshot;
+  stats: StatsSnapshot<VehicleStat>;
+}
+
+interface ExistingSave {
+  nowMs: number;
+  vehicle: VehicleRuntimeSave;
+  sharedAmmo: number;
+}
+```
+
+The project owns this schema and decides when it is written, replicated,
+rolled back, replayed, or transferred to a worker.
+
+## Run and snapshot
+
+```ts
+let nowMs = 4_000;
+let sharedAmmo = 18;
+
+const magazine = createMagazine({
+  capacity: 6,
+  reloadMs: 900,
+  reserve: {
+    current: () => sharedAmmo,
+    spend(amount) {
+      if (amount > sharedAmmo) return false;
+      sharedAmmo -= amount;
+      return true;
+    },
+    gain(amount) {
+      sharedAmmo += amount;
+    },
+  },
+});
+
+const stats = createStats<VehicleStat>(
+  { speed: 12, handling: 8 },
+  { now: () => nowMs },
+);
+stats.addSource("boost", { speed: { multiply: 1.25 } }, { expiresAtMs: 7_000 });
+
+magazine.fire(2);
+magazine.startReload();
+magazine.tick(0.3);
+
+const save: ExistingSave = {
+  nowMs,
+  vehicle: {
+    magazine: magazine.snapshot(),
+    stats: stats.snapshot(),
+  },
+  sharedAmmo,
+};
+
+const serialized = JSON.stringify(save);
+```
+
+Snapshots are detached from the live closures. Mutating or continuing the
+runtime after this point does not rewrite `save`.
+
+## Restore and resume
+
+```ts
+const decoded = JSON.parse(serialized) as ExistingSave;
+nowMs = decoded.nowMs;
+sharedAmmo = decoded.sharedAmmo; // restore caller-owned reserve first
+
+const resumedMagazine = createMagazine({
+  capacity: 6,
+  reloadMs: 900,
+  loaded: 0,
+  reserve: {
+    current: () => sharedAmmo,
+    spend(amount) {
+      if (amount > sharedAmmo) return false;
+      sharedAmmo -= amount;
+      return true;
+    },
+    gain(amount) {
+      sharedAmmo += amount;
+    },
+  },
+});
+if (!resumedMagazine.restore(decoded.vehicle.magazine)) {
+  throw new Error("magazine save does not match its reserve configuration");
+}
+
+const resumedStats = createStats<VehicleStat>(
+  { speed: 0, handling: 0 },
+  { now: () => nowMs },
+);
+resumedStats.restore(decoded.vehicle.stats);
+
+resumedMagazine.tick(0.6); // finishes the same in-progress 900ms reload
+nowMs = 7_000;
+resumedStats.get("speed"); // injected clock expires the boost deterministically
+```
+
+For a self-managed numeric magazine reserve, the magazine snapshot contains
+and restores that reserve directly. For a caller-owned `MagazineReserve`, save
+and restore the caller's reserve first; `restore` returns `false` rather than
+partially changing loaded/reload state when it cannot reconcile the reserve.
+
+## Ownership
+
+The existing project owns save versioning, entity identity, clock value,
+reserve state, networking/rollback policy, content, and when ticks occur.
+JGengine owns the closure convenience methods, snapshot encoding shape,
+detached copies, and deterministic continuation once the caller supplies the
+same config and clock.
+
+## Common traps
+
+- Re-supply immutable configuration such as magazine capacity/reload duration
+  and the stat id set when rebuilding a runtime; snapshots contain mutable
+  state, not content catalogs.
+- Restore externally-owned reserve data before calling `Magazine.restore`.
+- Persist the injected clock alongside expiring modifier snapshots or convert
+  expiry timestamps in the project's migration layer.
+- Do not keep a live snapshot object as mutable state. Restore it into a runtime
+  and take a fresh snapshot for the next save.
+- Check the boolean returned by `Magazine.restore`; reserve-kind mismatches and
+  unreconcilable external reserves are rejected without partial magazine state.

package/skills/jgengine-combat/recipes/portable-weapon-plumbing.md

@@ -0,0 +1,156 @@
+# Fire a weapon with your own Three.js raycaster
+
+Use this recipe when an existing Three.js/JavaScript game wants JGengine's fire
+cadence, magazine/reload, and deterministic damage resolution but keeps its own
+models, animations, muzzle flash, audio, input, camera, aiming, and — crucially —
+its own raycaster and entity list. There is no default gun: you compose generic
+primitives. No `GameContext`, entity store, renderer, or React is required.
+
+## Install and focused imports
+
+```sh
+bun add @jgengine/core three
+```
+
+```ts
+import {
+  createWeaponRuntime,
+  type WeaponRuntime,
+} from "@jgengine/core/combat";
+import type { DamageHitInput } from "@jgengine/core/combat";
+import * as THREE from "three";
+```
+
+## Caller-owned aim, entities, and raycaster
+
+The engine never touches your scene. You own the raycast; it returns whatever hit
+shape you like.
+
+```ts
+interface Enemy {
+  id: string;
+  mesh: THREE.Object3D;
+  armored: boolean;
+}
+
+const enemies: Enemy[] = loadEnemies();
+const raycaster = new THREE.Raycaster();
+
+function raycastFromCamera(camera: THREE.Camera): Enemy[] {
+  raycaster.setFromCamera(new THREE.Vector2(0, 0), camera); // center-screen shot
+  const meshes = enemies.map((e) => e.mesh);
+  const intersects = raycaster.intersectObjects(meshes, true);
+  const first = intersects[0];
+  if (first === undefined) return [];
+  const enemy = enemies.find((e) => e.mesh === first.object || e.mesh === first.object.parent);
+  return enemy === undefined ? [] : [enemy];
+}
+```
+
+## Compose the weapon runtime
+
+`cadenceMs`, `magazine`, and `ready` are plain data; `resolveHits` runs your
+raycaster and `damageFor` maps a hit to a portable damage input (return `null` to
+skip damage, e.g. a wall). Derive `cadenceMs` from a rounds-per-second fire rate
+with `1000 / roundsPerSecond`.
+
+```ts
+const rifle: WeaponRuntime<THREE.Camera, Enemy> = createWeaponRuntime({
+  cadenceMs: 1000 / 8, // 8 rounds/sec
+  magazine: { capacity: 30, reloadMs: 1800, reserve: 120 },
+  resolveHits: (camera) => raycastFromCamera(camera),
+  damageFor: (enemy): DamageHitInput => ({
+    channel: "kinetic",
+    impact: 24,
+    target: enemy.id,
+    targetTraits: enemy.armored ? ["armored"] : [],
+    matchup: { entries: { kinetic: { armored: { impact: 0.5 } } } },
+  }),
+});
+```
+
+## Fire, tick, and apply results
+
+```ts
+// Your input handler:
+function onTriggerDown(camera: THREE.Camera): void {
+  const result = rifle.fire(camera);
+  if (result.status === "fired") {
+    playMuzzleFlash();
+    for (const hit of result.resolutions) {
+      // Apply the resolved impact to YOUR health store, spawn YOUR hit spark, etc.
+      applyDamageToMyEntities(hit); // hit.impact, hit.channel, hit.status, hit.received
+    }
+  } else if (result.status === "empty") {
+    rifle.startReload();
+    playReloadAnim();
+  } // "cooling" and "reloading" are silent no-ops you can ignore or feed to the HUD
+}
+
+// Your frame loop:
+function update(dtSeconds: number): void {
+  rifle.tick(dtSeconds); // advances cadence + reload timers
+  hud.setAmmo(rifle.magazine?.loaded() ?? Infinity, rifle.magazine?.reserve() ?? null);
+  hud.setReload(rifle.magazine?.reloadFraction() ?? 0);
+}
+```
+
+`resolveHits` and `damageFor` are only called on a `"fired"` result, so a blocked
+trigger pull never touches your raycaster or ammo.
+
+## Bring your own ammo economy
+
+Point the magazine's `reserve` at a caller-owned pool with a `MagazineReserve`
+adapter instead of a plain number, so reloads draw from your shared inventory:
+
+```ts
+import type { MagazineReserve } from "@jgengine/core/combat";
+
+const backpack = { rifleAmmo: 240 };
+const reserve: MagazineReserve = {
+  current: () => backpack.rifleAmmo,
+  spend: (n) => (n <= backpack.rifleAmmo ? ((backpack.rifleAmmo -= n), true) : false),
+  gain: (n) => { backpack.rifleAmmo += n; },
+};
+// magazine: { capacity: 30, reloadMs: 1800, reserve }
+```
+
+## Save and restore
+
+The magazine exposes `loaded()`/`reserve()`/`reloadFraction()` and the cadence
+exposes `elapsedMs()`/`restore()` for HUD and snapshots:
+
+```ts
+const snapshot = {
+  cadenceMs: rifle.cadence.elapsedMs(),
+  loaded: rifle.magazine?.loaded() ?? null,
+};
+// After load: recreate the runtime from the same config, then:
+rifle.cadence.restore(snapshot.cadenceMs);
+```
+
+Recreate the magazine at its saved `loaded` via `MagazineConfig.loaded`. (Full
+magazine snapshot/restore lands with the serializable-runtime-state slice.)
+
+## Ownership
+
+The existing project keeps entities, meshes, the raycaster, aim, input, camera,
+muzzle flash, audio, animation, the health/damage sink, ammo inventory, weapon
+content and stats, and when the trigger fires. JGengine owns fire-rate gating,
+magazine/reload bookkeeping, and deterministic damage resolution (matchup,
+receiver modifiers, status rolls) with full provenance.
+
+## Common traps
+
+- `fire()` gates in order **reloading → cooling → empty**; a `"cooling"` result
+  means the cadence, not the magazine, blocked the shot. Tick before expecting
+  `"empty"`.
+- Only a `"fired"` result spends a round and resets cadence; blocked attempts are
+  free, so you can call `fire()` every input frame.
+- Firing does not auto-reload or fire-cancel a reload; call `startReload()` /
+  `cancelReload()` from your own input policy.
+- `damageFor` returning `null` keeps the hit in `result.hits` but produces no
+  `DamageHitResolution` — use it for terrain/props your raycast also returns.
+- Pass a seeded `rng` in the config for deterministic status rolls in multiplayer
+  authority, replays, or tests; per-hit `DamageHitInput.rng` overrides it.
+- Convert fire rate to `cadenceMs` with `1000 / roundsPerSecond`, not the reverse.

package/skills/jgengine-combat/recipes/visible-attacks.md

@@ -0,0 +1,81 @@
+# Recipe — make an attack you can actually see
+
+**Seam:** authoritative hit resolution (`applyEffect` / `fireProjectile`) ↔ the one-shot
+`combat.vfx` visual the shell renders. They are deliberately separate: **resolving damage
+never draws anything on its own.** If you call `applyEffect`/`fireProjectile` and "nothing
+happens on screen," you have the hit but not the picture — emit a `vfx` burst next to it.
+
+The easy path is a named **preset**, so you never hand-pick a `VfxKind` or a hex color.
+
+## The one line
+
+```ts
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+
+// caster and enemy are entity instance ids (the shell follows their live pose)
+function shootArrow(ctx: GameContext, caster: string, enemy: string): void {
+  ctx.scene.entity.vfx({ preset: "arrow", from: caster, to: enemy });
+}
+```
+
+That renders a visible bolt traveling from the caster to the enemy. Swap the flavor for the
+attack you want — the vocabulary already covers the usual suspects:
+
+| Want | `preset` | Archetype |
+| --- | --- | --- |
+| arrow / bolt / bullet | `"arrow"`, `"bolt"`, `"bullet"` | traveling `projectile` |
+| fire / ice / poison / arcane spell | `"fireball"`, `"firebolt"`, `"frostbolt"`, `"poison"`, `"arcane"`, `"shadowbolt"`, `"holybolt"` | traveling `projectile` |
+| lightning / laser / web / chain | `"lightning"`, `"laser"`, `"web"`, `"chain"` | connecting `beam` |
+| sword swing / melee hit | `"slash"`, `"sword"`, `"melee"`, `"hit"` | impact `spark` |
+| explosion / shockwave | `"explosion"`, `"blast"`, `"shockwave"`, `"frostNova"` | ground `nova` |
+| heal / buff / shield aura | `"heal"`, `"buff"`, `"shield"`, `"cast"` | lingering `glow` |
+
+Full list lives in `vfxPresets` (`@jgengine/core/combat`).
+
+## Wiring it to a real projectile attack
+
+`fireProjectile` returns a shot id; `settleProjectile` resolves the hit. Fire the visual when
+you fire the shot so the bolt is in flight while it travels, then settle to apply damage:
+
+```ts
+function fireAt(ctx: GameContext, caster: string, enemy: string): void {
+  const shot = ctx.scene.entity.fireProjectile({
+    from: caster,
+    via: { item: "shortbow" },
+    aim: { yaw: 0, pitch: 0 },
+    effect: "arrow-hit",
+  });
+  ctx.scene.entity.vfx({ preset: "arrow", from: caster, to: enemy }); // <- the picture
+  ctx.scene.entity.settleProjectile(shot);                            // <- the damage
+}
+```
+
+For a melee swing there is no projectile — just resolve the effect and flash the spark:
+
+```ts
+ctx.scene.entity.effect({ from: caster, to: enemy, effect: "cleave" });
+ctx.scene.entity.vfx({ preset: "slash", from: caster, to: enemy });
+```
+
+## Overrides and custom bursts
+
+Any field on the call wins over the preset, so you keep the archetype but retint it:
+
+```ts
+ctx.scene.entity.vfx({ preset: "fireball", color: 0x00ff88, from: caster, to: enemy });
+```
+
+Skip `preset` entirely and pass `kind` + `color` for a fully bespoke burst. A **misspelled**
+flavor still shows a `spark` rather than nothing, so a typo never silently drops the effect.
+
+When you need the raw numbers — e.g. to seed a long-lived `vfxInstance` beam from the same
+vocabulary — call `resolveVfxPreset("lightning")` and read `{ kind, color, durationMs?, radius? }`.
+
+## Don't
+
+- Don't expect `applyEffect`/`fireProjectile`/`settleProjectile` to draw a visual — they are
+  headless authority. The `vfx` call is what the player sees.
+- Don't put damage numbers in a preset. Presets are colors and shapes; combat values live in
+  your effect/ability data.
+- Don't disable presentation and wonder where the effect went: `presentationEffects` is on by
+  default, but if a game passes `presentationEffects: { vfx: false }` the burst won't render.

package/skills/jgengine-combat/reference.md

@@ -13,6 +13,25 @@ Native scene entity stats are a compatibility bridge over the same model. See
 the [portable stat-pool recipe](recipes/portable-stat-pools.md) for complete
 imports, adapter code, ownership, and JSON save/restore.
 
+## Portable runtime snapshots
+
+`createMagazine` (`combat/magazine`) and `createStats`
+(`stats/statModifiers`) retain their convenience APIs while exposing detached
+plain state through `snapshot()` / `restore(...)`. Magazine snapshots include
+loaded rounds, in-progress reload time, and finite/infinite reserve state;
+stat snapshots include base values plus ordered modifier sources and absolute
+expiry timestamps. Re-supply immutable config and the caller's injected clock
+when rebuilding. The [portable runtime-state recipe](recipes/portable-runtime-state.md)
+shows a complete existing-save round trip, including a caller-owned reserve.
+`createEffectSystem` (`combat/effects`) commits direct or area effects through
+the same `StatPoolAccess` contract. Receive rules still define deterministic
+shield/resource spill order, modifiers, and the final lethal pool; results
+carry exact applied deltas and lethal context. The legacy `resolveStats` input
+remains as a compatibility bridge, while native `GameContext` now supplies its
+`EntityStatsApi` adapter. Compose this committer with pure `resolveDamageHit`
+(matchup/received/status provenance) and `resolveDamage` (ordered bounded
+interceptors). See the [portable damage/effects recipe](recipes/portable-damage-effects.md).
+
 ## Effects and projectiles
 
 Effect ids are **game-defined strings**. Magnitudes **drain** stats: positive subtracts down `receive.<effect>.order` (spilling to the next stat in the order), negative restores. Heals pass a negative amount (`via: { amount: -flashHeal }`, typically read from a `weapon.heal` stat).
@@ -36,7 +55,7 @@ fireProjectile({ from, via, aim, effect })      // → shotId (pending)
 settleProjectile(shotId)                        // authoritative → { at, hits } | rejection
 ```
 
-`Aim = { origin, direction } | { yaw, pitch, spread? }`. A free `{ yaw, pitch }` aim defaults to `converge`: the bullet leaves the gun `muzzle` (so a tracer visibly comes from the barrel, not the camera) yet bends toward whatever the eye ray's crosshair covers, so the reticle stays truth. An explicit `{ origin, direction }` aim (enemy AI, turrets) passes through unchanged. Shot origin otherwise resolves via `ShotOriginPolicy` (`eye`: shooter position raised to eye height — 90% of the shooter's own hitbox top when colliders are known, ~1.6m otherwise — so shots trace the sightline and the crosshair is truth; `muzzle`/`camera`/`world` for custom rigs, `legacy` = raw entity position). Hitboxes auto-fit the rendered model: an entity kind mapped in `entityModels` (or an object catalog id in `objectModels`) gets a grounded AABB matching its model's measured bounds — footprint x height composed with `scale`/`targetHeight` exactly like the renderer — so the damage box equals the visual without hand-tuning. Unmodeled entities keep the body-covering humanoid AABB default (feet to ~1.8m); unmodeled objects with a `visual.scale` get a matching grounded physical body. Catalog assets opted into `COLLISION_MESH_ASSET_IDS` (`@jgengine/assets`) go one step further: the fit raycasts the asset's actual triangles (BVH over a quantized mesh shipped in the index), so a shot through a torus hole or archway passes clean instead of hitting the fitted box — same shape on client and headless host. Explicit catalog `colliders`/`halfExtents` and per-instance `setColliders` always override the fit. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
+`Aim = { origin, direction } | { yaw, pitch, spread? }`. A free `{ yaw, pitch }` aim defaults to `converge`: the bullet leaves the gun `muzzle` (so a tracer visibly comes from the barrel, not the camera) yet bends toward whatever the eye ray's crosshair covers, so the reticle stays truth. An explicit `{ origin, direction }` aim (enemy AI, turrets) passes through unchanged. Shot origin otherwise resolves via `ShotOriginPolicy` (`eye`: shooter position raised to eye height — 90% of the shooter's own hitbox top when colliders are known, ~1.6m otherwise — so shots trace the sightline and the crosshair is truth; `muzzle`/`camera`/`world` for custom rigs, `legacy` = raw entity position). Hitboxes auto-fit the rendered model: an entity kind mapped in `entityModels` (or an object catalog id in `objectModels`) gets a grounded AABB matching its model's measured bounds — footprint x height composed with `scale`/`targetHeight` exactly like the renderer — so the damage box equals the visual without hand-tuning. Custom-rendered content auto-fits too: the shell measures what `renderEntity`/`renderObject` actually mount (and any model with no index `dims`) and reports the entity-local bounds through `ctx.scene.entity.reportBounds` / `ctx.scene.object.reportBounds`, so a procedural mesh's hitbox wraps the render instead of the humanoid default — flag debug gizmos with `userData.jgMeasureExclude` to keep them out of the measurement, and note the measurement happens on the rendering client, so a never-rendering authoritative host should author `colliders` or model `dims` instead. Entities with nothing measurable at all keep the body-covering humanoid AABB default (feet to ~1.8m); unmodeled objects with a `visual.scale` get a matching grounded physical body. Catalog assets opted into `COLLISION_MESH_ASSET_IDS` (`@jgengine/assets`) go one step further: the fit raycasts the asset's actual triangles (BVH over a quantized mesh shipped in the index), so a shot through a torus hole or archway passes clean instead of hitting the fitted box — same shape on client and headless host. Explicit catalog `colliders`/`halfExtents` and per-instance `setColliders` always override the fit. Hitscan settles into per-hit effects; ballistic shots (`weapon.projectile` with `fuseTime`/`settleOn`) settle to a landing point — the handler then calls `effect({ at: settle.at, radius })`. Settling twice rejects. Prediction is never authority.
 
 Raycasts are **object-aware**: the default raycast checks placed scene objects as well as entities, discriminated by `RaycastHit.kind` (`"entity" | "object"` — an `ObjectRaycastHit` also carries `catalogId`). A crate or wall between shooter and target blocks or absorbs the shot instead of every projectile passing through scenery; supply `ProjectileSystemDeps.objects` (`{ list(), halfExtents?(catalogId) }`, matching `ObjectStore.list()` structurally) to opt in, with a `[0.5, 0.5, 0.5]` half-extent default per object.
 
@@ -85,7 +104,8 @@ Layered on top of effects/projectiles/death — none of it replaces them, it add
 - **Render cues** (`combat/renderCues`, #542) - the pure math behind a custom `renderEntity`/viewmodel rig's motion feel: `EntityRenderCues { speed, bobPhase, firing, reloading, recoil, hit, dead }`, `advanceMotionCues(cues, speed, dt, tuning?)` advances `bobPhase`/decays `recoil` from a live `groundSpeed(entity)` sample, `applyRenderAnimationEvent(cues, event)` folds in `"fire"` / `"reload"` / `"reloadEnd"` from `ctx.game.playEntityAnimation`, `applyRenderHitEvent`/`applyRenderDeathEvent` fold in `combat.hitReaction`/`entity.died`. `RenderCueTuning` overrides `cyclesPerUnit`/`recoilDecayPerSecond`/`firePulseSeconds`/`hitPulseSeconds`. A game never calls these directly — `@jgengine/shell/render`'s `useEntityRenderCues(instanceId)` (see `jgengine-ui`) wires all four into one ref-returning hook for `useFrame` consumers.
 - **Telegraph** (`combat/telegraph`) — a `TelegraphShape` (`circle | ring | cone | line`) + `windupMs`. `ctx.scene.entity.telegraph({ from, shape, at, dir?, windupMs, kind?, effect? })` emits `combat.telegraph` for the shell to draw a ground decal that fills over the windup, and — if `effect` is bound — applies that effect to everyone inside the shape (`pointInTelegraph`) at activation. Returns a cancel handle. **Turn-scoped variant**, for tactics/turn-based enemy intents instead of a real-time windup: set `TelegraphConfig.turns` (a count of turns instead of `windupMs`), then read `telegraphTurnProgress(config, startedTurn, currentTurn)` (0..1 fill fraction), `telegraphFiredAtTurn(config, startedTurn, currentTurn)` (has it resolved), and `telegraphTurnsRemaining(config, startedTurn, currentTurn)` — the same "enemy will hit this tile" decal, advanced by `turnLoop.round()`/`active()` instead of a clock.
 - **Damage-number typing** — `ctx.scene.entity.floatText({ …, crit?, element?, hitType?, scale? })` (and the `entity.floatText` event) carry hit metadata; the shell's `resolveFloatTextStyle` (`@jgengine/shell/world/floatTextStyle`) maps crit/element to color + scale + glow.
-- **VFX — one-shot vs retained** — `ctx.scene.entity.vfx({ kind, color, from?, to?, radius?, durationMs? })` fires a **one-shot** burst (`combat.vfx`, `kind: projectile | beam | nova | glow | spark`) the shell renders once and expires. For a **long-lived** effect whose endpoints/params move over time (held beam, tether, zone, target line, looping emitter) use the retained registry `ctx.scene.entity.vfxInstance` (`createVfxInstanceStore`, `@jgengine/core/game/vfxInstance`): `upsert({ id?, kind, color, from?, to?, radius?, params?, ttlMs? })` creates or replaces by stable id, `update(id, patch)` nudges dynamic params (a missing id is a no-op, not a throw), `stop(id, { fadeMs? })` disposes with an optional fade, and `tick(now)` enforces the TTL heartbeat; `list()`/`count()` are for debug. Endpoints are `VfxRef`s — an entity **instance id** (the shell resolves its live pose each frame, so the effect follows a moving entity with no per-frame commands) or a fixed `[x, y, z]` world point. State is headless/serializable and the store is renderer-independent; each op emits `combat.vfxInstance` which the shell's `RetainedVfx` overlay binds to render resources (beam is the first shipped retained renderer). Call `vfxInstance.clear()` on scene/level reset. Duet Keys' prism beam is the first adopter (driven from its `onTick`).
+- **VFX — make an attack visible in one line** — the easy, discoverable path is a named `preset`: `ctx.scene.entity.vfx({ preset: "arrow", from: caster, to: enemy })` renders a visible bolt with zero color/archetype tuning, and `"lightning"`, `"web"`, `"slash"`/`"sword"`, `"shield"`, `"heal"`, `"fireball"`, `"frostbolt"`, `"explosion"` and the rest of `vfxPresets` (`@jgengine/core/combat`) likewise just work — this is the answer to "I fired a projectile at the enemy but couldn't see anything." A preset is pure presentation vocabulary (a `kind` + color + lifetime, like named CSS colors); it never touches damage or hit resolution, which stay in your effect/projectile data. **The authoritative `fireProjectile`/`settleProjectile` and `applyEffect` do not emit any visual on their own** — emit the `vfx` burst yourself when you fire/settle (`fireProjectile(...)` → `vfx({ preset, from, to })`). Any field you also pass overrides the preset (`vfx({ preset: "fireball", color: 0x00ff00 })`); supply `kind` + `color` directly for a fully custom burst with no preset; an unknown flavor name degrades to a visible `spark` rather than nothing. `resolveVfxPreset(name, overrides?)` returns the raw `{ kind, color, durationMs?, radius? }` when you need the numbers (e.g. to seed a retained instance from the same vocabulary). Full walkthrough: [make an attack you can actually see](recipes/visible-attacks.md).
+- **VFX — one-shot vs retained** — `ctx.scene.entity.vfx({ preset?, kind?, color?, from?, to?, radius?, durationMs? })` fires a **one-shot** burst (`combat.vfx`, `kind: projectile | beam | nova | glow | spark`) the shell renders once and expires. For a **long-lived** effect whose endpoints/params move over time (held beam, tether, zone, target line, looping emitter) use the retained registry `ctx.scene.entity.vfxInstance` (`createVfxInstanceStore`, `@jgengine/core/game/vfxInstance`): `upsert({ id?, kind, color, from?, to?, radius?, params?, ttlMs? })` creates or replaces by stable id, `update(id, patch)` nudges dynamic params (a missing id is a no-op, not a throw), `stop(id, { fadeMs? })` disposes with an optional fade, and `tick(now)` enforces the TTL heartbeat; `list()`/`count()` are for debug. Endpoints are `VfxRef`s — an entity **instance id** (the shell resolves its live pose each frame, so the effect follows a moving entity with no per-frame commands) or a fixed `[x, y, z]` world point. State is headless/serializable and the store is renderer-independent; each op emits `combat.vfxInstance` which the shell's `RetainedVfx` overlay binds to render resources (beam is the first shipped retained renderer). Call `vfxInstance.clear()` on scene/level reset. Duet Keys' prism beam is the first adopter (driven from its `onTick`).
 
 ## Abilities, resources, auto-target, resistance, run drafts
 
@@ -105,4 +125,3 @@ Genre systems layered over the same effects/projectiles/targeting/loot primitive
 - **Completion predicates** — `completion: { kind, params }` names a registered evaluator; `BUILTIN_COMPLETION_PREDICATES` ships `immediate`, `manual`/`flag`, `timer` (phase seconds), `cleared` (tagged count drained), `metric` (live threshold), `event` (cumulative count), and `quorum` (N of nested predicates). Signals (`counts`/`metrics`/`events`/`flags`) come in through `ctx.signals`; evaluation is deterministic. Register your own via `config.predicates`.
 - **Spawn providers** — spawning is one optional node adapter: `spawn: { kind, params }` invoked on enter. `BUILTIN_SPAWN_PROVIDERS.points` reads a named authored scene point list from `ctx.spawnPoints` (coordinates stay in the scene, referenced by key — never embedded in the sequence); `list` echoes inline requests. Register catalog/director-backed providers via `config.spawnProviders`.
 - **Injection & scripted control** — `injectPhase(state, phase, { after | before | childOf })` inserts a phase or branch at runtime (e.g. a boss after the final wave) into the serializable tree without disturbing active/completed nodes; `forceCompletePhase` completes the active phase regardless of its predicate for scripted skips and failure/retry, restoring the authored predicate afterward.
-