refactor: 拆分 claude-dev-stack 为 windows-dev-stack 和 wsl-dev-stack
将原 claude-dev-stack 目录拆分为独立的 Windows 和 WSL 部署栈，便于分别维护和使用。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -0,0 +1,271 @@
|
||||
> **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`
|
||||
Reference in New Issue
Block a user