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

> **Language:** [English](skills.md) | [日本語](skills.ja.md) | Português (BR) | [Español](skills.es.md) | [Русский](skills.ru.md) | [简体中文](skills.zh.md) | [हिन्दी](skills.hi.md)

# 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:
```gdscript
# 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`