# Ability Effects (fx.ability_vfx)

## What it is for

Plays a library effect when an ability fires, on the caster, ahead of it or on the targeted area, turned the way the caster faces.

It needs `combat.abilities`, `game.engine`; installing it brings them in.

## Turn it on

Install the kit in a project, then change a setting (the values shown are its defaults):

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "fx.ability_vfx" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "fx.ability_vfx",
                              config: { "phase": "active", "scale": 1 } }
```

## First example

<!-- test: kits/game_engine/host/tests/fx_ability_vfx.rs::the_hit_phase_plays_on_each_target -->
This is the body of the passing test `the_hit_phase_plays_on_each_target`; the helper functions it calls are defined at the top of the same test file.

```rust
#[test]
fn the_hit_phase_plays_on_each_target() {
    let mut s = session(json!({ "phase": "hit", "scale": 1.5, "fitArea": false }));
    let played = cue(
        &mut s,
        json!({ "source": "e1", "ability": "nova", "phase": "hit", "target": "e2" }),
    );
    assert_eq!(played.len(), 1);
    // On the target, turned as the caster faces, not sized to the area.
    assert!(near(&played[0]["position"][0], 9.0) && near(&played[0]["position"][2], 9.0));
    assert!(near(&played[0]["yaw"], PI / 2.0) && near(&played[0]["scale"], 1.5));
    assert_eq!(played[0]["entity"], json!("e1"));
    // Without a target the effect stays on the caster.
    let own = cue(
        &mut s,
        json!({ "source": "e1", "ability": "bolt", "phase": "hit" }),
    );
    assert!(near(&own[0]["position"][0], 1.0));
}
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `phase` | string | `"active"` | `windup`, `active`, `hit` | Ability phase that plays the effect (hit: on each target struck). |
| `scale` | number | `1` | 0.1–10 | Size factor of every ability effect. |
| `fitArea` | boolean | `true` |  | Area abilities scale their effect to the radius of the area. |
| `authoredRadius` | number | `2.5` | 0.1–100 | Radius, in metres, of the disc the effects are authored at: an area ability of that radius plays its effect at scale. |

## Services, events, variables

- Service `fx.effects`: play(slot, position, { yaw?, scale?, entity? }) - a one-shot Library effect at a point.
- Events emitted:
  - `fx.effect` (`slot`, `position`, `yaw`, `scale`, `entity`) — The renderer plays the effect bound to `slot` once at `position`.
- Events listened to: `ability.cue`

## Hooks and modding

- Moddable settings: `phase`, `scale`, `fitArea`, `authoredRadius`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api fx.ability_vfx` lists the exact settings and services of your version.

## Versions

Kit version 1.1.0.