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)](skills.pt-br.md) | Español | [Русский](skills.ru.md) | [简体中文](skills.zh.md) | [हिन्दी](skills.hi.md)
|
||||
|
||||
# Godot MCP Pro — Skills para Asistentes de IA
|
||||
|
||||
> Copia este archivo a `.claude/skills.md` en la raíz de tu proyecto Godot para darle a Claude Code el contexto completo sobre cómo usar Godot MCP Pro de forma efectiva.
|
||||
|
||||
## ¿Qué es Godot MCP Pro?
|
||||
|
||||
Tienes acceso a 169 herramientas MCP que se conectan directamente al editor de Godot 4. Puedes crear escenas, escribir scripts, simular entrada del jugador, inspeccionar juegos en ejecución y más — todo sin que el usuario salga de esta conversación. Cada cambio pasa por el sistema UndoRedo de Godot, así que el usuario siempre puede hacer Ctrl+Z.
|
||||
|
||||
## Flujos de Trabajo Esenciales
|
||||
|
||||
### 1. Explorar un Proyecto
|
||||
|
||||
Siempre empieza entendiendo el proyecto antes de hacer cambios:
|
||||
|
||||
```
|
||||
get_project_info → nombre del proyecto, versión de Godot, renderizador, tamaño del viewport
|
||||
get_filesystem_tree → estructura de directorios (usa filter: "*.tscn" o "*.gd")
|
||||
get_scene_tree → jerarquía de nodos de la escena abierta actualmente
|
||||
read_script → leer cualquier archivo GDScript
|
||||
get_project_settings → revisar la configuración del proyecto
|
||||
```
|
||||
|
||||
### 2. Construir una Escena 2D
|
||||
|
||||
```
|
||||
create_scene → crear archivo .tscn con tipo de nodo raíz
|
||||
add_node → agregar nodos hijos con propiedades
|
||||
create_script → escribir GDScript para lógica del juego
|
||||
attach_script → adjuntar script a un nodo
|
||||
update_property → establecer position, scale, modulate, etc.
|
||||
save_scene → guardar en disco
|
||||
```
|
||||
|
||||
**Ejemplo — creando un jugador:**
|
||||
1. `create_scene` con root_type `CharacterBody2D`, path `res://scenes/player.tscn`
|
||||
2. `add_node` tipo `Sprite2D` con propiedad texture
|
||||
3. `add_node` tipo `CollisionShape2D`
|
||||
4. `add_resource` para asignar una shape (ej: `RectangleShape2D`) al CollisionShape2D
|
||||
5. `create_script` con lógica de movimiento
|
||||
6. `attach_script` al nodo raíz
|
||||
7. `save_scene`
|
||||
|
||||
### 3. Construir una Escena 3D
|
||||
|
||||
```
|
||||
create_scene → root_type: Node3D
|
||||
add_mesh_instance → agregar primitivas (box, sphere, cylinder, plane) o importar .glb/.gltf
|
||||
setup_lighting → agregar DirectionalLight3D, OmniLight3D o SpotLight3D
|
||||
setup_environment → cielo, luz ambiental, niebla, tonemap
|
||||
setup_camera_3d → cámara con SpringArm3D opcional para tercera persona
|
||||
set_material_3d → materiales PBR (albedo, metallic, roughness, emission)
|
||||
setup_collision → agregar shapes de colisión a cuerpos físicos
|
||||
setup_physics_body → configurar masa, fricción, gravedad
|
||||
```
|
||||
|
||||
### 4. Escribir y Editar Scripts
|
||||
|
||||
```
|
||||
create_script → crear nuevo archivo .gd (proporciona el contenido completo)
|
||||
edit_script → modificar scripts existentes
|
||||
- Usa `replacements: [{search: "old code", replace: "new code"}]` para ediciones específicas
|
||||
- Usa `content` para reemplazo completo del archivo
|
||||
- Usa `insert_at_line` + `text` para insertar código
|
||||
validate_script → verificar errores de sintaxis sin ejecutar
|
||||
read_script → leer contenido actual antes de editar
|
||||
```
|
||||
|
||||
### 5. Probar y Depurar
|
||||
|
||||
```
|
||||
play_scene → lanzar el juego (mode: "current", "main" o ruta de archivo)
|
||||
get_game_screenshot → ver cómo luce el juego en este momento
|
||||
capture_frames → capturar múltiples frames para observar movimiento/animación
|
||||
get_game_scene_tree → inspeccionar el árbol de escena en tiempo de ejecución
|
||||
get_game_node_properties → leer valores en runtime (position, health, state, etc.)
|
||||
set_game_node_property → modificar valores en el juego en ejecución
|
||||
simulate_key → presionar teclas (WASD, SPACE, etc.) con duración
|
||||
simulate_mouse_click → hacer clic en coordenadas del viewport
|
||||
simulate_action → disparar acciones del InputMap (move_left, jump, etc.)
|
||||
get_editor_errors → revisar errores de ejecución
|
||||
stop_scene → detener el juego
|
||||
```
|
||||
|
||||
**Ciclo de playtesting:**
|
||||
1. `play_scene` → iniciar el juego
|
||||
2. `get_game_screenshot` → ver estado actual
|
||||
3. `simulate_key` / `simulate_action` → interactuar con el juego
|
||||
4. `capture_frames` → observar comportamiento a lo largo del tiempo
|
||||
5. `get_game_node_properties` → verificar valores específicos
|
||||
6. `stop_scene` → detener cuando termines
|
||||
7. Corregir problemas en scripts → repetir
|
||||
|
||||
### 6. Animaciones
|
||||
|
||||
```
|
||||
# Asegúrate de que exista un nodo AnimationPlayer en la escena
|
||||
create_animation → nueva animación con duración y modo de loop
|
||||
add_animation_track → agregar tracks de property/transform/method
|
||||
set_animation_keyframe → insertar keyframes en tiempos específicos
|
||||
get_animation_info → inspeccionar animaciones existentes
|
||||
```
|
||||
|
||||
**Ejemplo — sprite rebotando:**
|
||||
1. `create_animation` name `bounce`, length `1.0`, loop_mode `1` (loop lineal)
|
||||
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 → cambiar font_color, etc.
|
||||
set_theme_font_size → ajustar tamaño de texto
|
||||
set_theme_stylebox → fondos, bordes, esquinas redondeadas
|
||||
connect_signal → conectar pressed del button, value_changed, etc.
|
||||
```
|
||||
|
||||
### 8. TileMap
|
||||
|
||||
```
|
||||
tilemap_get_info → revisar fuentes del tile set y disposición del atlas
|
||||
tilemap_set_cell → colocar tiles individuales
|
||||
tilemap_fill_rect → rellenar regiones rectangulares
|
||||
tilemap_get_used_cells → ver qué ya está colocado
|
||||
tilemap_clear → limpiar todas las celdas
|
||||
```
|
||||
|
||||
### 9. Audio
|
||||
|
||||
```
|
||||
add_audio_bus → crear buses de audio (SFX, Music, UI)
|
||||
set_audio_bus → ajustar volumen, solo, mute
|
||||
add_audio_bus_effect → agregar reverb, delay, compressor, etc.
|
||||
add_audio_player → agregar nodos AudioStreamPlayer(2D/3D)
|
||||
```
|
||||
|
||||
### 10. Configuración del Proyecto
|
||||
|
||||
```
|
||||
set_project_setting → cambiar tamaño del viewport, configuraciones de física, etc.
|
||||
set_input_action → definir mapeos de entrada (move_left → KEY_A, etc.)
|
||||
add_autoload → registrar singletons autoload
|
||||
set_physics_layers → nombrar capas de colisión (player, enemy, world, etc.)
|
||||
```
|
||||
|
||||
## Reglas Importantes y Trampas
|
||||
|
||||
### Valores de Propiedades
|
||||
Las propiedades se parsean automáticamente desde strings. Usa estos formatos:
|
||||
- Vector2: `"Vector2(100, 200)"`
|
||||
- Vector3: `"Vector3(1, 2, 3)"`
|
||||
- Color: `"Color(1, 0, 0, 1)"` o `"#ff0000"`
|
||||
- Bool: `"true"` / `"false"`
|
||||
- Números: `"42"`, `"3.14"`
|
||||
- Enums: Usa valores enteros (ej: `0` para el primer valor del enum)
|
||||
|
||||
### Nunca Edites project.godot Directamente
|
||||
El editor de Godot sobrescribe `project.godot` constantemente. Siempre usa `set_project_setting` para cambiar configuraciones del proyecto.
|
||||
|
||||
### Anotaciones de Tipo en GDScript
|
||||
Al escribir GDScript con loops `for` sobre arrays sin tipo, usa anotaciones de tipo explícitas:
|
||||
```gdscript
|
||||
# MAL — causará errores
|
||||
for item in some_untyped_array:
|
||||
var x := item.value # la inferencia de tipos falla
|
||||
|
||||
# BIEN
|
||||
for i in range(some_untyped_array.size()):
|
||||
var item: Dictionary = some_untyped_array[i]
|
||||
var x: int = item.value
|
||||
```
|
||||
|
||||
### Los Cambios en Scripts Necesitan Reload
|
||||
Después de crear o modificar scripts significativamente, usa `reload_project` para asegurar que Godot reconozca los cambios. Esto es especialmente importante después de `create_script`.
|
||||
|
||||
### Consejos para simulate_key
|
||||
- Usa **duraciones cortas** (0.3–0.5 segundos) para movimiento preciso
|
||||
- Duraciones largas (1+ segundo) causan overshooting
|
||||
- Para pruebas de gameplay, prefiere `simulate_action` sobre `simulate_key` cuando haya acciones del InputMap definidas
|
||||
|
||||
### simulate_mouse_click
|
||||
- El valor por defecto `auto_release: true` envía press y release — requerido para botones de UI
|
||||
- Los botones de UI se activan en release, por lo que ambos eventos son necesarios
|
||||
|
||||
### Limitaciones de execute_game_script
|
||||
- Sin funciones anidadas (`func` dentro de `func`) — causa error de compilación
|
||||
- Usa `.get("property")` en lugar de `.property` para acceso dinámico
|
||||
- Los errores de runtime pausan el debugger (se continúa automáticamente, pero evítalo si es posible)
|
||||
|
||||
### Colisión y Áreas de Recolección
|
||||
- Para ítems recolectables, usa Area3D/Area2D con radio >= 1.5
|
||||
- Radios más pequeños son casi imposibles de activar con entrada simulada
|
||||
|
||||
### Guarda Frecuentemente
|
||||
Llama a `save_scene` después de hacer cambios significativos. Los cambios no guardados pueden perderse si el editor se recarga.
|
||||
|
||||
## Herramientas de Análisis y Depuración
|
||||
|
||||
Cuando algo sale mal, usa estas herramientas para investigar:
|
||||
|
||||
```
|
||||
get_editor_errors → revisar errores de script y excepciones de runtime
|
||||
get_output_log → leer salida de print() y advertencias
|
||||
analyze_scene_complexity → encontrar cuellos de botella de rendimiento
|
||||
analyze_signal_flow → visualizar conexiones de signals
|
||||
detect_circular_dependencies → encontrar referencias circulares de script/escena
|
||||
find_unused_resources → limpiar archivos no utilizados
|
||||
get_performance_monitors → FPS, memoria, draw calls, estadísticas de física
|
||||
```
|
||||
|
||||
## Pruebas y QA
|
||||
|
||||
```
|
||||
run_test_scenario → definir y ejecutar secuencias de prueba automatizadas
|
||||
assert_node_state → verificar que las propiedades de nodos coincidan con valores esperados
|
||||
assert_screen_text → verificar que el texto se muestre en pantalla
|
||||
compare_screenshots → pruebas de regresión visual (usa rutas de archivo, no base64)
|
||||
run_stress_test → generar muchos nodos para probar rendimiento
|
||||
```
|
||||
|
||||
## Patrones Avanzados
|
||||
|
||||
### Operaciones entre Escenas
|
||||
```
|
||||
cross_scene_set_property → modificar nodos en escenas que no están abiertas actualmente
|
||||
find_node_references → encontrar todos los archivos que referencian un patrón
|
||||
batch_set_property → establecer una propiedad en todos los nodos de un tipo
|
||||
```
|
||||
|
||||
### Flujo de Trabajo con Shaders
|
||||
```
|
||||
create_shader → escribir código shader estilo GLSL
|
||||
assign_shader_material → aplicar a un nodo
|
||||
set_shader_param → ajustar uniforms en runtime
|
||||
get_shader_params → inspeccionar valores actuales
|
||||
```
|
||||
|
||||
### Navegación (3D)
|
||||
```
|
||||
setup_navigation_region → definir área transitable
|
||||
bake_navigation_mesh → generar navmesh
|
||||
setup_navigation_agent → agregar pathfinding a personajes
|
||||
```
|
||||
|
||||
### AnimationTree y Máquinas de Estado
|
||||
```
|
||||
create_animation_tree → configurar AnimationTree con máquina de estado o blend tree
|
||||
add_state_machine_state → agregar estados (idle, walk, run, jump)
|
||||
add_state_machine_transition → definir transiciones entre estados
|
||||
set_tree_parameter → controlar parámetros de blend
|
||||
```
|
||||
|
||||
## Orden de Flujo de Trabajo Recomendado
|
||||
|
||||
Al construir un juego nuevo desde cero:
|
||||
|
||||
1. **Configuración del proyecto** — `get_project_info`, `set_project_setting` (viewport, física)
|
||||
2. **Mapeo de entrada** — `set_input_action` para todos los controles del jugador
|
||||
3. **Escena principal** — `create_scene`, establecer como escena principal
|
||||
4. **Jugador** — crear escena del jugador con sprite, colisión, script
|
||||
5. **Nivel/Mundo** — construir el entorno (TileMap, meshes 3D, etc.)
|
||||
6. **Lógica del juego** — scripts para enemigos, ítems, UI
|
||||
7. **Audio** — configurar buses, agregar audio players
|
||||
8. **Playtesting** — `play_scene`, probar con entrada simulada, corregir bugs
|
||||
9. **Pulido** — animaciones, partículas, shaders, temas
|
||||
10. **Exportación** — `list_export_presets`, `export_project`
|
||||
Reference in New Issue
Block a user