GS - Effects
A Godot asset that handles *any* type of effect. This is different than `fx`.
Status effects, temporary health and going down instead of dying, for Godot 4.7+. Burning, crits, invulnerability, slows, stuns and marks are one data document with different numbers, so a new effect is data and not a new class. Part of the gamespice-platform family. It needs only core.
The addon never changes a health value. A burning entity makes the manager emit damaged with an amount, and your game applies it the way it applies any damage, so a burn tick goes through the same armour and friendly-fire rules as a bullet. A slowed entity makes move_speed_scale() return less than 1, and your movement code reads it. Effects therefore work in a game with no damage system at all.
It has two related systems: temporary health that decays (overheal, pills), and being downed at zero health so a teammate can pick you up.
Install
- Copy
addons/dot_effects/andaddons/dot_core/into your project. - Enable dot-effects in Project > Project Settings > Plugins.
bootstrap clones every project and links the addons for you.
Quick start
var effects := DotEffectManager.new()
effects.setup()
add_child(effects)
effects.define(DotEffectDef.burning(&"afterburn", 3.0, 10 * 64)) # 3 damage every 32 ticks, for 10 seconds
effects.define(DotEffectDef.damage_buff(&"crit", 3.0, 5 * 64))
effects.define(DotEffectDef.invulnerability(&"invuln", 8 * 64))
effects.define(DotEffectDef.speed(&"adrenaline", 1.4, 15 * 64))
effects.damaged.connect(func(entity, amount, type, source):
health_of(entity).apply(DotDamage.make(amount, type, source, tick)))
effects.apply(&"afterburn", victim_id, attacker_id) # a DotResult; refused if the victim is immune
effects.advance(tick) # once per server tick
Entities are int ids. Ask the manager what an entity's effects add up to wherever you need it:
speed *= effects.move_speed_scale(id)
damage = effects.scale_damage(damage, attacker_id, victim_id) # crit on one side, a vulnerability on the other
if not effects.may_attack(id): return
There are also may_move, may_jump, may_capture, jump_scale, fire_rate_scale and is_invulnerable. Call on_death(id) when an entity dies and on_round_reset() between rounds, so effects marked to clear then are removed.
What an effect can do
The four factories above cover the common cases. Everything else is a field on DotEffectDef. The numbers are defaults.
| Field | Default | What it does |
|---|---|---|
duration_ticks |
640 | How long it lasts (10 seconds at 64 ticks). |
stacking |
REFRESH |
A second application: REFRESH the duration, EXTEND it, STACK another beside it, or IGNORE it. |
max_stacks, max_duration_ticks |
1, 0 | Limits for STACK and EXTEND. 0 means no limit. |
per_source |
false | Each attacker gets their own instance, such as a bleed from two players. |
tick_interval |
32 | How often the periodic part fires. |
damage_per_tick, damage_type |
0, none | Damage each interval, and its type. |
heal_per_tick, heal_overheals |
0, false | Healing each interval, and whether it can go over the maximum. |
damage_taken_scale, damage_dealt_scale |
1.0 | Damage multipliers in each direction. |
ignores_falloff |
false | Tells your damage code to skip distance falloff. Read it with state_of(id).ignores_falloff(). |
move_speed_scale, jump_scale, fire_rate_scale |
1.0 | Movement, jump and fire rate multipliers. |
invulnerable |
false | Takes no damage. |
no_attack, no_move, no_jump, no_capture |
false | What the entity cannot do, such as a stun or a freeze. |
cures, immune_to |
none | Tags this effect removes when applied, and tags it refuses while active. |
clear_on_death, clear_on_round |
true | Removed on death, and between rounds. |
Downed instead of dead
Turn on rules.downed_enabled, then ask the manager what should happen whenever an entity reaches zero health:
var what := effects.report_zero_health(entity)
if str(what.value) == "down":
player.play_downed()
else:
player.die()
By default a downed player bleeds out over about 90 seconds. A teammate who holds revive on them for 5 seconds (begin_revive(entity, by)) brings them back with 30 health. Moving away, or being downed, cancels the revive and loses the progress. The bleed keeps draining while a revive is held, so a rescue started in the last seconds is a gamble. By default the third time down is death. position_fn and allies_fn let the manager check that the reviver is close enough and on the same side. defibrillate() brings somebody back from dead.
Settings
The rules live in a DotEffectRules resource on the manager's rules. The manager makes a default one if you set none. Values layer in the usual order: inspector defaults, a JSON file, the environment, then the command line. Call load_layered() before setup():
var rules := DotEffectRules.new()
rules.load_layered("user://effects.json")
effects.rules = rules
DOT_EFFECTS_DOWNED_ENABLED=true godot --headless -- --effects-downed-max-incaps=3
All numbers are defaults and all are configurable. Ticks assume 64 a second.
| Setting | Default | What it does |
|---|---|---|
max_per_entity |
24 | Most effects one entity can hold at once. A further one is refused. Default 24, 0 = unlimited; negative is refused by validate(). |
allow_stacking |
true | Off makes every STACK effect refresh instead. |
downed_enabled |
false | Go down at zero health instead of dying. |
downed_health |
300 | The pool a downed player bleeds through. |
downed_bleed_per_tick |
0.052 | How fast it drains (about 90 seconds). |
downed_revive_ticks |
320 | How long a revive takes (5 seconds). |
downed_revive_health |
30 | Health a revived player comes back with. |
downed_revive_radius |
2.0 | How close the reviver must stay. 0 skips the check. |
downed_revive_scales |
false | More revivers make it faster. A second begin_revive joins instead of replacing, and leave_revive(entity, by) lets one go while the rest carry on. |
downed_max_incaps |
2 | Revives before the next down is death. 0 is unlimited. The inspector slider runs 0 to 64. |
downed_defib_health |
50 | Health after defibrillate(). 0 turns it off. |
temp_decay_per_tick |
0.1 | How fast temporary health drains. 0 keeps it. |
temp_grace_ticks |
0 | Ticks after a top-up before it starts to drain. |
The design is in docs/design.md.
Test
godot --headless --path . --import
godot --headless --path . res://examples/effects_selftest.tscn
The self-test is offline and exits non-zero on any failure.
Status
Built and maintained with Claude Code. The test suites pass, but little of this has been in front of real players yet. Please report rough edges by opening an issue.
Licence
MIT. See LICENSE. Only the TMC back-end web infrastructure is not open source.
Engagement Over Time
GS - Effects is a Godot asset. It has 1 download, 47 views, and 0 favorites. This item belongs to 1 collection and 2 tags.
Reviews
Log in to leave a review.
Comments (0)
Log in to comment.
