Voltar para o Blog
Quest Log

Hitstop na Godot 4: freeze frame no acerto com código

Espadachim de pixel art congelado no instante em que a lâmina acerta um inimigo, com faísca branca no ponto de impacto

Hitstop na Godot 4 em GDScript tipado: freeze frame global com Engine.time_scale, pausa local só no atacante e no alvo, timer real e as armadilhas.

Ferramenta:Godot

Hitstop na Godot 4 é o truque de game feel com a melhor relação custo e resultado que eu conheço: meia dúzia de linhas de GDScript e o golpe da sua espada deixa de parecer que atravessa papel. Neste tutorial eu mostro as duas formas de fazer o freeze frame no acerto, a global com Engine.time_scale e a local que congela só o atacante e o alvo, mais o timer que ignora a escala de tempo, a duração em frames e as armadilhas com áudio, partículas e input que aparecem logo no primeiro playtest.

Se você já tem hitbox e hurtbox funcionando, está pronto. Se ainda não, monte antes o knockback e a invencibilidade ao tomar dano, porque o hitstop entra exatamente no mesmo frame em que o dano é aplicado.

O que é hitstop e por que ele dá peso ao golpe

Hitstop é uma pausa de poucos frames no instante do acerto. A espada encosta no inimigo, os dois param por uns 60 ms e depois a animação segue, o inimigo voa para trás e as partículas saem. Jogos de luta usam isso desde sempre, e quase todo jogo de ação 2D moderno faz alguma versão.

O motivo de funcionar é perceptivo. Um golpe que acerta e continua no mesmo ritmo não deixa o olho registrar o contato: a lâmina passa e pronto. A pausa cria uma sensação de resistência, como se a arma tivesse batido em algo com massa. É o mesmo princípio que faz game feel e juice valerem tanto: o jogador não sabe dizer o que mudou, mas sente que o combate ficou mais sólido.

Tem um efeito colateral bom também. Durante o freeze o jogador ganha um respiro para ler o que aconteceu, o que deixa combos mais legíveis. O custo é tempo de ação: hitstop demais deixa o jogo arrastado. Por isso a duração precisa ser curta e proporcional ao golpe.

Hitstop global com Engine.time_scale

A forma mais simples é parar o jogo inteiro. Engine.time_scale multiplica o delta de todo o jogo: em 0.0, nada que dependa de delta anda. O problema clássico aparece na hora de voltar: se você usar um timer comum para restaurar a escala, ele também está congelado e nunca dispara.

A solução está na assinatura de SceneTree.create_timer na Godot 4:

create_timer(time_sec: float, process_always: bool = true, process_in_physics: bool = false, ignore_time_scale: bool = false) -> SceneTreeTimer

O quarto argumento, ignore_time_scale, faz o timer contar tempo real. É ele que resolve o hitstop. Crie um script hit_stop.gd e registre como autoload com o nome HitStop (Project Settings, aba Globals):

extends Node

var _global_until_ms: int = 0
var _saved_time_scale: float = 1.0


func global_stop(duration: float, scale: float = 0.0) -> void:
    var end_ms: int = Time.get_ticks_msec() + int(duration * 1000.0)
    # Se já existe um hitstop mais longo rodando, não encurta ele.
    if end_ms <= _global_until_ms:
        return
    # Só salva a escala original no primeiro hitstop, senão salvaria o 0.0.
    if _global_until_ms == 0:
        _saved_time_scale = Engine.time_scale
    _global_until_ms = end_ms
    Engine.time_scale = scale

    await get_tree().create_timer(duration, true, false, true).timeout

    # Um hitstop mais novo assumiu o controle: ele que restaura.
    if _global_until_ms != end_ms:
        return
    Engine.time_scale = _saved_time_scale
    _global_until_ms = 0

Três detalhes desse código evitam bug real:

  1. Hitstops sobrepostos. Num combo, dois acertos podem cair com 30 ms de diferença. Sem o controle por end_ms, o primeiro timer restauraria a escala no meio do segundo hitstop.
  2. Escala salva, não fixa em 1.0. Se o seu jogo já estava em câmera lenta quando o golpe acertou, restaurar para 1.0 mata o efeito. Salvar o valor anterior mantém o slow motion com time_scale intacto.
  3. process_always em true. O timer continua contando mesmo com a árvore pausada. Sem isso, um menu de pausa aberto no meio do hitstop deixaria o jogo preso em escala zero.

Para usar, chame no script do ataque, no momento em que o dano é aplicado:

func _on_hitbox_area_entered(area: Area2D) -> void:
    var target: Enemy = area.owner as Enemy
    if target == null:
        return
    target.take_damage(damage, global_position)
    HitStop.global_stop(0.07)

O global tem uma vantagem: é impossível esquecer algum node, tudo para junto. A desvantagem é a mesma frase: tudo para junto, inclusive a câmera, os outros inimigos e efeitos que você queria ver se mexendo.

Hitstop local: congelando só o atacante e o alvo

A versão local congela apenas quem participa do golpe. O resto do mundo continua, a câmera pode tremer durante o freeze e, num jogo com vários inimigos na tela, o acerto num deles não paralisa a batalha toda. Para isso uso process_mode.

Colocar um node em Node.PROCESS_MODE_DISABLED desliga _process, _physics_process e o input dele e de todos os filhos que herdam o modo. Isso inclui o AnimationPlayer e o AnimatedSprite2D do personagem, que é exatamente o que a gente quer: a animação para no frame do acerto.

Acrescente isto ao mesmo autoload:

var _frozen_modes: Dictionary = {}
var _frozen_until: Dictionary = {}


func freeze_nodes(nodes: Array[Node], duration: float) -> void:
    var end_ms: int = Time.get_ticks_msec() + int(duration * 1000.0)
    for node: Node in nodes:
        if not is_instance_valid(node):
            continue
        if not _frozen_modes.has(node):
            _frozen_modes[node] = node.process_mode
            node.process_mode = Node.PROCESS_MODE_DISABLED
        var current_until: int = _frozen_until.get(node, 0)
        _frozen_until[node] = maxi(end_ms, current_until)

    await get_tree().create_timer(duration, true, false, true).timeout

    for node: Node in nodes:
        if not _frozen_modes.has(node):
            continue
        # Outro freeze mais longo pegou esse node: deixa ele restaurar.
        if _frozen_until[node] != end_ms:
            continue
        if is_instance_valid(node):
            node.process_mode = _frozen_modes[node]
        _frozen_modes.erase(node)
        _frozen_until.erase(node)

O dicionário _frozen_modes guarda o process_mode original de cada node. Sem ele, um segundo freeze no mesmo inimigo salvaria PROCESS_MODE_DISABLED como "original" e o inimigo ficaria congelado para sempre. Esse é o bug mais comum de hitstop local, e aparece justamente quando o jogador acerta um combo rápido.

No ataque, troque a chamada:

HitStop.freeze_nodes([self, target], 0.07)

E o set_physics_process(false)?

Funciona, mas congela menos. set_physics_process(false) desliga só o callback de física daquele node. O AnimationPlayer filho continua tocando, então o sprite segue a animação enquanto o corpo fica parado. Para um freeze frame de verdade, process_mode é o caminho. Use set_physics_process quando quiser o efeito oposto: personagem parado no lugar, mas animação de impacto rodando.

Quanto tempo dura um hitstop: pense em frames

Medir em segundos esconde o que o jogador realmente vê. A 60 FPS, cada frame tem cerca de 16,7 ms. Valores que uso como ponto de partida:

GolpeFrames a 60 FPSSegundos
Leve (jab, primeiro hit do combo)3 a 50.05 a 0.08
Pesado6 a 90.10 a 0.15
Final de combo, parry, golpe crítico9 a 120.15 a 0.20

Mantenha os valores como constantes nomeadas para ajustar no playtest:

const HIT_STOP_LIGHT: float = 0.06
const HIT_STOP_HEAVY: float = 0.12
const HIT_STOP_FINISHER: float = 0.18

Uma regra que ajuda: o hitstop deve crescer com o dano, não com a animação. Um golpe lento que tira pouco dano com freeze longo parece bug. E repare que o hitstop do primeiro golpe do combo deve ser o menor de todos, senão o combo perde ritmo.

Combinando hitstop com camera shake e flash branco

Hitstop sozinho já melhora muito. Junto de tremor de tela e flash branco no alvo, o golpe ganha o pacote completo. A ordem que funciona, no mesmo frame do acerto: dano, flash, hitstop, shake.

@export var camera: Camera2D

func _on_hitbox_area_entered(area: Area2D) -> void:
    var target: Enemy = area.owner as Enemy
    if target == null:
        return
    target.take_damage(damage, global_position)
    target.flash_white(HIT_STOP_LIGHT)
    HitStop.freeze_nodes([self, target], HIT_STOP_LIGHT)
    camera.shake(4.0)

O shake aqui é o método do camera shake com tremor de tela. Repare que ele só treme durante o freeze porque a câmera não está na lista de nodes congelados. Com o hitstop global e time_scale em zero, um shake que usa delta ficaria parado até o tempo voltar, o que é um argumento forte a favor da versão local.

O flash tem uma pegadinha: o alvo está congelado, então um Tween criado com target.create_tween() também fica parado (Tweens ligados a um node seguem o processamento dele). O flash liga e só desliga depois do hitstop. Resolva desligando por um timer da árvore, que não depende do node:

func flash_white(duration: float) -> void:
    var mat: ShaderMaterial = sprite.material as ShaderMaterial
    mat.set_shader_parameter("flash_amount", 1.0)
    await get_tree().create_timer(duration, true, false, true).timeout
    if is_instance_valid(self):
        mat.set_shader_parameter("flash_amount", 0.0)

O shader com o parâmetro flash_amount está no tutorial de shader de hit flash no Godot 4. E se quiser ver a sequência completa de spark, flash, hitstop e shake frame a frame, o post de efeito de impacto 2D detalha a ordem.

Armadilhas: áudio, partículas e input

Áudio. Engine.time_scale não afeta a reprodução de áudio, então no hitstop global o som de impacto toca normal, o que é bom. No local, um AudioStreamPlayer2D filho do node congelado pode ser pausado junto e cortar o som do golpe. Toque o som de impacto num player fora da hierarquia congelada, ou ponha esse player com process_mode em PROCESS_MODE_ALWAYS, que sobrescreve a herança.

Partículas. Faíscas instanciadas como filhas do inimigo congelam com ele e viram um frame estático feio. Instancie o hit spark na raiz da fase (ou num node Effects) para ele animar durante o freeze. Se você quer o oposto, partícula parada durante a pausa, controle explicitamente com speed_scale em vez de depender da herança.

Input. Esse é o que mais gera reclamação de "controle duro". Com PROCESS_MODE_DISABLED, o player não recebe input durante o hitstop. E no global, com time_scale em zero, não há tick de física, então um Input.is_action_just_pressed lido em _physics_process pode simplesmente não ver o botão. Quem aperta o próximo golpe do combo durante o freeze perde o comando. A correção é um buffer de input num node que não congela:

extends Node

const BUFFER_MS: int = 150

var _attack_pressed_at: int = -1000


func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("attack"):
        _attack_pressed_at = Time.get_ticks_msec()


func consume_attack() -> bool:
    if Time.get_ticks_msec() - _attack_pressed_at <= BUFFER_MS:
        _attack_pressed_at = -1000
        return true
    return false

O player consulta consume_attack() quando volta a processar. Como o buffer usa Time.get_ticks_msec(), que é tempo real, ele funciona igual com qualquer escala de tempo.

Divisão por delta. Com time_scale em 0.0, delta chega como zero. Qualquer código que divide por delta (cálculo de velocidade a partir de deslocamento, por exemplo) gera infinito ou NaN. Se você tem esse tipo de conta, use 0.02 em vez de zero no hitstop global: visualmente é quase parado e o delta nunca zera.

É aqui que muita gente trava: o hitstop isolado funciona, mas somado a combo, knockback, i-frames, buffer de input e câmera, cada sistema quebra o outro de um jeito diferente. Montar essas peças sobre uma base organizada, com estados claros e responsabilidades separadas, é o que separa um protótipo que dá vontade de jogar de um que vira remendo.

Curso de Godot
Quer fazer seu primeiro jogo na Godot?

No curso de Godot da CursoGame.Dev você vai do zero ao primeiro jogo, com um desafio prático em cada level e suporte individual no WhatsApp quando travar.

Conhecer o curso de Godot
Suporte no WhatsAppAcesso vitalícioGarantia de 7 dias

Hitstop no parry e no golpe crítico

Hitstop não é só para dano comum. Os momentos que mais pedem freeze são os de recompensa: parry perfeito, golpe crítico, último inimigo da sala. Um freeze um pouco mais longo nesses casos sinaliza ao jogador que ele fez algo especial. O parry com bloqueio e escudo na Godot usa exatamente isso para vender o timing certo, e a versão para C# está no parry na Unity com janela de tempo.

Uma variação que funciona bem: hitstop diferente para atacante e alvo. O alvo congela o tempo cheio, o atacante congela um pouco menos e volta primeiro, o que deixa o jogador com sensação de controle. Com freeze_nodes basta duas chamadas:

HitStop.freeze_nodes([target], HIT_STOP_HEAVY)
HitStop.freeze_nodes([self], HIT_STOP_HEAVY * 0.6)

Resumo do hitstop na Godot 4 e próximos passos

Hitstop na Godot 4 se resume a duas escolhas. Global, com Engine.time_scale e create_timer(duracao, true, false, true) para restaurar no tempo real, quando você quer simplicidade e o jogo tem poucos elementos em tela. Local, com process_mode em PROCESS_MODE_DISABLED só no atacante e no alvo, quando você quer câmera, efeitos e o resto da cena vivos durante o freeze. Nos dois casos, proteja contra hitstops sobrepostos, meça em frames e cuide de áudio, partículas e input.

Se você ainda está decidindo em qual engine montar seu jogo de ação, a comparação completa entre Godot e Unity ajuda, e o hub de tutoriais de Godot reúne os outros posts de combate e game feel.

Perguntas frequentes

O que é hitstop em jogos?

Hitstop (ou hit stop, freeze frame) é uma pausa curtíssima, de alguns frames, no instante em que um golpe acerta. Atacante e alvo param por 50 a 150 ms e depois tudo volta a correr. A pausa dá tempo para o olho registrar o impacto e passa a sensação de que a arma encontrou algo sólido.

Como fazer hitstop na Godot 4?

Há dois jeitos. O global zera Engine.time_scale e restaura depois com get_tree().create_timer(duracao, true, false, true), em que o último argumento faz o timer ignorar a escala de tempo. O local troca o process_mode do atacante e do alvo para PROCESS_MODE_DISABLED e devolve o valor original quando o timer acaba.

Quanto tempo deve durar o hitstop?

Um bom ponto de partida a 60 FPS: 3 a 5 frames (50 a 80 ms) para golpe leve, 6 a 9 frames (100 a 150 ms) para golpe pesado ou golpe final de combo. Acima de uns 200 ms o jogador começa a ler a pausa como travamento.

Por que meu timer de hitstop nunca termina?

Porque ele roda no tempo escalado. Com Engine.time_scale em 0, um timer comum nunca avança. Passe ignore_time_scale como true no quarto argumento de SceneTree.create_timer, ou use um Tween com set_ignore_time_scale(true).