Voltar para o Blog
Quest Log

Spine na Godot 4: Instale o Runtime e Toque Animações

Personagem 2D com esqueleto de ossos aparecendo na janela de cena de uma engine, com o painel de inspetor aberto ao lado

Spine na Godot 4 passo a passo: instale o runtime spine-godot, importe .skel e .atlas, monte o SpineSprite e controle animações e eventos por GDScript.

Usar Spine na Godot 4 deixou de ser gambiarra faz tempo: a própria Esoteric Software, empresa que faz o Spine, mantém um runtime oficial chamado spine-godot. Com ele você importa o esqueleto exportado do editor, coloca um nó SpineSprite na cena e controla as animações por GDScript, com mistura entre animações, várias trilhas ao mesmo tempo e eventos disparados no meio do movimento, como o som do passo batendo no chão no frame certo.

Este post é o passo a passo prático: instalar o runtime, exportar do jeito certo, montar o nó na cena e escrever o controle do personagem. Se você ainda não decidiu se o Spine faz sentido para o seu jogo, leia antes o post sobre animação 2D com Spine, que compara o fluxo esqueletal com o quadro a quadro e mostra quando cada um vale a pena.

Spine na Godot 4: as duas formas de instalar o runtime

O spine-godot existe em dois formatos para a Godot 4, e a escolha depende de uma pergunta só: você programa em GDScript ou em C#?

GDExtension (recomendado para GDScript). Você baixa o pacote da extensão na página do spine-godot no site oficial do Spine, descompacta e copia a pasta bin/ para a raiz do seu projeto. O resultado é um arquivo em seu-projeto/bin/spine_godot_extension.gdextension. Ao abrir o projeto, a Godot carrega a extensão e os nós do Spine aparecem na lista de nós. Você continua usando a Godot oficial, sem editor customizado. A limitação: a GDExtension não tem bindings para C#.

Editor pré-compilado com o módulo (para C#). A Esoteric também distribui builds da Godot com o módulo do Spine compilado dentro do motor, junto com os export templates correspondentes. Você instala os templates em Editor > Gerenciar Modelos de Exportação, usando a opção de instalar a partir de arquivo. Esse caminho suporta C#, ao custo de você ficar preso à versão da Godot que a Esoteric compilou.

Para a maior parte dos projetos indie em GDScript, a GDExtension é o caminho com menos atrito. Ela também facilita atualizar a Godot sem esperar um build customizado novo, desde que a extensão seja compatível com a versão.

Um aviso que economiza horas: a versão do runtime precisa bater com a versão do editor Spine usada para exportar. Esqueleto exportado no Spine 4.2 deve ser lido pelo runtime 4.2. Se trocar a versão maior do runtime, reexporte tudo com o editor correspondente. A documentação oficial tem um guia de versionamento, e vale consultá-lo antes de qualquer atualização.

Exportar do Spine do jeito que a Godot entende

No editor Spine, o export que a Godot precisa tem três partes:

  1. Dados do esqueleto: exporte em binário (.skel). É o formato recomendado pela documentação, menor e mais rápido de carregar. Se usar JSON, salve com a extensão .spine-json, não .json, porque o importador do runtime identifica o arquivo pela extensão.
  2. Atlas de textura: marque a opção de empacotar o atlas no export. Ela gera um arquivo .atlas com as coordenadas de cada parte.
  3. Páginas do atlas: as imagens .png geradas junto com o .atlas.

Copie os três para uma pasta do projeto, por exemplo res://personagens/heroi/. Ao detectar os arquivos, a Godot importa o esqueleto como um recurso de arquivo de esqueleto, o atlas como um recurso de atlas e os PNGs como texturas normais.

Uma dica de organização que ajuda muito depois: nomeie as animações no Spine exatamente como vai chamá-las no código (idle, run, jump, attack) e mantenha o padrão em todos os personagens. Você vai referenciar esses nomes como texto no GDScript, e um Run com maiúscula em um personagem e run no outro vira bug silencioso.

Se a arte do personagem ainda não está separada em partes, resolva isso antes de abrir o Spine: desenhe pensando nas juntas, deixe sobra nas áreas que se sobrepõem e organize uma camada por parte.

Montar o SpineSprite na cena

Com os arquivos importados, a montagem tem dois passos.

Primeiro, crie um SpineSkeletonDataResource. No painel Sistema de Arquivos, crie um novo recurso desse tipo e salve, por exemplo, como heroi_data.tres. No inspetor, aponte o campo de atlas para o recurso .atlas importado e o campo de dados do esqueleto para o .skel. Esse recurso junta as duas coisas e pode ser compartilhado por quantos nós você quiser: dez inimigos iguais usam o mesmo recurso, e os dados ficam carregados uma vez só.

É também nesse recurso que você configura os tempos de mistura (mix) entre animações pelo inspetor. Por exemplo: de idle para run com 0,2 segundo de transição. Sem mix, a troca de animação é seca e o personagem "pula" de pose; com mix curto, ela fica suave.

Depois, adicione um nó SpineSprite e aponte a propriedade de dados do esqueleto para o heroi_data.tres. O personagem aparece na viewport. Em um jogo de plataforma, a estrutura mais comum é um CharacterBody2D como raiz, com a colisão e um SpineSprite como filho cuidando só da parte visual.

Além do SpineSprite, o runtime traz outros nós úteis: SpineBoneNode, que lê ou controla a posição de um osso (bom para prender uma arma na mão), SpineSlotNode, que insere nós da Godot dentro da ordem de desenho de um slot, e SpineAnimationTrack, que integra a animação do Spine com o AnimationPlayer da Godot para cutscenes.

Tocar animações por GDScript

O controle passa pelo SpineAnimationState, que você pega com get_animation_state(). Os dois métodos que você mais vai usar são:

  • set_animation(nome, loop, trilha): troca imediatamente a animação daquela trilha.
  • add_animation(nome, atraso, loop, trilha): enfileira uma animação para tocar depois da atual, com um atraso em segundos.

Aqui vai um controle de personagem de plataforma completo, com o SpineSprite como filho de um CharacterBody2D:

extends CharacterBody2D

const VELOCIDADE: float = 180.0
const FORCA_PULO: float = -420.0

@onready var visual: SpineSprite = $SpineSprite

var gravidade: float = ProjectSettings.get_setting("physics/2d/default_gravity")
var animacao_atual: String = ""

func _ready() -> void:
    _tocar("idle", true)

func _physics_process(delta: float) -> void:
    if not is_on_floor():
        velocity.y += gravidade * delta
    if Input.is_action_just_pressed("ui_accept") and is_on_floor():
        velocity.y = FORCA_PULO
    var direcao: float = Input.get_axis("ui_left", "ui_right")
    velocity.x = direcao * VELOCIDADE
    move_and_slide()
    _atualizar_visual(direcao)

func _atualizar_visual(direcao: float) -> void:
    if direcao != 0.0:
        visual.get_skeleton().set_scale_x(signf(direcao))
    if not is_on_floor():
        _tocar("jump", false)
    elif direcao != 0.0:
        _tocar("run", true)
    else:
        _tocar("idle", true)

func _tocar(nome: String, em_loop: bool) -> void:
    if nome == animacao_atual:
        return
    animacao_atual = nome
    visual.get_animation_state().set_animation(nome, em_loop, 0)

Dois detalhes importam aqui. O primeiro é a guarda em _tocar: sem ela, set_animation seria chamado a cada frame de física, reiniciando a animação e deixando o personagem congelado no primeiro frame. O segundo é o espelhamento: em vez de inverter o nó inteiro, o código inverte a escala do esqueleto com get_skeleton().set_scale_x(), que é o jeito usado nos exemplos oficiais.

Trilhas: atirar enquanto corre

O Spine trabalha com trilhas (tracks), e é aí que ele ganha muito do sprite sheet. A trilha 0 cuida do corpo (idle, run, jump). Uma trilha 1 pode tocar por cima uma animação que só mexe nos braços, como atirar, sem interromper a corrida.

func atirar() -> void:
    var estado: SpineAnimationState = visual.get_animation_state()
    estado.set_animation("shoot", false, 1)
    estado.add_empty_animation(1, 0.2, 0.0)

add_empty_animation(trilha, mix, atraso) enfileira uma animação vazia na trilha 1 com 0,2 segundo de mistura, fazendo os braços voltarem suavemente para o que a trilha 0 estiver tocando. Para isso funcionar bem, a animação shoot no editor Spine deve ter chaves só nos ossos dos braços. Se ela tiver chave nas pernas, vai brigar com a corrida.

Com sprite sheet, a mesma combinação exigiria desenhar "correr atirando", "pular atirando" e "parado atirando" como animações separadas. Esse é um dos motivos mais concretos para adotar esqueletal em jogo de ação.

Eventos: som de passo e hitbox no frame certo

Eventos são marcadores que o animador coloca na linha do tempo do Spine, como footstep no frame em que o pé toca o chão ou hit no frame em que a espada atinge o ponto máximo. O SpineSprite emite o sinal animation_event quando a animação passa por eles.

@onready var som_passo: AudioStreamPlayer2D = $SomPasso
@onready var hitbox: Area2D = $Hitbox

func _ready() -> void:
    visual.animation_event.connect(_on_animation_event)
    visual.animation_completed.connect(_on_animation_completed)

func _on_animation_event(_sprite: SpineSprite, _estado: SpineAnimationState, _entrada: SpineTrackEntry, evento: SpineEvent) -> void:
    var nome: String = evento.get_data().get_event_name()
    if nome == "footstep":
        som_passo.play()
    elif nome == "hit":
        hitbox.monitoring = true

func _on_animation_completed(_sprite: SpineSprite, _estado: SpineAnimationState, entrada: SpineTrackEntry) -> void:
    if entrada.get_animation().get_name() == "attack":
        hitbox.monitoring = false

Esse padrão tira do código o trabalho de adivinhar tempo. Se o animador deixar o ataque mais lento, o evento hit anda junto e o dano continua saindo no frame certo, sem ninguém mexer em timer. Um cuidado da documentação: não guarde referências ao SpineTrackEntry fora da função que o recebeu, porque o runtime reaproveita esses objetos internamente.

Problemas comuns e como resolver

O esqueleto não carrega ou aparece quebrado. Quase sempre é versão diferente entre editor e runtime. Confira a versão do Spine usada no export e a do runtime instalado.

O arquivo JSON não é reconhecido. Renomeie para .spine-json. Com .json, a Godot trata como JSON genérico.

A animação fica travada no primeiro frame. Você está chamando set_animation todo frame. Guarde a animação atual e só troque quando mudar, como no exemplo.

A troca entre animações é seca. Configure os tempos de mix no SpineSkeletonDataResource.

Personagem pequeno demais ou gigante. Ajuste a escala no export do Spine ou a escala do SpineSprite, e mantenha a mesma referência para todos os personagens do jogo.

Integrar o Spine na engine é a parte técnica e documentada. A parte que mais trava quem está começando é a anterior: desenhar o personagem com proporção, separar as partes com sobra nas juntas e animar com peso e intenção. Sem essa base de arte, o melhor runtime do mundo só toca animação dura com mais eficiência. Não por acaso, estúdio contrata animador de jogos pelo senso de movimento e pela arte, não por saber instalar plugin.

Curso de Arte 2D
Quer fazer a arte do seu jogo?

No curso de Arte 2D para Jogos da CursoGame.Dev você vai do rabisco ao portfólio: personagens, cenários, tilesets, UI e animação, sem precisar saber desenhar.

Conhecer o curso de Arte 2D
Suporte no WhatsAppAcesso vitalícioGarantia de 7 dias

Próximo passo

Com o personagem rodando e respondendo ao controle, o passo seguinte natural é usar skins para trocar roupa, arma e até o personagem inteiro sem duplicar animação. O post sobre skins no Spine mostra como montar isso no editor e combinar skins por código na Godot, o que abre caminho para customização de personagem e variações de inimigo com o mesmo esqueleto.

Perguntas frequentes

O Spine funciona na Godot 4?

Sim. A Esoteric Software, empresa do Spine, mantém o runtime oficial spine-godot, que funciona na Godot 4 de duas formas: como GDExtension, que você copia para a pasta do projeto, ou como um editor da Godot pré-compilado com o módulo do Spine embutido. A GDExtension é o caminho mais simples para GDScript; o editor pré-compilado é o caminho para quem usa C#.

Qual formato exportar do Spine para a Godot?

Exporte os dados do esqueleto em binário (.skel), que é o formato recomendado, junto com o arquivo .atlas e as imagens .png do atlas. Se preferir JSON, salve com a extensão .spine-json em vez de .json, porque é essa extensão que o importador do runtime reconhece.

Preciso de licença do Spine para usar o runtime na Godot?

O runtime é distribuído sob a Spine Runtimes License, que está ligada ao uso do editor Spine. Na prática, quem produz as animações precisa de uma licença do editor. Leia o texto da licença no site oficial antes de publicar o jogo, porque é ele que vale, não resumo de terceiros.

A versão do Spine precisa bater com a do runtime?

Precisa. Os dados exportados por uma versão do editor Spine devem ser lidos pelo runtime da mesma versão. Se você atualizar o runtime para uma versão maior, reexporte os projetos com o editor correspondente. Misturar versões é a causa mais comum de esqueleto que não carrega ou carrega quebrado.