# Visual effects of combat (fx.* kits)

Short presentation effects tied to combat events: a library effect when an ability fires, a flash when something is hit. Readable
offline: `gripforge docs fx-kits`, or the MCP tool `gripforge_docs` (topic `fx-kits`).

## The map

| Kit | What it does | Needs |
| --- | --- | --- |
| `fx.ability_vfx` | plays a library effect (kind `vfx`) where an ability lands, turned the way the caster faces | `combat.abilities` |
| `fx.hit_flash` | whatever takes damage flashes: a bright tint that fades, with a small scale punch | nothing besides `game.engine` |

Both are views (role `view`): headless, they decide where and how and emit an event; the renderer plays or tints once. Neither takes a
decision of the game, so neither declares a hook. They work on the web and in the native Rust player.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "fx.hit_flash" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "fx.hit_flash", config: { "playerColor": "#ff3b30", "duration": 0.2 } }
gripforge_gamekit_install   { project_id: "gkp_…", id: "fx.ability_vfx" }
```

Only the keys that differ from the defaults need to be written. The full reference is `gripforge kit api <id>`.

## fx.hit_flash

It listens to `combat.damaged { target, amount, kind?, killed? }`, so any combat kit triggers it. Without this kit, the web renderer keeps
a plain white 0.08 s flash.

| Key | Default | Meaning |
| --- | --- | --- |
| `color` | `#ffffff` | flash colour of a hit entity |
| `playerColor` | `#ff5a4a` | flash colour when the player is hit |
| `duration` | 0.14 | seconds; the tint fades over that time (0.03 to 1) |
| `intensity` | 2.4 | peak emissive strength (0.2 to 8) |
| `punch` | 0.06 | scale added at the peak (0.06 is +6 %); 0 turns it off |
| `killBoost` | 1.6 | multiplier of intensity and duration on the killing blow |
| `minInterval` | 0.06 | seconds before the same entity flashes again |
| `onlyTags` | `[]` | flash only entities carrying one of these tags; empty means everything |
| `skipKinds` | `["status"]` | damage kinds that do not flash (damage over time by default) |
| `player` | `true` | the player flashes too |

Service `fx.flash`: `flash(entity, { color?, duration?, intensity?, punch? })` tints any entity for a moment: a heal in green, a pickup, a
parry. It emits the same event `fx.hit_flash` and uses the same renderer path. The time of the last flash is not saved.

## fx.ability_vfx

Bind a library effect to the slot `ability_vfx:<ability id>` (the ids of the `abilities` collection). It plays each time the ability
reaches the configured phase, on the event `ability.cue`. An ability without a bound effect plays nothing: the game keeps its own cast
feedback.

| Key | Default | Meaning |
| --- | --- | --- |
| `phase` | `active` | the ability phase that plays the effect: `windup`, `active`, or `hit` (on each target struck) |
| `scale` | 1 | size factor of every ability effect (0.1 to 10) |
| `fitArea` | `true` | area abilities scale their effect to the radius of the area |
| `authoredRadius` | 2.5 | radius in metres of the disc the effects are authored at; the divisor of the size of an area effect |

Where it plays:

| Ability shape | Position | Size |
| --- | --- | --- |
| self | on the caster | `scale` |
| arc, line | on the caster, turned along its facing | `scale` |
| circle | ahead of the caster by the ability's offset | radius / `authoredRadius` x `scale` when `fitArea` |
| phase `hit` | on each target struck | `scale` |

Service `fx.effects`: `play(slot, position, { yaw?, scale?, entity? })` plays any bound vfx slot at a point (an explosion on a death, a
pickup sparkle) with the same event, `fx.effect`, and the same renderer path.

## Modding and hooks

Every config key of both kits is moddable (a mod may recolour or retime the flash, change the phase or the scale of ability effects).
Whether an ability is cast is the decision of `combat.abilities`; whether a hit lands is the hook `combat.damage` of `combat.core`: a
hit that a tap cancels emits no `combat.damaged`, so nothing flashes.

```json
{ "schema": "gripforge.mod/1", "id": "red_flash", "name": "Red flash", "version": "1.0.0",
  "requires": { "fx.hit_flash": "^1" }, "config": { "fx.hit_flash": { "color": "#ff4040", "punch": 0.1 } } }
```

## When it does not do what you expect

| Symptom | Cause and fix |
| --- | --- |
| Nothing flashes | the damage kind is in `skipKinds`, `onlyTags` excludes the entity, or the hit was cancelled upstream |
| The ability plays no effect | no library effect is bound to `ability_vfx:<id>`, or `phase` is not the phase that fires |
| The area effect is the wrong size | `authoredRadius` differs from the radius the effect was authored at, or `fitArea` is `false` |
| The same entity flashes too often | raise `minInterval` |