Ability Effects
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.
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):
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.
#[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?, clock? }) - a one-shot Library effect at a point; attach(entity, slot, { offset?, yaw?, scale? }) and detach(entity, slot?) - an effect that loops on an entity (1.3). - Events emitted:
fx.effect(slot,position,yaw,scale,entity,clock) — The renderer plays the effect bound toslotonce atposition.
<!-- test: kits/game_engine/host/tests/fx_ability_vfx.rs::an_effect_on_the_clock_of_the_frames_says_so --> An effect ages with the game time, so a paused game holds its effects. Pass clock: "real" to play for an effect that must play while the game is paused (a cinematic, a menu): it ages on the frames and fx.effect carries clock: "real".
- Events listened to:
ability.cue
Effects that loop on an entity (1.3) #
<!-- test: kits/game_engine/host/tests/fx_ability_vfx.rs::an_attached_effect_is_a_component_the_service_changes --> An effect can loop on an entity and follow it: the smoke of a chimney, the steam of a boiler, the plume of an airship. Give the archetype (or one instance) the component fx.attach, one emitter or a list of up to 8:
{ "id": "airship", "kind": "prop", "asset": { "item": "lib_…" },
"components": { "fx.attach": [{ "slot": "smoke", "offset": [0, 6, -3], "scale": 2 }] } }
slot names an effect of the config effects; offset is in metres in the frame of the entity, yaw turns the effect on top of its facing, scale sizes it. At run time, attach(entity, slot, { offset?, yaw?, scale? }) of the service fx.effects adds an emitter (the one of the same slot is replaced) and detach(entity, slot?) removes it, or every one. The presentation module plays each emitter in a loop over the duration of its effect, as long as the component is there; attached and one-shot effects share 32 places. The component is saved with the entity.
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.3.0 (since 2026-10-31: effects that loop on an entity, component fx.attach). 1.2.0 (2026-10-29): clock: "real" for effects that play while the game is paused.
<!-- kit-services:begin -->
Services this kit uses (and that you can provide) #
| Capability | Required | Methods |
|---|---|---|
combat.abilities | required | pack |
engine.content | optional | registerComponent |
Any brick can serve them: a kit, or your engine (Godot provide_service, Unity Provide, Unreal ProvideService, Bevy provide_kit_service, C gfk_provide) — see the guide. <!-- kit-services:end -->
Finite emitter profiles (1.4) #
emitterProfiles is an array of reusable { id, duration, fadeIn, fadeOut } envelopes. An fx.attach emitter or attach call selects profile; explicit fields override it. The kit stores startedAt on creation. Fades follow simulation time independently of the particle loop, survive save/load, pause with gameplay and release their drawing slot at expiry. Duration is at most 600 seconds; zero or omitted keeps the old infinite loop. Profiles are resolved at attachment, so later edits affect new emitters.