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

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

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:

# 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