@jgengine/core 0.18.1 → 0.19.0

package/skills/jgengine-combat/capabilities.md

@@ -120,7 +120,7 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createEncounterState` (function) · `import { createEncounterState } from "@jgengine/core/combat"`
 
-## event-meter — a heat/streak gauge that builds from repeated hits and cools down over time
+## event-meter — a heat/streak/alert gauge (wanted level, rage, combo) that builds from repeated events and cools down over time
 
 - `createEventMeter` (function) · `import { createEventMeter } from "@jgengine/core/combat"`
 
@@ -128,6 +128,14 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createFireCadence` (function) · `import { createFireCadence } from "@jgengine/core/combat"`
 
+## global-cooldown — share one cooldown across every ability slot (MMO global cooldown) with a cooldown group
+
+- `createAbilityKit` (function) · `import { createAbilityKit } from "@jgengine/core/combat"`
+
+## hitscan-shot — aim a hitscan shot (shoot a gun): resolve origin and direction from the eye or muzzle for a raycast
+
+- `resolveShot` (function) · `import { resolveShot } 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"`
@@ -141,6 +149,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createMagazine` (function) · `import { createMagazine } from "@jgengine/core/combat"`
 
+## on-death-drops — make a killed enemy drop loot on the ground or into the killer's bag via catalog onDeath
+
+- `OnDeathSpec` (interface) · `import { OnDeathSpec } from "@jgengine/core/combat"`
+
 ## parry-window — time a block/parry/i-frame defensive window against incoming hits
 
 - `createDefensiveWindow` (function) · `import { createDefensiveWindow } from "@jgengine/core/combat"`
@@ -236,6 +248,22 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `vfxPresets` (const) · `import { vfxPresets } from "@jgengine/core/combat"`
 
+## weapon-feedback — turn weapon shots, recoil kick and impacts into per-tick feedback-mixer signals for camera shake, audio and rumble
+
+- `createWeaponFeedbackSignals` (function) · `import { createWeaponFeedbackSignals } from "@jgengine/core/combat/weaponFeedback"`
+
+## weapon-handling — recoil patterns with camera kick and recovery, spread bloom, stance multipliers and ADS as serializable state
+
+- `createWeaponHandling` (function) · `import { createWeaponHandling } from "@jgengine/core/combat/weaponHandling"`
+
+## weapon-metrics — measure a weapon's feel as numbers — spread per shot, climb over a magazine, reset time, ADS time, time-to-kill at a range
+
+- `measureWeapon` (function) · `import { measureWeapon } from "@jgengine/core/combat/weaponHandling"`
+
+## weapon-presentation — per-weapon viewmodel offset, ADS pose, viewmodel FOV, sway, bob and recoil kick from a weapon handling frame
+
+- `createWeaponPresentation` (function) · `import { createWeaponPresentation } from "@jgengine/core/combat/weaponPresentation"`
+
 ## 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"`

package/skills/jgengine-combat/recipes/weapon-feel.md

@@ -0,0 +1,50 @@
+# Recipe — weapon feel (feel target → metrics → handling knobs)
+
+**What this wires:** a weapon that handles the way the brief says, from the shot to the camera, sound and rumble. There is no default rifle or shotgun: every weapon is a set of angles in radians and times in seconds that the game picks, checked against numbers it writes down first. A looter shooter's generated guns are the same fields, rolled from the game's own parts tables.
+
+## The seams
+
+- **Cadence and ammo.** `createWeaponRuntime` or `weaponFire` + `magazine`, per the [portable weapon-plumbing recipe](portable-weapon-plumbing.md). Each time the cadence fires, call `handling.fire(stance)`.
+- **Handling.** `createWeaponHandling(tuning, { random: ctx.rng })` from `@jgengine/core/combat/weaponHandling`.
+  - `recoil`: a `pattern` of `[pitch, yaw]` kicks per shot (or a flat `pitch`), `randomCone` from the injected RNG, `cameraShare` (view punch versus aim kick), `recoverRate`/`recoverDelay`, `adsScale`.
+  - `spread`: `base`, `perShot` bloom, `max`, `recoverRate`/`recoverDelay`, and `ads`/`crouching`/`moving`/`airborne` multipliers.
+  - `adsTime`.
+  - Sample the shot direction inside `fire().spread`. Add `tick(dt, stance).aimPitch/aimYaw` to the aim and `cameraPitch/cameraYaw` to the view only.
+  - `snapshot`/`restore` for prediction and replay; `retune` for attachments, parts and upgrades mid-fight.
+- **Presentation.** Return `{ handling: handling.frame(), presentation }` from `camera.weapon(entityId)`, with a `createWeaponPresentation` tuning (`@jgengine/core/combat/weaponPresentation`): `hip`/`ads` viewmodel offsets, `viewmodelFov`, `adsZoom`, `sway`, `bob` and `kick`. The `first` rig poses the viewmodel, adds recoil to the look and zooms with `adsProgress`. The `shoulder` rig takes its ADS framing and recoil from the same frame.
+- **Feedback.** `createWeaponFeedbackSignals()` from `@jgengine/core/combat/weaponFeedback`.
+  - Call `signals.shot(handling.fire(stance))` on each shot and `signals.impact(damage)` when a hit lands.
+  - Each tick, `mixer.update(dt, signals.read(handling.tick(dt, stance)))` on a `createFeedbackMixer` (`@jgengine/core/vfx/feedbackMixer`) the game declares.
+  - `kick`, `shot` and `impact` are one-tick pulses. Route `kick` without smoothing into a trauma target and pass it to `createCameraShake().add(...)` (`@jgengine/core/vfx/cameraShake`), so trauma lands once per shot.
+  - Route `impact` with a `release` into rumble targets for `ctx.input.rumble`, rate-limited to about 10 Hz. A threshold `event` on `impact` gives a hit-confirm one-shot.
+  - Play the gunshot once per `shot` count. `ads` and `spread` suit continuous targets such as a muffled gun tail or a HUD crosshair gap.
+- **Proof.** `measureWeapon(() => createWeaponHandling(tuning), { interval, burst, damage, pellets, targetHealth, range, targetRadius, damageAt, stance })` returns deterministic numbers:
+  - `spreadByShot`, `firstShotSpread` and `tenthShotSpread`.
+  - `burstClimb`: set `burst` to the magazine size for climb over a magazine.
+  - `resetSeconds` and `adsSeconds`.
+  - `shotsToKill` and `timeToKill`: expected damage, where each projectile hits by the share of its cone the target covers at `range`, scaled by the game's `damageAt` falloff.
+
+## Workflow
+
+1. **Write the feel as numbers** on the `WeaponReport` fields. Some examples:
+   - "Laser beam when aimed" is `spreadByShot[29] < 0.01` rad with `stance: { ads: true }`.
+   - "Controllable" is `burstClimb` under about 3° over the magazine and `resetSeconds < 0.5`.
+   - "Close-range only" is `timeToKill` at 5 m near `0` and above 2 s at 30 m.
+   - "Snappy sights" is `adsSeconds < 0.2`.
+2. **Put them in a test** next to the tuning, one `measureWeapon` call per weapon or per rolled part set.
+3. **Move one knob at a time** using the table below, and rerun after each change.
+4. **Fire it** in the game (`bun run drive <game> --record <name>`, per `jgengine-verify`). The tests prove the numbers; the recording proves the kick, shake and sound read right.
+
+## Symptom → knob
+
+| Symptom | Knob (direction) |
+| --- | --- |
+| Muzzle climbs out of control over a magazine | `recoil.pattern` pitch ↓, `recoverRate` ↑, `recoverDelay` ↓ |
+| Kick feels weak but aim stays true | `cameraShare` ↑: more view punch, same aim |
+| Spray is unlearnable | `randomCone` ↓, keep the drift in `pattern` |
+| Accurate forever while held | `spread.perShot` ↑, `max` ↑ |
+| Bloom never settles between bursts | `spread.recoverRate` ↑, `spread.recoverDelay` ↓ |
+| Hip fire too good versus aiming | `spread.ads` ↓, `recoil.adsScale` ↓ |
+| Sights feel sluggish | `adsTime` ↓ |
+| Shotgun kills at sniper range | `spread.base` ↑ or a steeper `damageAt` falloff |
+| Every shot shakes the same | route `kick` through a `curve` so the shake scales with the kick |