Godot 2D Movement: controle de personagem sem confundir velocidade e colisão

ANÁLISE EDITORIAL

Um personagem que atravessa o chão pode parecer um problema de física, mas às vezes a causa está na configuração da máscara de colisão ou em uma chamada de movimento colocada no ciclo errado. A Godot 2D Movement reúne exemplos para diagnosticar esses detalhes em jogos 2D feitos com Godot 4.7. A proposta é orientar uma implementação pequena e verificável, não entregar um jogo pronto.

O que esta Skill faz

A Skill orienta um agente de código a trabalhar com CharacterBody2D, CollisionShape2D, a propriedade velocity e o método move_and_slide(). Cobre movimentação lateral com gravidade e salto, movimento em oito direções visto de cima, leitura de colisões e ajustes de rampa. Uma referência adicional trata de salto com altura variável, tolerância de salto, plataformas móveis e move_and_collide(). Esses exemplos são pontos de partida, não componentes instaláveis de uma engine.

O recorte importa. Um corpo controlado por script não recebe gravidade automaticamente só por ter uma forma de colisão. E a forma de chamar move_and_slide() no Godot 4 é diferente da API da série 3. A documentação oficial de CharacterBody2D confirma que o corpo deve ser movido pelos métodos de colisão durante o passo de física.

Para quem serve e quando não usar

Serve a quem mantém um protótipo, um jogo de plataforma ou um personagem de visão superior em Godot 4.7 e quer pedir ajuda a um agente sem aceitar uma alteração ampla e opaca. Também funciona como checklist humano para investigar por que is_on_floor() permanece falso, por que um corpo afunda ou por que a velocidade se comporta de modo diferente em máquinas distintas.

Não é o material certo para corpos rígidos movidos pela simulação, para criar um mapa de tiles, nem para desenhar toda a arquitetura de um jogo. A própria coleção aponta outras Skills para essas tarefas. Em um projeto Godot 3, não copie o exemplo sem adaptação: a assinatura antiga de move_and_slide não corresponde à série 4. Para um jogo já publicado em outra versão 4.x, confira a referência daquela versão antes de aplicar um trecho do arquivo.

Origem, adoção, licença e commit

O material é mantido em gamedev-skills/awesome-gamedev-agent-skills, uma coleção independente de Skills de desenvolvimento de jogos. Não é uma Skill oficial do projeto Godot, e o nome da engine indica compatibilidade, não endosso. A consulta ao GitHub em 22/09/2026 registrou 1.101 estrelas. O número descreve a adoção pública do repositório naquele instante e não mede a qualidade do controle de personagem.

Os arquivos foram fixados no commit b105e1cf617adf0b68ed98790a716bbb60993179. O cabeçalho da Skill informa alvo Godot 4.7, mas não dá um número de versão próprio para o documento. O repositório usa Apache-2.0 e inclui um arquivo NOTICE, ambos preservados no pacote local. A licença da documentação visual do Godot é diferente e está creditada abaixo.

Três verificações antes de mexer no controle

Árvore da cena: confira se o personagem é um CharacterBody2D com CollisionShape2D dimensionado, se o chão também tem colisão e se a máscara do personagem inclui a camada do chão. Um sprite visível não é uma forma de colisão. No caso de plataformas unidirecionais, a orientação e a opção de colisão unilateral também entram na análise.

Entrada e passo de física: defina as ações no Input Map antes de chamar Input.get_axis() ou Input.get_vector(). Atualize velocity dentro de _physics_process(delta) e chame move_and_slide() sem argumentos no Godot 4. O método já considera o passo de física; multiplicar a velocidade por delta uma segunda vez produz movimento incorreto. A gravidade, ao contrário, deve ser acumulada com o tempo.

Resultado observável: rode uma cena pequena com piso plano, obstáculo e rampa. Verifique deslocamento, colisão e estados is_on_floor() ou is_on_wall() depois da chamada de movimento. A Skill também mostra get_slide_collision(), mas uma leitura de colisão não prova que o jogo está equilibrado ou livre de falhas. Salto, câmera e animação precisam de testes próprios.

Captura real da configuração de entrada

A imagem abaixo mostra a aba Input Map no editor apresentada pela documentação oficial do Godot 4.7. Ela ajuda a localizar as ações direcionais que o exemplo da documentação configura. Os nomes do pacote auditado, como move_left, são diferentes dos nomes da captura, como left; crie as ações com os nomes que seu script realmente usa. Não é captura de uma execução feita pelo Bastidores.

Compatibilidade e pré-requisitos

Para ler o ZIP, basta um agente compatível com arquivos SKILL.md e referências Markdown. Para aplicar os exemplos, tenha um projeto Godot 4.7 que possa ser alterado com segurança, uma cena de teste e acesso ao editor. O pacote não instala Godot. Confira a versão real do projeto e as opções de exportação antes de copiar orientações para outro ambiente. O manual da classe na versão 4.7 é o contraponto técnico às receitas da coleção.

O agente precisará ler a cena e o script que você autorizar. Se também puder editar arquivos ou executar o projeto, defina esse escopo de maneira explícita. Uma cena descartável e controle de versão facilitam a revisão do diff e a reversão. Não forneça credenciais de distribuição, acesso à loja, arquivos de jogadores ou código privado sem necessidade.

Instalação segura do pacote documental

O download local godot-2d-movement.zip reúne SKILL.md, sua referência controller-recipes.md, LICENSE, NOTICE e ORIGEM.md. Seu SHA-256 é e392b6fa76fd775263f34709d3a47b4c5a3c152cfcd74159ad7706b317aac1ce. No PowerShell, confira com Get-FileHash .\godot-2d-movement.zip -Algorithm SHA256; em Linux ou macOS, com sha256sum godot-2d-movement.zip. Se o valor divergir, não use o arquivo.

Extraia o ZIP em um diretório de inspeção, leia ORIGEM.md e os dois arquivos de licença/atribuição. Depois copie apenas a pasta godot-2d-movement para o diretório de Skills apropriado ao seu agente, sem mover os avisos de licença para um lugar inacessível. O repositório de origem é uma ação separada para conferir os arquivos diretamente no mantenedor. O ZIP não contém editor, motor, executável, scripts de instalação ou um projeto de jogo.

Configuração e primeiro uso

Faça a primeira tentativa em uma cópia recuperável de uma cena simples. Configure as ações move_left, move_right e jump no Input Map se for testar o padrão lateral do documento. Adicione uma forma de colisão ao personagem e outra ao piso. Peça ao agente: “Leia a versão do projeto, a cena do personagem e o script atual. Compare o uso de velocity, Input Map e move_and_slide() com a Skill Godot 2D Movement. Proponha primeiro um diff mínimo, sem editar a cena nem executar comandos.”

Depois da sua aprovação, aplique somente a alteração selecionada e teste a cena com entradas reproduzíveis. Para visão superior, use as quatro ações direcionais e examine o modo MOTION_MODE_FLOATING, que não classifica superfícies como piso e teto. Para plataforma, teste queda, salto no chão, borda e rampa. Registre o que foi observado em vez de declarar que um valor de velocidade ou de gravidade serve para todos os jogos.

Resultado esperado e limites

Um resultado útil é um controlador pequeno cuja direção responde às ações configuradas, que não atravessa um piso válido e cuja diferença em relação ao código anterior pode ser inspecionada. A Skill também deve ajudar a explicar um erro concreto, como uma forma ausente ou uma máscara incompatível. Os números de velocidade e gravidade do exemplo são valores ilustrativos para ajuste local, não parâmetros universais ou medições de desempenho.

O pacote documental não inclui o roteador da coleção completa nem as Skills relacionadas. Por isso, referências a platformer, godot-physics e outras são contexto, não uma promessa de que esses arquivos virão no ZIP. Instalar a Skill tampouco garante compatibilidade com plugins, dispositivos móveis, multiplayer ou versões futuras da engine.

Permissões, privacidade e riscos

O texto da Skill é uma instrução para agentes, portanto deve ser lido como conteúdo de terceiros antes de ser ativado. O arquivo em si não solicita credenciais ou acesso de rede, mas um agente com ferramentas pode ler, alterar e executar arquivos conforme as permissões que você lhe conceder. Limite o escopo ao projeto, aprove mudanças mutáveis e mantenha backups. Em repositórios compartilhados, revise também se cenas, recursos e relatórios de teste contêm dados privados.

A referência descreve ajustes como desabilitar temporariamente uma camada para atravessar uma plataforma de um só sentido. Essa alteração afeta colisões durante a execução e precisa ser restaurada no momento correto. Não trate uma receita de exemplo como sistema final de segurança, antitrapaça ou persistência. Para jogos com estado salvo ou rede, faça uma análise específica.

Erros comuns e como corrigir

Nada acontece ao apertar uma tecla: confirme no Input Map que a ação existe, que o nome no código é idêntico e que a cena em teste está ativa. O personagem cai através do piso: verifique as duas formas de colisão, sua escala e as camadas e máscaras, antes de mexer na gravidade. is_on_floor() fica falso: observe o valor depois de move_and_slide() e confira a direção para cima e a posição da forma.

Movimento lento ou irregular: procure multiplicação extra por delta e deslocamento direto por position +=. Erro ao chamar move_and_slide(velocity): verifique se não foi copiado um padrão da série 3. Escorrega em rampas: confira floor_stop_on_slope, floor_snap_length e a geometria do piso. Se a cena ainda falhar, reduza-a a um teste mínimo antes de acrescentar câmera, animação ou inimigos.

Integridade, licença e fontes

Os quatro arquivos originais do ZIP foram comparados byte a byte com os Git blobs do commit citado. ORIGEM.md registra os hashes individuais e a atribuição. A licença Apache-2.0 permite a redistribuição com seus avisos preservados; a captura externa é da documentação Godot sob CC BY 3.0 e não integra o ZIP. Consulte a instalação no README do mantenedor e a documentação original do Godot. Nenhum exemplo foi executado pelo Bastidores nesta curadoria.