spacel/CLAUDE.md

Godot MCP Pro - AI Assistant Instructions

You have access to the Godot MCP Pro toolset for building and testing Godot games through the editor. Follow these rules carefully.

Critical: Editor vs Runtime Tools

Tools are split into two categories. Using a runtime tool without starting the game will always fail.

Editor Tools (always available)

These work on the currently open scene in the Godot editor:

• Scene: get_scene_tree, create_scene, open_scene, save_scene, delete_scene, add_scene_instance, get_scene_file_content, get_scene_exports
• Nodes: add_node, delete_node, duplicate_node, move_node, rename_node, update_property, get_node_properties, add_resource, set_anchor_preset, connect_signal, disconnect_signal, get_node_groups, set_node_groups, find_nodes_in_group
• Scripts: create_script, read_script, edit_script, validate_script, attach_script, get_open_scripts, list_scripts
• Project: get_project_info, get_project_settings, set_project_setting, get_project_statistics, get_filesystem_tree, get_input_actions, set_input_action
• Editor: execute_editor_script, get_editor_errors, get_output_log, get_editor_screenshot, clear_output, reload_plugin, reload_project
• Resources: create_resource, read_resource, edit_resource, get_resource_preview
• Batch: batch_add_nodes, batch_set_property, find_nodes_by_type, find_signal_connections, find_node_references, get_scene_dependencies, cross_scene_set_property
• 3D: add_mesh_instance, setup_environment, setup_lighting, setup_camera_3d, setup_collision, setup_physics_body, set_material_3d, add_raycast, add_gridmap
• Animation: create_animation, add_animation_track, set_animation_keyframe, list_animations, get_animation_info, remove_animation
• Animation Tree: create_animation_tree, get_animation_tree_structure, add_state_machine_state, add_state_machine_transition, remove_state_machine_state, remove_state_machine_transition, set_blend_tree_node, set_tree_parameter
• Audio: add_audio_player, add_audio_bus, add_audio_bus_effect, set_audio_bus, get_audio_bus_layout, get_audio_info
• Navigation: setup_navigation_region, setup_navigation_agent, bake_navigation_mesh, set_navigation_layers, get_navigation_info
• Particles: create_particles, set_particle_material, set_particle_color_gradient, apply_particle_preset, get_particle_info
• Physics: get_physics_layers, set_physics_layers, get_collision_info
• Shader: create_shader, read_shader, edit_shader, assign_shader_material, get_shader_params, set_shader_param
• Theme: create_theme, get_theme_info, set_theme_color, set_theme_font_size, set_theme_constant, set_theme_stylebox
• Tilemap: tilemap_get_info, tilemap_set_cell, tilemap_get_cell, tilemap_fill_rect, tilemap_clear, tilemap_get_used_cells
• Export: list_export_presets, get_export_info, export_project
• Analysis: analyze_scene_complexity, analyze_signal_flow, detect_circular_dependencies, find_unused_resources, get_performance_monitors, search_files, search_in_files, find_script_references
• Profiling: get_editor_performance

Runtime Tools (require play_scene first)

You MUST call play_scene before using any of these. They interact with the running game:

• Game State: get_game_scene_tree, get_game_node_properties, set_game_node_property, execute_game_script, get_game_screenshot, get_autoload, find_nodes_by_script
• Input Simulation: simulate_key, simulate_mouse_click, simulate_mouse_move, simulate_action, simulate_sequence
• Capture/Recording: capture_frames, record_frames, monitor_properties, start_recording, stop_recording, replay_recording, batch_get_properties
• UI Interaction: find_ui_elements, click_button_by_text, wait_for_node, find_nearby_nodes, navigate_to, move_to
• Testing: run_test_scenario, assert_node_state, assert_screen_text, run_stress_test, get_test_report
• Screenshots: get_game_screenshot, compare_screenshots
• Control: play_scene, stop_scene

Workflow Patterns

Building a scene from scratch

1. create_scene or open_scene
2. Use add_node or batch_add_nodes to add nodes
3. create_script + attach_script for behavior
4. save_scene

Testing gameplay

1. Build scene with editor tools (above)
2. play_scene to start the game
3. Use simulate_key/simulate_mouse_click for input
4. get_game_screenshot or capture_frames to observe results
5. stop_scene when done

Inspecting a project

1. get_project_info for overview
2. get_scene_tree for current scene structure
3. read_script to read code
4. get_node_properties for specific node details

Migrating code properties to inspector

When a script hardcodes visual properties (colors, sizes, positions, theme overrides) that should be in the inspector:

1. read_script to find hardcoded property assignments (e.g. modulate = Color(...), add_theme_color_override(...))
2. get_node_properties to see current inspector values
3. update_property to set the same values as node properties in the inspector
4. edit_script to remove the hardcoded lines from the script
5. save_scene to persist the inspector changes
6. validate_script to verify the script still works

Formatting Rules

execute_editor_script

The code parameter must be valid GDScript. Use _mcp_print(value) to return output.

# Correct
_mcp_print("hello")

# Correct - multi-line
var nodes = []
for child in EditorInterface.get_edited_scene_root().get_children():
    nodes.append(child.name)
_mcp_print(str(nodes))

execute_game_script

Same as above but runs inside the running game. Additional rules:

• No nested functions (func inside func is invalid GDScript)
• Use .get("property") instead of .property for safe access
• Runs in a temporary node — use get_tree() to access the scene tree

batch_add_nodes

Pass an array of node definitions. Nodes are processed in order, so earlier nodes can be parents for later ones:

{
  "nodes": [
    {"type": "Node2D", "name": "Container", "parent_path": "."},
    {"type": "Sprite2D", "name": "Icon", "parent_path": "Container"},
    {"type": "Label", "name": "Title", "parent_path": "Container", "properties": {"text": "Hello"}}
  ]
}

Best Practices

1. Prefer inspector properties over code — When changing visual properties (colors, sizes, theme overrides, transforms, etc.), use update_property to set them directly on the node. This keeps values visible in the Godot inspector and easy to tweak. Only use GDScript when the property isn't available in the inspector or needs to be dynamic at runtime.

Common Pitfalls

1. Never edit project.godot directly — Use set_project_setting instead. The Godot editor overwrites the file.
2. GDScript type inference — Use explicit type annotations in for-loops: for item: String in array instead of for item in array.
3. Reload after script changes — After create_script, call reload_project if the script doesn't take effect.
4. Property values as strings — Properties like position accept string format: "Vector2(100, 200)", "Color(1, 0, 0, 1)".
5. simulate_key duration — Use short durations (0.3-0.5s) for precise movement. Integer seconds (1, 2, 3) cause overshooting.
6. compare_screenshots — Pass file paths (user://screenshot.png), not base64 data.

CLI Mode (Alternative to MCP Tools)

If MCP tools are unavailable or you have a terminal/bash tool, you can control Godot via the CLI. The CLI requires the server to be built first (node build/setup.js install in the server directory).

# Discover available command groups
node /path/to/server/build/cli.js --help

# Discover commands in a group
node /path/to/server/build/cli.js scene --help

# Discover options for a specific command
node /path/to/server/build/cli.js node add --help

# Execute commands
node /path/to/server/build/cli.js project info
node /path/to/server/build/cli.js scene tree
node /path/to/server/build/cli.js node add --type CharacterBody3D --name Player --parent /root/Main
node /path/to/server/build/cli.js script read --path res://player.gd
node /path/to/server/build/cli.js scene play
node /path/to/server/build/cli.js input key --key W --duration 0.5
node /path/to/server/build/cli.js runtime tree

Command groups: project, scene, node, script, editor, input, runtime

Always start by running --help to discover available commands. Use the CLI when MCP tools are not loaded or when you need to reduce context usage.