Godot: Sistema de Status Effects (Buff e Debuff) do Zero

Veneno que drena vida a cada segundo, queimadura que empilha, atordoamento que trava o controle, um buff que aumenta seu ataque por dez segundos. Isso e a espinha dorsal de quase todo RPG, roguelike ou jogo de combate. Montar status effects no Godot 4 do zero nao e difícil, mas quase todo mundo comeca escrevendo um bool esta_envenenado no personagem e, três efeitos depois, tem um script cheio de flags que ninguem entende. Neste tutorial a gente resolve isso direito: um Resource tipado que descreve cada efeito (buff ou debuff) e um node gerenciador que aplica, processa e remove tudo sozinho.

A ideia central e a mesma que sustenta código limpo em qualquer sistema de jogo: separar o que um efeito e do que o efeito faz. O "e" (nome, duracao, dano por tick, se empilha) vira dado num Resource. O "faz" (contar tempo, aplicar dano periodico, avisar quando acabou) vira lógica num node. Com essa divisao, adicionar um novo efeito e criar um arquivo, nao reescrever o personagem.

Definindo o efeito com um Resource tipado

Comece pela definicao. Um status effect no Godot funciona muito bem como Resource, porque e dado puro, editável no Inspector e salvável em .tres. Repare que tudo e tipado, do enum ao array.

class_name StatusEffect
extends Resource

enum Tipo { BUFF, DEBUFF }

@export var id: StringName = &""
@export var nome: String = ""
@export var tipo: Tipo = Tipo.DEBUFF

## Quanto tempo o efeito dura, em segundos.
@export var duracao: float = 5.0

## Dano (positivo) ou cura (negativo) aplicado a cada tick.
@export var dano_por_tick: int = 0

## Intervalo entre ticks, em segundos. Use 0 para efeitos sem tick.
@export var intervalo_tick: float = 1.0

## Se true, aplicar de novo soma intensidade. Se false, so renova a duracao.
@export var empilha: bool = false

## Limite de stacks quando empilha e true.
@export var max_stacks: int = 5

## Modificadores de atributo enquanto o efeito estiver ativo.
@export var mod_ataque: int = 0
@export var mod_velocidade: float = 0.0

## Se true, trava o controle do personagem (atordoamento, congelamento).
@export var atordoa: bool = false

Cada campo é uma decisao de design que vira um slider no Inspector. Um veneno é tipo = DEBUFF, dano_por_tick = 3, intervalo_tick = 1.0, empilha = true. Um buff de fúria é tipo = BUFF, dano_por_tick = 0, mod_ataque = 10, empilha = false. Um atordoamento é atordoa = true, duracao = 1.5, e nada mais. O mesmo Resource cobre os três porque descreve dado, nao comportamento.

Salve o script, clique com o botao direito numa pasta no FileSystem, escolha Create New > Resource, busque StatusEffect e preencha os valores. Cada .tres é um efeito pronto para arrastar em qualquer lugar do projeto.

O estado de runtime: uma instancia ativa do efeito

Aqui entra a pegadinha mais comum de quem usa Resource: ele é compartilhado por referencia. Se voce contar a duracao dentro do próprio StatusEffect, todos os personagens que usam veneno.tres compartilham o mesmo contador, e o sistema quebra silenciosamente. A regra é: a definicao nunca guarda estado de runtime. O tempo restante e o número de stacks vivem numa classe separada.

class_name EfeitoAtivo
extends RefCounted

var dados: StatusEffect          # referencia compartilhada, so leitura
var tempo_restante: float = 0.0  # estado proprio desta instancia
var acumulador_tick: float = 0.0
var stacks: int = 1

func _init(p_dados: StatusEffect) -> void:
    dados = p_dados
    tempo_restante = p_dados.duracao

O EfeitoAtivo estende RefCounted, entao nao precisa de queue_free() nem entra na árvore de cena. Ele guarda o que muda quadro a quadro (tempo restante, acumulador do tick, stacks) e aponta para o dados que nunca muda. É o mesmo padrao definicao mais estado que sustenta inventário e qualquer sistema data-driven no Godot.

O node gerenciador: aplicar, processar e remover

Agora o coracao do sistema. O StatusEffectManager é um Node filho do personagem. Ele guarda os efeitos ativos, processa duracao e tick a cada frame no _process, cuida de empilhar contra renovar, remove ao expirar e emite sinais para o resto do jogo reagir.

class_name StatusEffectManager
extends Node

signal efeito_aplicado(efeito: EfeitoAtivo)
signal efeito_removido(dados: StatusEffect)
signal tick_aplicado(dados: StatusEffect, dano: int)

var _ativos: Array[EfeitoAtivo] = []

func aplicar(dados: StatusEffect) -> void:
    var existente: EfeitoAtivo = _buscar(dados.id)
    if existente != null:
        if dados.empilha and existente.stacks < dados.max_stacks:
            existente.stacks += 1
        # Empilhando ou nao, aplicar de novo sempre renova a duracao.
        existente.tempo_restante = dados.duracao
        return
    var novo := EfeitoAtivo.new(dados)
    _ativos.append(novo)
    efeito_aplicado.emit(novo)

func _buscar(id: StringName) -> EfeitoAtivo:
    for efeito in _ativos:
        if efeito.dados.id == id:
            return efeito
    return null

O método aplicar é onde stack e renovacao acontecem. Se o efeito ainda nao existe, cria um EfeitoAtivo e emite o sinal. Se ja existe e o Resource permite empilhar, soma um stack (respeitando o max_stacks) e reinicia a duracao. Se ja existe e nao empilha, so renova o tempo. Um único if resolve os três casos que quase todo mundo trata com código duplicado.

Falta o loop que faz o tempo andar. Ele roda todo frame, desconta o delta da duracao, aplica dano por tick no intervalo certo e remove o que expirou.

func _process(delta: float) -> void:
    # Itera de tras para frente porque removemos itens durante o loop.
    for i in range(_ativos.size() - 1, -1, -1):
        var efeito: EfeitoAtivo = _ativos[i]
        _processar_tick(efeito, delta)
        efeito.tempo_restante -= delta
        if efeito.tempo_restante <= 0.0:
            _remover_no_indice(i)

func _processar_tick(efeito: EfeitoAtivo, delta: float) -> void:
    if efeito.dados.intervalo_tick <= 0.0 or efeito.dados.dano_por_tick == 0:
        return
    efeito.acumulador_tick += delta
    while efeito.acumulador_tick >= efeito.dados.intervalo_tick:
        efeito.acumulador_tick -= efeito.dados.intervalo_tick
        var dano: int = efeito.dados.dano_por_tick * efeito.stacks
        tick_aplicado.emit(efeito.dados, dano)

func _remover_no_indice(indice: int) -> void:
    var dados: StatusEffect = _ativos[indice].dados
    _ativos.remove_at(indice)
    efeito_removido.emit(dados)

Dois detalhes valem atencao. O loop itera de trás para frente (_ativos.size() - 1 até 0) porque removemos itens dentro dele, e remover de um array enquanto avança para frente pula elementos. E o tick usa um acumulador de delta, nao um Timer: o while cobre o caso raro de um frame gigante que passa dois intervalos de uma vez, sem perder ticks. Repare que o dano do tick é multiplicado por stacks, entao dois venenos empilhados doem o dobro sem código extra.

Integrando com a vida do personagem

O gerenciador nunca toca na vida direto. Ele avisa por sinal, e o personagem decide o que fazer. Esse desacoplamento é o que deixa o sistema reutilizável: o mesmo StatusEffectManager serve para o player, para inimigos e para NPCs, cada um reagindo do seu jeito.

extends CharacterBody2D

@export var vida_maxima: int = 100
@export var ataque_base: int = 10
@export var velocidade_base: float = 200.0

var vida: int = 100

@onready var status: StatusEffectManager = $StatusEffectManager

func _ready() -> void:
    vida = vida_maxima
    status.tick_aplicado.connect(_on_tick_aplicado)

func _on_tick_aplicado(dados: StatusEffect, dano: int) -> void:
    # dano positivo tira vida (veneno), negativo cura (regeneracao).
    vida = clampi(vida - dano, 0, vida_maxima)
    if vida <= 0:
        morrer()

Do lado do dano por tick, o personagem só assina tick_aplicado e ajusta a vida. Um dano_por_tick positivo drena (veneno, queimadura), negativo cura (um buff de regeneracao). O clampi evita vida negativa ou passar do máximo. Se a fonte do veneno for um golpe do seu sistema de combate corpo a corpo, basta chamar alvo.status.aplicar(veneno) no momento do acerto, e todo o resto acontece sozinho.

Para buffs e debuffs que alteram atributos (ataque, velocidade), nao escreva no valor base. Guarde o base separado e recalcule o valor final somando os modificadores dos efeitos ativos. Assim, quando o buff expira, o atributo volta sozinho, porque o modificador simplesmente deixou de existir no cálculo.

func ataque_atual() -> int:
    var total: int = ataque_base
    for efeito in status.get_ativos():
        total += efeito.dados.mod_ataque * efeito.stacks
    return total

func velocidade_atual() -> float:
    var total: float = velocidade_base
    for efeito in status.get_ativos():
        total += efeito.dados.mod_velocidade
    return total

Para isso funcionar, exponha os ativos no gerenciador com um getter simples que devolve a lista sem deixar ninguem mexer nela por engano:

func get_ativos() -> Array[EfeitoAtivo]:
    return _ativos

Atordoamento: status effects no Godot que travam o controle

Nem todo status effect no Godot é dano ou modificador. O atordoamento, o congelamento e a paralisia bloqueiam a acao do personagem. Como o StatusEffect ja tem o campo atordoa, o personagem só precisa perguntar ao gerenciador se algum efeito ativo trava o controle antes de ler o input.

func esta_atordoado() -> bool:
    for efeito in status.get_ativos():
        if efeito.dados.atordoa:
            return true
    return false

func _physics_process(delta: float) -> void:
    if esta_atordoado():
        velocity = Vector2.ZERO
        move_and_slide()
        return
    # aqui entra seu movimento normal de input
    velocity.x = Input.get_axis("esquerda", "direita") * velocidade_atual()
    move_and_slide()

Enquanto houver um efeito com atordoa = true na lista, o input é ignorado. Quando o atordoamento expira (o _process do gerenciador remove ele e emite efeito_removido), esta_atordoado() volta a retornar false e o controle retorna sozinho. Esse tipo de troca de comportamento, controlável contra travado, é justamente o que uma maquina de estados (state machine) no Godot organiza com elegancia: em vez de espalhar if por vários métodos, o atordoamento vira um estado próprio que ignora input, e o gerenciador de status apenas dispara a transicao.

Aplicando e testando o sistema

Com as pecas no lugar, usar é trivial. Crie os .tres dos efeitos, referencie no código e chame aplicar.

@export var veneno: StatusEffect
@export var furia: StatusEffect

func _ready() -> void:
    status.aplicar(veneno)   # comeca a drenar vida por tick
    status.aplicar(furia)    # aumenta o ataque enquanto durar
    status.aplicar(veneno)   # empilha: agora o veneno doi o dobro

Antes de espalhar isso pelo jogo, monte uma cena de teste com um único personagem e conecte os três sinais a um print. Verifique quatro coisas: o veneno tira vida no intervalo certo, aplicar de novo empilha (ou renova, conforme o Resource), o buff de ataque some quando a duracao acaba e o atordoamento devolve o controle ao expirar. Se os quatro passam, o sistema está redondo.

O ganho de longo prazo é o mesmo de todo bom design de dados no Godot: efeito novo é arquivo novo, nao código novo. Uma queimadura que empilha, um lentidao que corta a velocidade pela metade, um escudo que reduz dano recebido, tudo vira mais um .tres e, no máximo, um campo a mais no Resource. Se você está montando esses sistemas ainda aprendendo a estruturar código de jogo, vale seguir uma base organizada como a trilha de Godot para iniciante, porque status effects, combate e máquina de estados são exatamente os pontos onde arquitetura fraca cobra caro mais tarde.

Pega o gerenciador deste tutorial, pluga no seu personagem e cria três efeitos: um veneno que empilha, um buff de ataque e um atordoamento. No dia em que você adicionar o décimo efeito em dois minutos, sem tocar no personagem, o padrao se paga.