@jgengine/core 0.11.0 → 0.13.0

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

@@ -2,6 +2,36 @@
 
 Reference module for the [`jgengine-combat` API](SKILL.md) skill. Load this when you need the combat surface — effects, projectiles, death, feel, and abilities.
 
+## Portable named resources
+
+`StatPool` (`@jgengine/core/stats/statPool`) is the plain
+`{ current, max, min }` model for any caller-named bounded resource. Existing
+projects implement the two-method `StatPoolAccess` over their own ECS, reducer,
+or save model, then use `applyStatPoolDelta`; reducer-style integrations use
+the pure `createStatPool` / `patchStatPool` / `changeStatPool` transitions.
+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).
@@ -25,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). Default entity hitbox is a body-covering AABB (feet to ~1.8m). Objects with a `visual.scale` get a matching grounded physical body automatically; explicit catalog `colliders`/`halfExtents` override. 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.
 
@@ -74,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
 
@@ -94,5 +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.
-
-

package/skills/jgengine-gameplay/SKILL.md

@@ -11,6 +11,10 @@ This skill owns non-combat rules and state: systems, catalogs, inventory/items,
 
 Use [capabilities.md](capabilities.md) for intent discovery, [api.md](api.md) for signatures, and [reference-systems.md](reference-systems.md) for scheduling details before hand-rolling a subsystem.
 
+Existing projects can keep player state and saves behind `LevelingStatAccess`.
+Follow the [portable XP/leveling recipe](recipes/portable-xp-leveling.md) for
+custom stat ids, immutable store writes, multiple level events, and JSON resume.
+
 ## Canonical workflow
 
 1. Define plain serializable state and stable ids.
@@ -30,6 +34,10 @@ Prefer `defineSystem` and `defineGame({ systems })` for scheduled capabilities.
 - Random selection accepts injected RNG and stable ordering.
 - Large collections use indexes, queues, or bounded reconciliation rather than repeated scans.
 
+## Part-composed character motion
+
+A character kit-bashed from primitives/`ModelPart`s (no skeleton, no clips) animates procedurally: tag parts with `role` (`leg.l`, `arm.r`, `head`, `tail`, `wing.l`…) and the shell's part-motion rig drives counter-phase limb swing from the entity's live movement speed, idle breathe/sway, hit flinch on `combat.hitReaction`, and a death topple on `entity.died` — no game-side frame loops. Tune with `ModelConfig.partMotion`; curves are pure and deterministic (`@jgengine/core/game/partAnimation`), so crowds de-sync by instance-id phase and replays stay stable. Soft characters (blobs, slimes) opt into volume-conserving squash-and-stretch with `partMotion: { squashAmp }` — footfall squash, jelly idle breathe, flinch pulse — and `deathStyle: "splat"` flattens out on death instead of the default sideways topple. Rigged GLBs keep using `ModelConfig.animation` — roles are only for rig-less compositions.
+
 ## Traps
 
 - A bare export mention is not an example; use capabilities for discovery and real imports/tests for adoption.