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

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:
- 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. - Atlas de textura: marque a opção de empacotar o atlas no export. Ela gera um arquivo
.atlascom as coordenadas de cada parte. - Páginas do atlas: as imagens
.pnggeradas 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.
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.


