Combat effects
Usage guide of fx.hit_flash and fx.ability_vfx: the flash on a hit, the effect bound to an ability, settings and defaults, services, modding.
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 #
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.
{ "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 |