server-deploy/windows-dev-stack/godot-mcp-pro-v1.14.1/addons/godot_mcp/skills.es.md

> **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`