Godot development

Requirements:

• Godot 4+
• godot-docs MCP server (npm package @fernforestgames/mcp-server-godot-docs)
• godot-editor MCP server (GitHub project fernforestgames/mcp-server-godot-editor installed into addons/)

GDScript workflow

When writing or modifying GDScript, copy this checklist and track your progress:

- [ ] Step 1: Read source files
- [ ] Step 2: Look up relevant Godot documentation
- [ ] Step 3: Write or modify GDScript code
- [ ] Step 4: Import new files with Godot CLI
- [ ] Step 5: Typecheck and validate syntax
- [ ] Step 6: Test the changes

Step 1: Read source files

Read any relevant GDScript source files in the current project.

Step 2: Look up relevant Godot documentation

Use the godot-docs:get_godot_class tool to look up everything about a specific Godot class. Use the godot-docs:search_godot_docs tool to find a string in the Godot documentation.

Step 3: Write or modify GDScript code

Adhere to the following rules while writing GDScript:

• Use the latest Godot 4.5 syntax and features, including typed arrays and dictionaries: Array[int], Dictionary[String, float], etc.
• Always use static typing
• Don't use := type inference declarations for AI-generated code (prefer explicit annotations)
• Prefix private variables/methods with _
• Indent with tabs
• Use @export or dependency injection instead of hardcoded node paths
• Prefer methods with static typing over equivalent StringName variants

Step 4: Import new files with Godot CLI

Run the Godot CLI with --import after adding new files, to make sure they get picked up by the editor:

godot --headless --import

This should be run in the project root directory (where project.godot is located). Remember that any folder containing .gdignore will be skipped during import.

Step 5: Typecheck and validate syntax

Directly invoke the provided check_syntax.sh script to check the syntax of all GDScript files in the project.

For example:

./.claude/skills/godot/scripts/check_syntax.sh

Step 6: Test the changes

Use the testing workflow described below to test your changes.

Testing workflow

Automated tests

Unit tests can be written with the GUT (Godot Unit Test) framework: https://github.com/bitwes/Gut https://gut.readthedocs.io

If not already present in the current project in the addons/ directory, do NOT attempt to install it. Ask the user to install it from the Godot Asset Library instead.

Important: use a sub-agent to write and run GUT tests, as this consumes a lot of tokens.

Writing tests

Test cases should be scripts that extend GutTest:

extends GutTest

# GUT assertions are untyped, so disable this warning
@warning_ignore_start("unsafe_call_argument")

func before_all():
	pass

func before_each():
	pass

func test_passes():
	assert_eq(1, 1)

func test_fails():
	assert_eq("hello", "goodbye")

func after_each():
	pass

func after_all():
	pass

Run the Godot CLI with --import after adding new files, to make sure they get picked up by the editor:

godot --headless --import

This should be run in the project root directory (where project.godot is located).

Assertions

assert_true(got)
assert_false(got)
assert_null(got)
assert_not_null(got)

assert_eq(got, expected)
assert_eq_deep(got, expected)  # Like assert_eq but more detailed failure messages for nested collections
assert_almost_eq(got, expected, error_interval)
assert_ne(got, not_expected)
assert_ne_deep(got, not_expected)
assert_almost_ne(got, not_expected, error_interval)
assert_gt(got, expected)
assert_gte(got, expected)
assert_lt(got, expected)
assert_lte(got, expected)

assert_same(got, expected)  # Checks that reference types (Object, Dictionary, Array) are exactly the same reference
assert_not_same(got, expected)

assert_has(obj, element)
assert_does_not_have(obj, element)

assert_is(obj, class_or_script_obj)
assert_typeof(obj, type_constant)  # TYPE_INT, TYPE_STRING, etc.
assert_not_typeof(obj, type_constant)

assert_engine_error(matching_text)
assert_engine_error_count(count)
assert_push_error(matching_text)
assert_push_error_count(count)
assert_push_warning(matching_text)
assert_push_warning_count(count)

assert_freed(obj)
assert_not_freed(obj)

Helpers

await wait_seconds(10)
await wait_idle_frames(5)  # 5 _process frames
await wait_physics_frames(2)
await wait_for_signal(scene_tree.node_removed, 3)  # time out after 3 seconds
await wait_until(callable, 3)  # time out after 3 seconds

Running tests

Once tests have been written and imported, run them using the GUT command line script:

godot --headless --script addons/gut/gut_cmdln.gd

# Run a specific test file
godot --headless --script addons/gut/gut_cmdln.gd -gtest=res://tests/sample_tests.gd

GUT is configured with an optional res://.gutconfig.json file. A sample can be generated with:

godot --headless --script addons/gut/gut_cmdln.gd -gprint_gutconfig_sample

Interactive testing with the Godot Editor MCP server

The godot-editor MCP server allows you to control running games from the editor, enabling automated UI testing and visual verification.

Starting and stopping scenes

godot-editor:play_main_scene      # Start the project's main scene
godot-editor:play_scene           # Start a specific scene by path (e.g., "res://levels/test.tscn")
godot-editor:stop_playing_scene   # Stop the currently running scene

Important: Always follow up play_main_scene or play_scene with another action (screenshot, input, etc.) or stop_playing_scene. Never leave a scene running indefinitely.

Taking screenshots

Use godot-editor:take_screenshot to capture the current game viewport. The screenshot is returned as an image that you can view directly.

Node interaction

Use godot-editor:click_node and godot-editor:hover_node to interact with controls and nodes (2D or 3D). Use godot-editor:get_node_tree to inspect the current scene tree and determine node paths.

godot-editor:click_node
  node_path: "/root/Main/UI/StartButton"
  button_index: 1  # Optional, defaults to left click
  offset: {x: 0, y: 0}  # Optional offset from center

godot-editor:hover_node
  unique_name: "InventorySlot"

godot-editor:click_node
  accessibility_name: "SubmitButton"

Input synthesis

Use godot-editor:synthesize_input to simulate user input events (only if you cannot use click_node or hover_node).

For example:

• type: "key", keycode: "Space", pressed: true (uses Key enum names)
• type: "mouse_button", button_index: 1, position: {x, y}, pressed: true
• type: "mouse_motion", position: {x, y}
• type: "action", action: "ui_accept", pressed: true

Example workflow for UI testing

1. godot-editor:play_main_scene
2. godot-editor:take_screenshot, verify initial state
3. godot-editor:get_node_tree, check node paths
4. godot-editor:hover_node with unique_name "PlayButton"
5. godot-editor:take_screenshot, verify hover visual feedback
6. godot-editor:click_node with unique_name "PlayButton"
7. godot-editor:take_screenshot, verify button was clicked (new screen, animation, etc.)
8. godot-editor:stop_playing_scene

Godot resource files (.tres, .tscn)

• NEVER manually assign or generate uid:// fields—Godot fills these in automatically

Connecting @exports in scene files

When a script uses @export var some_node: SomeNodeType, you can assign it via a .tscn file:

[node name="MyNode" type="Node3D" parent="." node_paths=PackedStringArray("player", "camera")]
script = ExtResource("1_abc123")
player = NodePath("../Player")
camera = NodePath("CameraPivot/Camera3D")