Ragdoll na Godot 4: Física de Esqueleto com PhysicalBone3D

Ragdoll na Godot 4 é o efeito de um personagem que perde o controle e desaba de forma física: o inimigo leva o tiro final, os membros amolecem e o corpo tomba respeitando a gravidade, a inclinação do chão e os obstáculos ao redor. Em vez de tocar uma animação de morte fixa, você entrega o esqueleto para o motor de física e deixa a queda acontecer sozinha. Na Godot 4 a peça central disso é o nó PhysicalBone3D, que vive dentro de um Skeleton3D e transforma cada osso em um corpo rígido articulado.

Neste guia você vai montar a física do esqueleto, ativar a simulação por código com physical_bones_start_simulation(), voltar para a animação e entender os cuidados de performance. Também vou ser honesto sobre um ponto que quase todo tutorial esconde: ragdoll puro raramente é a melhor solução, e o resultado bom quase sempre vem de misturar física com animação. Se você ainda está começando no 3D, vale ler antes o passo a passo do seu primeiro jogo 3D na Godot, porque aqui eu assumo que você já sabe montar uma cena com um personagem animado.

Como o ragdoll funciona na Godot 4

O ponto de partida é sempre um Skeleton3D: o nó que guarda a hierarquia de ossos de um modelo animado, normalmente importado de um .glb ou .fbx. Em condições normais, quem move esses ossos é o AnimationPlayer, aplicando as poses das animações a cada frame. O ragdoll inverte isso: durante a simulação, quem dita a posição de cada osso é o motor de física.

Para isso existe o PhysicalBone3D. Ele é um corpo rígido articulado, parecido em espírito com um RigidBody3D, mas amarrado a um osso específico do esqueleto por uma junta. Cada PhysicalBone3D precisa de uma forma de colisão (um CollisionShape3D filho) para saber com o que colide e qual é o seu volume físico. Quando a simulação liga, esses corpos caem sob gravidade, batem no chão, esbarram uns nos outros e arrastam os ossos do Skeleton3D junto. O resultado é o corpo desabando de forma crível.

Três conceitos guiam tudo o que vem a seguir:

• Skeleton3D é o maestro. Você nunca liga ou desliga um PhysicalBone3D individualmente na prática comum; você chama métodos no Skeleton3D que ligam e desligam o conjunto.
• PhysicalBone3D é o corpo físico de um osso. Sem forma de colisão, ele não faz nada útil.
• Junta é o que segura o esqueleto inteiro. Cada corpo se conecta ao corpo do osso pai por uma junta (do tipo cone, hinge, etc.), o que impede que os membros se soltem e voem para longe.

Se motores de física em geral ainda são um assunto nebuloso para você, dê uma olhada em como funcionam por dentro os motores de física de corpo rígido: entender solver, junta e forma de colisão vai fazer todos os ajustes deste post pararem de parecer mágica.

Montando a cena com Skeleton3D

Comece com um personagem humanoide já importado e funcionando com animação. A estrutura típica na sua cena é assim:

Personagem (CharacterBody3D)
├── CollisionShape3D        # colisor do personagem em pé (cápsula)
├── Skeleton3D
│   └── (ossos do modelo)
└── AnimationPlayer

O Skeleton3D é onde toda a mágica do ragdoll mora. Antes de qualquer código, você precisa dar a ele os PhysicalBone3D.

O botão "Create physical skeleton"

Colocar um PhysicalBone3D por osso na mão, com junta e cápsula, é trabalho de horas. A Godot resolve isso com um atalho: selecione o nó Skeleton3D no editor e, na barra de ferramentas que aparece no topo do viewport (o menu do esqueleto, com um ícone de bonequinho), clique em "Create physical skeleton".

A Godot então gera, de uma vez, um PhysicalBone3D para cada osso do esqueleto, cada um já com:

• uma junta configurada em relação ao osso pai;
• uma forma de colisão em cápsula, dimensionada por aproximação a partir do comprimento do osso.

O resultado é bruto e precisa de faxina, mas economiza o trabalho pesado. Depois de gerar, você vai ver dezenas de nós PhysicalBone3D como filhos do Skeleton3D.

Refinando os ossos e as formas de colisão

O esqueleto gerado automaticamente costuma exagerar. Um humanoide não precisa de física em cada falange dos dedos. Faça esta limpeza:

• Apague os PhysicalBone3D de ossos pequenos e irrelevantes: dedos das mãos, dedos dos pés, ossos faciais. Menos corpos significa mais performance e menos instabilidade. Mire em algo entre 10 e 16 corpos para um humano: cabeça, pescoço opcional, tronco, quadril, e os pares de braço, antebraço, coxa e canela.
• Ajuste cada forma de colisão no Inspector do CollisionShape3D. As cápsulas geradas costumam ser finas ou sobrepostas demais. Duas cápsulas que nascem se sobrepondo vão se empurrar com força no primeiro frame e o personagem "explode". Deixe-as encostando, não invadindo uma a outra.
• Confira a escala do modelo. Ragdoll é sensível a escala. Se o seu personagem tem uma escala muito diferente de 1.0 em algum nó pai, o solver de física fica instável. O ideal é aplicar a escala no import e manter os nós de cena em escala 1.

Vale reforçar um ponto de física geral aqui: as formas de colisão dos PhysicalBone3D vão colidir entre si por padrão. Sem cuidado com as juntas e o tamanho das cápsulas, os corpos brigam uns com os outros e o ragdoll vibra ou espirra. É a parte que mais consome tempo de tuning, então não espere que o "Create physical skeleton" entregue algo pronto.

Ativando o ragdoll na Godot por código

Com os PhysicalBone3D montados, ligar e desligar o ragdoll é surpreendentemente simples: são dois métodos no Skeleton3D. Toda a ativação da física em runtime passa por physical_bones_start_simulation(), e a volta ao normal por physical_bones_stop_simulation().

Aqui está um controlador enxuto, em GDScript tipado, para um personagem que entra em ragdoll ao morrer:

extends CharacterBody3D

@onready var skeleton: Skeleton3D = $Skeleton3D
@onready var anim: AnimationPlayer = $AnimationPlayer
@onready var body_collider: CollisionShape3D = $CollisionShape3D

var is_ragdoll: bool = false

func _ready() -> void:
    anim.play("idle")

func die() -> void:
    if is_ragdoll:
        return
    is_ragdoll = true

    # 1. Para de tocar animacao: a fisica assume os ossos agora.
    anim.stop()

    # 2. Desliga o colisor "em pe" do personagem para nao brigar
    #    com as capsulas dos ossos.
    body_collider.disabled = true

    # 3. Liga a simulacao de TODOS os PhysicalBone3D do esqueleto.
    skeleton.physical_bones_start_simulation()

Chamar physical_bones_start_simulation() sem argumentos coloca todos os PhysicalBone3D do esqueleto em modo de simulação. A partir desse frame, o AnimationPlayer não manda mais nos ossos: a física manda. O corpo começa a cair.

Repare no detalhe do body_collider.disabled = true. O CharacterBody3D tem o próprio colisor em cápsula, usado quando o personagem anda em pé. Se você deixar esse colisor ligado durante o ragdoll, ele briga com as cápsulas dos ossos e empurra o corpo de forma estranha. Desligue-o quando o ragdoll começa.

Dando um empurrão na direção do golpe

Um corpo que simplesmente amolece e escorrega no chão parece sem vida. O que vende a morte é o impacto: o inimigo é jogado para trás na direção do tiro. Você consegue isso aplicando um impulso a um osso específico logo depois de ligar a simulação.

Para pegar um PhysicalBone3D pelo nome e empurrá-lo, use apply_central_impulse:

func die_from_hit(hit_direction: Vector3, force: float) -> void:
    die()

    # Pega o corpo fisico do tronco pelo nome do no PhysicalBone3D.
    var spine: PhysicalBone3D = skeleton.get_node("Physical Bone spine") as PhysicalBone3D
    if spine != null:
        spine.apply_central_impulse(hit_direction.normalized() * force)

O nome do nó ("Physical Bone spine") depende de como o seu modelo nomeia os ossos; confira no editor o nome exato que a Godot gerou. O hit_direction é o vetor que vai do atirador para o alvo, e force é a intensidade do empurrão. Um valor entre 3 e 8 costuma dar uma reação satisfatória sem lançar o corpo para o outro lado do mapa.

Voltando do ragdoll para a animação

Desligar o ragdoll é uma única linha:

func stand_up() -> void:
    if not is_ragdoll:
        return
    is_ragdoll = false

    # Devolve o controle dos ossos ao AnimationPlayer.
    skeleton.physical_bones_stop_simulation()

    # Religa o colisor "em pe".
    body_collider.disabled = false

    anim.play("get_up")

Aqui mora o problema que ninguém avisa: physical_bones_stop_simulation() corta a física na hora e devolve os ossos para a animação instantaneamente. Se o corpo estava largado de bruços no chão e você manda tocar idle, ele salta de pé num único frame. O resultado é um teleporte feio.

Existem três saídas comuns para isso:

• Não voltar. Para morte de inimigo, o ragdoll é o estado final. O corpo cai e fica lá até você removê-lo da cena ou dissolvê-lo com um efeito. É o caso mais simples e o mais usado.
• Animação de "get up" que casa com a pose. Você lê a posição final aproximada do ragdoll (de bruços ou de costas) e escolhe uma animação de levantar coerente. Ainda tem um pequeno salto, mas fica aceitável.
• Blend por peso. O caminho profissional, com o AnimationTree misturando gradualmente a pose física de volta para a animação. Mais trabalhoso, resultado muito melhor.

Casos de uso: morte, hit reaction e detritos

Nem todo uso de ragdoll é morte. Cada cenário pede uma dose diferente de física:

• Morte de inimigo. O caso clássico. Ragdoll total, sem volta, muitas vezes com um impulso na direção do golpe. É onde ragdoll puro brilha, porque perder totalmente o controle é exatamente o efeito desejado.
• Hit reaction (reação de dano). Aqui ragdoll puro atrapalha. O inimigo tomou um soco e deveria cambalear e continuar lutando, não virar um saco de batatas. O ideal é uma reação parcial, com só alguns ossos reagindo, ou uma animação de flinch bem-feita.
• Detritos e objetos. Um manequim de treino ou partes destacáveis podem viver o tempo todo em ragdoll passivo, reagindo a explosões e tiros sem nunca terem animação.

Cuidados de performance

Cada PhysicalBone3D ativo é um corpo rígido que o motor de física precisa simular todo frame. Isso escala rápido e mal:

• Limite o número de ragdolls simultâneos. Vinte inimigos morrendo ao mesmo tempo são potencialmente centenas de corpos físicos ativos. Estabeleça um teto: quando um novo ragdoll aparece e você já está no limite, faça o mais antigo dormir (sleeping = true) ou removê-lo.
• Congele ragdolls parados. Quando o corpo já assentou no chão, ele não precisa mais ser simulado. O motor tem detecção de repouso, mas você pode ajudar chamando physical_bones_stop_simulation() depois de alguns segundos e deixando o corpo estático na pose final.
• Menos ossos, mais performance. É o botão mais direto: 12 corpos em vez de 30 é menos da metade do custo.
• Dissolva os corpos. Depois de alguns segundos no chão, faça o inimigo desaparecer com um efeito (afundar, virar fumaça, esmaecer). Além de estético, tira o corpo da simulação.

Se você quer se aprofundar na parte de física em si, na fricção, nas juntas e no comportamento de colisão que sustentam tudo isso, o guia de física de jogos na Godot cobre os fundamentos que fazem o ragdoll parar de parecer aleatório.

Por que ragdoll puro raramente é o melhor

Chega a hora da parte honesta. Ragdoll puro, aquele em que a física assume 100% do corpo, tem um custo estético alto: o personagem vira um boneco de pano sem osso nenhum de firmeza. Para morte tudo bem, é o que queremos. Mas para praticamente qualquer outra situação, o resultado parece sem vida justamente porque perdeu toda a intenção da animação.

O padrão da indústria é misturar animação com física, e há duas abordagens principais:

• Ragdoll parcial (por membros). Você liga a simulação só em alguns ossos e deixa o resto sob controle da animação. O physical_bones_start_simulation() aceita uma lista de nomes de ossos justamente para isso. Um exemplo: o inimigo continua andando pela animação, mas o braço que levou o tiro vira ragdoll e balança solto.

func ragdoll_arm() -> void:
    # So o braco direito entra em fisica; o resto segue animado.
    var arm_bones: Array[StringName] = [
        &"Physical Bone upper_arm_R",
        &"Physical Bone lower_arm_R",
    ]
    skeleton.physical_bones_start_simulation(arm_bones)

• Blend animado (powered ragdoll). A física roda, mas as juntas dos PhysicalBone3D recebem forças que puxam o corpo de volta para a pose da animação-alvo. O personagem cai reagindo ao mundo, mas ainda "tenta" ficar em pé ou executar um movimento. É o que dá aquela sensação de peso realista em jogos AAA. É bem mais complexo de configurar e foge do escopo de um primeiro ragdoll, mas é para onde você caminha quando o efeito básico já funciona.

A recomendação prática: comece com ragdoll total para morte, porque é simples e o efeito é bom. Só quando precisar de reações mais sutis parta para o ragdoll parcial. O blend animado deixe para quando a mecânica já estiver madura e valer o investimento.

Fechando

O ragdoll na Godot 4 se resume a poucas peças: um Skeleton3D com PhysicalBone3D e formas de colisão bem ajustadas, o botão "Create physical skeleton" para gerar a base, e os métodos physical_bones_start_simulation() e physical_bones_stop_simulation() para ligar e desligar a física por código. O código é curto; o trabalho de verdade está no tuning das cápsulas, das juntas e da escala, e na decisão de quando usar física total, parcial ou blend.

A Godot entrega tudo isso de graça e sem plugin, o que é uma das razões de tanta gente migrar para ela em projetos 3D. Se você ainda está decidindo em qual motor investir seu tempo, o nosso comparativo Godot vs Unity detalha como cada engine trata física, animação e fluxo 3D, para você escolher com base no seu projeto e não no hype.