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.

Source: module-kits:kits/fx_ability_vfx/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs fx-ability-vfxMCP tool: gripforge_docs { "topic": "fx-ability-vfx" }

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.

SettingTypeDefaultRange or valuesMeaning
phasestring"active"windup, active, hitAbility phase that plays the effect (hit: on each target struck).
scalenumber10.1–10Size factor of every ability effect.
fitAreabooleantrueArea abilities scale their effect to the radius of the area.
authoredRadiusnumber2.50.1–100Radius, 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 to slot once at position.

<!-- 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) #

CapabilityRequiredMethods
combat.abilitiesrequiredpack
engine.contentoptionalregisterComponent

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.