server-deploy/claude-dev-stack/godot-mcp-pro-v1.14.1/addons/godot_mcp/skills.pt-br.md

Language: English | 日本語 | Português (BR) | Español | Русский | 简体中文 | हिन्दी

Godot MCP Pro — Skills para Assistentes de IA

Copie este arquivo para .claude/skills.md na raiz do seu projeto Godot para dar ao Claude Code o contexto completo de como usar o Godot MCP Pro de forma eficiente.

O que é o Godot MCP Pro?

Você tem acesso a 169 ferramentas MCP que se conectam diretamente ao editor Godot 4. Você pode criar cenas, escrever scripts, simular entrada do jogador, inspecionar jogos em execução e muito mais — tudo sem que o usuário precise sair desta conversa. Todas as alterações passam pelo sistema UndoRedo do Godot, então o usuário pode sempre usar Ctrl+Z.

Fluxos de Trabalho Essenciais

1. Explorar um Projeto

Sempre comece entendendo o projeto antes de fazer alterações:

get_project_info          → nome do projeto, versão do Godot, renderizador, tamanho do viewport
get_filesystem_tree       → estrutura de diretórios (use filter: "*.tscn" ou "*.gd")
get_scene_tree            → hierarquia de nós da cena atualmente aberta
read_script               → ler qualquer arquivo GDScript
get_project_settings      → verificar configuração do projeto

2. Construir uma Cena 2D

create_scene   → criar arquivo .tscn com tipo de nó raiz
add_node       → adicionar nós filhos com propriedades
create_script  → escrever GDScript para lógica do jogo
attach_script  → anexar script a um nó
update_property → definir position, scale, modulate, etc.
save_scene     → salvar no disco

Exemplo — criando um jogador:

1. create_scene com root_type CharacterBody2D, path res://scenes/player.tscn
2. add_node tipo Sprite2D com propriedade texture
3. add_node tipo CollisionShape2D
4. add_resource para atribuir uma shape (ex: RectangleShape2D) ao CollisionShape2D
5. create_script com lógica de movimento
6. attach_script ao nó raiz
7. save_scene

3. Construir uma Cena 3D

create_scene         → root_type: Node3D
add_mesh_instance    → adicionar primitivas (box, sphere, cylinder, plane) ou importar .glb/.gltf
setup_lighting       → adicionar DirectionalLight3D, OmniLight3D ou SpotLight3D
setup_environment    → céu, luz ambiente, neblina, tonemap
setup_camera_3d      → câmera com SpringArm3D opcional para terceira pessoa
set_material_3d      → materiais PBR (albedo, metallic, roughness, emission)
setup_collision      → adicionar shapes de colisão a corpos físicos
setup_physics_body   → configurar massa, atrito, gravidade

4. Escrever e Editar Scripts

create_script  → criar novo arquivo .gd (forneça o conteúdo completo)
edit_script    → modificar scripts existentes
  - Use `replacements: [{search: "old code", replace: "new code"}]` para edições pontuais
  - Use `content` para substituição completa do arquivo
  - Use `insert_at_line` + `text` para inserir código
validate_script → verificar erros de sintaxe sem executar
read_script    → ler conteúdo atual antes de editar

5. Testar e Depurar

play_scene             → iniciar o jogo (mode: "current", "main" ou caminho do arquivo)
get_game_screenshot    → ver como o jogo está neste momento
capture_frames         → capturar múltiplos frames para observar movimento/animação
get_game_scene_tree    → inspecionar a árvore de cena em tempo de execução
get_game_node_properties → ler valores em runtime (position, health, state, etc.)
set_game_node_property → modificar valores no jogo em execução
simulate_key           → pressionar teclas (WASD, SPACE, etc.) com duração
simulate_mouse_click   → clicar em coordenadas do viewport
simulate_action        → disparar ações do InputMap (move_left, jump, etc.)
get_editor_errors      → verificar erros de execução
stop_scene             → parar o jogo

Loop de playtesting:

1. play_scene → iniciar o jogo
2. get_game_screenshot → ver estado atual
3. simulate_key / simulate_action → interagir com o jogo
4. capture_frames → observar comportamento ao longo do tempo
5. get_game_node_properties → verificar valores específicos
6. stop_scene → parar quando terminar
7. Corrigir problemas nos scripts → repetir

6. Animações

# Certifique-se de que existe um nó AnimationPlayer na cena
create_animation       → nova animação com duração e modo de loop
add_animation_track    → adicionar tracks de property/transform/method
set_animation_keyframe → inserir keyframes em tempos específicos
get_animation_info     → inspecionar animações existentes

Exemplo — sprite quicando:

1. create_animation name bounce, length 1.0, loop_mode 1 (loop linear)
2. add_animation_track track_path Sprite2D:position, track_type value
3. set_animation_keyframe time 0.0, value Vector2(0, 0)
4. set_animation_keyframe time 0.5, value Vector2(0, -50)
5. set_animation_keyframe time 1.0, value Vector2(0, 0)

7. UI / HUD

add_node          → Control, Label, Button, TextureRect, etc.
set_anchor_preset → posicionar Controls (full_rect, center, bottom_wide, etc.)
set_theme_color   → alterar font_color, etc.
set_theme_font_size → ajustar tamanho do texto
set_theme_stylebox  → fundos, bordas, cantos arredondados
connect_signal    → conectar pressed do button, value_changed, etc.

8. TileMap

tilemap_get_info      → verificar fontes do tile set e layout do atlas
tilemap_set_cell      → colocar tiles individuais
tilemap_fill_rect     → preencher regiões retangulares
tilemap_get_used_cells → ver o que já está colocado
tilemap_clear         → limpar todas as células

9. Áudio

add_audio_bus        → criar buses de áudio (SFX, Music, UI)
set_audio_bus        → ajustar volume, solo, mute
add_audio_bus_effect → adicionar reverb, delay, compressor, etc.
add_audio_player     → adicionar nós AudioStreamPlayer(2D/3D)

10. Configuração do Projeto

set_project_setting  → alterar tamanho do viewport, configurações de física, etc.
set_input_action     → definir mapeamentos de entrada (move_left → KEY_A, etc.)
add_autoload         → registrar singletons autoload
set_physics_layers   → nomear camadas de colisão (player, enemy, world, etc.)

Regras Importantes e Armadilhas

Valores de Propriedade

Propriedades são parseadas automaticamente de strings. Use estes formatos:

• Vector2: "Vector2(100, 200)"
• Vector3: "Vector3(1, 2, 3)"
• Color: "Color(1, 0, 0, 1)" ou "#ff0000"
• Bool: "true" / "false"
• Números: "42", "3.14"
• Enums: Use valores inteiros (ex: 0 para o primeiro valor do enum)

Nunca Edite project.godot Diretamente

O editor Godot sobrescreve project.godot constantemente. Sempre use set_project_setting para alterar configurações do projeto.

Anotações de Tipo em GDScript

Ao escrever GDScript com loops for sobre arrays sem tipo, use anotações de tipo explícitas:

# RUIM — vai causar erros
for item in some_untyped_array:
    var x := item.value  # inferência de tipo falha

# BOM
for i in range(some_untyped_array.size()):
    var item: Dictionary = some_untyped_array[i]
    var x: int = item.value

Alterações em Scripts Precisam de Reload

Após criar ou modificar scripts significativamente, use reload_project para garantir que o Godot reconheça as alterações. Isso é especialmente importante após create_script.

Dicas para simulate_key

• Use durações curtas (0.3–0.5 segundos) para movimentos precisos
• Durações longas (1+ segundo) causam overshooting
• Para testes de gameplay, prefira simulate_action em vez de simulate_key quando ações do InputMap estiverem definidas

simulate_mouse_click

• O padrão auto_release: true envia press e release — necessário para botões de UI
• Botões de UI disparam no release, então ambos os eventos são necessários

Limitações do execute_game_script

• Sem funções aninhadas (func dentro de func) — causa erro de compilação
• Use .get("property") em vez de .property para acesso dinâmico
• Erros de runtime pausam o debugger (continuado automaticamente, mas evite se possível)

Colisão e Áreas de Coleta

• Para itens coletáveis, use Area3D/Area2D com raio >= 1.5
• Raios menores são quase impossíveis de acionar com entrada simulada

Salve com Frequência

Chame save_scene após fazer alterações significativas. Alterações não salvas podem ser perdidas se o editor recarregar.

Ferramentas de Análise e Depuração

Quando algo der errado, use estas ferramentas para investigar:

get_editor_errors          → verificar erros de script e exceções de runtime
get_output_log             → ler saída de print() e avisos
analyze_scene_complexity   → encontrar gargalos de performance
analyze_signal_flow        → visualizar conexões de signals
detect_circular_dependencies → encontrar referências circulares de script/cena
find_unused_resources      → limpar arquivos não utilizados
get_performance_monitors   → FPS, memória, draw calls, estatísticas de física

Testes e QA

run_test_scenario   → definir e executar sequências de teste automatizadas
assert_node_state   → verificar se propriedades de nós correspondem aos valores esperados
assert_screen_text  → verificar se texto está exibido na tela
compare_screenshots → teste de regressão visual (use caminhos de arquivo, não base64)
run_stress_test     → gerar muitos nós para testar performance

Padrões Avançados

Operações entre Cenas

cross_scene_set_property → modificar nós em cenas que não estão abertas atualmente
find_node_references     → encontrar todos os arquivos que referenciam um padrão
batch_set_property       → definir uma propriedade em todos os nós de um tipo

Fluxo de Trabalho com Shaders

create_shader        → escrever código shader estilo GLSL
assign_shader_material → aplicar a um nó
set_shader_param     → ajustar uniforms em runtime
get_shader_params    → inspecionar valores atuais

Navegação (3D)

setup_navigation_region → definir área caminhável
bake_navigation_mesh   → gerar navmesh
setup_navigation_agent → adicionar pathfinding a personagens

AnimationTree e Máquinas de Estado

create_animation_tree           → configurar AnimationTree com máquina de estado ou blend tree
add_state_machine_state         → adicionar estados (idle, walk, run, jump)
add_state_machine_transition    → definir transições entre estados
set_tree_parameter              → controlar parâmetros de blend

Ordem de Fluxo de Trabalho Recomendada

Ao construir um novo jogo do zero:

1. Configuração do projeto — get_project_info, set_project_setting (viewport, física)
2. Mapeamento de entrada — set_input_action para todos os controles do jogador
3. Cena principal — create_scene, definir como cena principal
4. Jogador — criar cena do jogador com sprite, colisão, script
5. Nível/Mundo — construir o ambiente (TileMap, meshes 3D, etc.)
6. Lógica do jogo — scripts para inimigos, itens, UI
7. Áudio — configurar buses, adicionar audio players
8. Playtesting — play_scene, testar com entrada simulada, corrigir bugs
9. Polimento — animações, partículas, shaders, temas
10. Exportação — list_export_presets, export_project