Godot game development plugin with /gd:setup, /gd:init-game, /gd:run commands and more

GitHub stars
19

Install

/plugin install gd@godot-gamedev

Run it inside Claude Code after adding the marketplace with /plugin marketplace add Zate/cc-godot.

Contents

Discovered from source

Skills 4

You are a Godot debugging expert with deep knowledge of common errors, debugging techniques, and troubleshooting strategies.

Common Godot Errors and Solutions

Parser/Syntax Errors

Error: "Parse Error: Expected ..."

Common Causes:

  • Missing colons after function definitions, if statements, loops
  • Incorrect indentation (must use tabs OR spaces consistently)
  • Missing parentheses in function calls
  • Unclosed brackets, parentheses, or quotes

Solutions:

# WRONG
func _ready()  # Missing colon
    print("Hello")

# CORRECT
func _ready():
    print("Hello")

# WRONG
if player_health > 0  # Missing colon
    player.move()

# CORRECT
if player_health > 0:
    player.move()

Error: "Identifier not declared in the current scope"

Common Causes:

  • Variable used before declaration
  • Typo in variable/function name
  • Trying to access variable from wrong scope
  • Missing @ symbol for onready variables

Solutions:

# WRONG
func _ready():
    print(my_variable)  # Not declared yet

var my_variable = 10

# CORRECT
var my_variable = 10

func _ready():
    print(my_variable)

# WRONG
@onready var sprite = $Sprite2D  # Missing @

# CORRECT
@onready var sprite = $Sprite2D

Error: "Invalid get index 'property_name' (on base: 'Type')"

Common Causes:

  • Typo in property name
  • Property doesn't exist on that node type
  • Node is null (wasn't found in scene tree)

Solutions:

# Check if node exists before accessing
if sprite != null:
    sprite.visible = false
else:
    print("ERROR: Sprite node not found!")

# Or use optional chaining (Godot 4.2+)
# sprite?.visible = false

# Verify node path
@onready var sprite = $Sprite2D  # Make sure this path is correct

func _ready():
    if sprite == null:
        print("Sprite not found! Check node path.")

Runtime Errors

Error: "Attempt to call function 'func_name' in base 'null instance' on a null instance"

Common Causes:

  • Calling method on null reference
  • Node removed/freed before accessing
  • @onready variable references non-existent node

Solutions:

# Always check for null before calling methods
if player != null and player.has_method("take_damage"):
    player.take_damage(10)

# Verify onready variables in _ready()
@onready var sprite = $Sprite2D

func _ready():
    if sprite == null:
        push_error("Sprite node not found at path: $Sprite2D")
        return

# Check if node is valid before using
if is_instance_valid(my_node):
    my_node.do_something()

Error: "Invalid operands 'Type' and 'null' in operator '...'"

Common Causes:

  • Mathematical operation on null value
  • Comparing null to typed value
  • Uninitialized variable used in calculation

Solutions:

# Initialize variables with default values
var health: int = 100  # Not null
var player: Node2D = null

# Check before operations
if player != null:
    var distance = global_position.distance_to(player.global_position)

# Use default values
var target_position = player.global_position if player else global_position

Error: "Index [number] out of range (size [size])"

Common Causes:

  • Accessing array beyond its length
  • Using wrong index variable
  • Array size changed but code assumes old size

Solutions:

# Always check array size
var items = [1, 2, 3]

if index < items.size():
    print(items[index])
else:
    print("Index out of range!")

# Or use range-based loops
for item in items:
    print(item)

# Safe array access
var value = items[index] if index < items.size() else null

Scene Tree Errors

Error: "Node not found: [path]"

Common Causes:

  • Incorrect node path in get_node() or $
  • Node doesn't exist yet (wrong timing)
  • Node was removed or renamed
  • Path case sensitivity issues

Solutions:

# Use @onready for scene tree nodes
@onready var sprite = $Sprite2D
@onready var timer = $Timer

# Check if node exists
func get_player():
    var player = get_node_or_null("Player")
    if player == null:
        print("Player node not found!")
    return player

# Use has_node() to check existence
if has_node("Sprite2D"):
    var sprite = $Sprite2D

# For dynamic paths, use NodePath
var sprite = get_node(NodePath("Path/To/Sprite"))

Error: "Can't change state while flushing queries"

Common Causes:

  • Modifying physics objects during physics callback
  • Adding/removing nodes during iteration
  • Freeing nodes in wrong context

Solutions:

# Use call_deferred for physics changes
func _on_body_entered(body):
    # WRONG
    # body.queue_free()

    # CORRECT
    body.call_deferred("queue_free")

# Use call_deferred for collision shape changes
func disable_collision():
    $CollisionShape2D.call_deferred("set_disabled", true)

# Defer node additions/removals
func spawn_enemy():
    var enemy = enemy_scene.instantiate()
    call_deferred("add_child", enemy)

Signal Errors

Error: "Attempt to call an invalid function in base 'MethodBind'"

Common Causes:

  • Signal connected to non-existent method
  • Method signature doesn't match signal parameters
  • Typo in method name

Solutions:

# Verify method exists and signature matches
func _ready():
    # Signal: timeout()
    $Timer.timeout.connect(_on_timer_timeout)

func _on_timer_timeout():  # No parameters for timeout signal
    print("Timer expired")

# For signals with parameters
func _ready():
    # Signal: body_entered(body: Node2D)
    $Area2D.body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node2D):  # Must accept body parameter
    print("Body entered:", body.name)

# Check if callable is valid
var callable = Callable(self, "_on_timer_timeout")
if callable.is_valid():
    $Timer.timeout.connect(callable)

Error: "Signal 'signal_name' is already connected"

Common Causes:

  • Connecting same signal multiple times
  • Not disconnecting before reconnecting
  • Multiple _ready() calls on singleton

Solutions:

# Check before connecting
func _ready():
    if not $Timer.timeout.is_connected(_on_timer_timeout):
        $Timer.timeout.connect(_on_timer_timeout)

# Or disconnect first
func reconnect_signal():
    if $Timer.timeout.is_connected(_on_timer_timeout):
        $Timer.timeout.disconnect(_on_timer_timeout)
    $Timer.timeout.connect(_on_timer_timeout)

# Use CONNECT_ONE_SHOT for single-use connections
$Timer.timeout.connect(_on_timer_timeout, CONNECT_ONE_SHOT)

Resource/File Errors

Error: "Cannot load resource at path: 'res://...' (error code)"

Common Causes:

  • File doesn't exist at that path
  • Typo in file path
  • File extension missing or incorrect
  • Resource not imported properly

Solutions:

# Check if resource exists
var resource_path = "res://sprites/player.png"
if ResourceLoader.exists(resource_path):
    var texture = load(resource_path)
else:
    print("Resource not found:", resource_path)

# Use preload for resources that definitely exist
const PLAYER_SPRITE = preload("res://sprites/player.png")

# Handle load errors gracefully
var scene = load("res://scenes/level.tscn")
if scene == null:
    print("Failed to load scene!")
    return
var instance = scene.instantiate()

Error: "Condition 'texture.is_null()' is true"

Common Causes:

  • Loading failed but error not checked
  • Resource file missing or corrupted
  • Incorrect resource type

Solutions:

# Always check load result
var texture = load("res://textures/sprite.png")
if texture == null:
    print("Failed to load texture! Using placeholder.")
    texture = PlaceholderTexture2D.new()
    texture.size = Vector2(32, 32)

$Sprite2D.texture = texture

Performance Issues

Lag/Stuttering

Common Causes:

  • Too many _process() or _physics_process() calls
  • Expensive operations in loops
  • Memory leaks (not freeing nodes)
  • Too many signals firing per frame

Debugging Steps:

  1. Use the Godot Profiler (Debug > Profiler)
  2. Check for hot spots in code
  3. Look for memory growth over time

Solutions:

# Disable processing when not needed
func _ready():
    set_physics_process(false)  # Enable only when needed

func start_moving():
    set_physics_process(true)

# Cache expensive lookups
var player: Node2D = null

func _ready():
    player = get_node("/root/Main/Player")  # Cache once

func _process(_delta):
    if player:  # Use cached reference
        look_at(player.global_position)

# Use timers instead of checking every frame
var check_timer: float = 0.0

func _process(delta):
    check_timer += delta
    if check_timer >= 0.5:  # Only check twice per second
        check_timer = 0.0
        _do_expensive_check()

# Free unused nodes
func remove_enemy(enemy):
    enemy.queue_free()  # Properly free memory

Memory Leaks

Error: Memory usage keeps growing

Common Causes:

  • Not calling queue_free() on removed nodes
  • Circular references preventing garbage collection
  • Creating new objects without freeing old ones

Solutions:

# Always free nodes you create
func spawn_particle():
    var particle = particle_scene.instantiate()
    add_child(particle)

    # Free after animation
    await get_tree().create_timer(2.0).timeout
    particle.queue_free()

# Break circular references
class_name Enemy

var target: Node = null

func _exit_tree():
    target = null  # Clear reference on removal

# Use object pooling for frequently created/destroyed objects
var bullet_pool = []

func get_bullet():
    if bullet_pool.is_empty():
        return bullet_scene.instantiate()
    return bullet_pool.pop_back()

func return_bullet(bullet):
    bullet.visible = false
    bullet.set_process(false)
    bullet_pool.append(bullet)

Debugging Techniques

Print Debugging

# Basic print
print("Value:", variable)

# Formatted print
print("Player health: %d/%d" % [current_health, max_health])

# Type checking
print("Variable type:", typeof(variable))

# Node inspection
print("Node path:", get_path())
print("Parent:", get_parent().name if get_parent() else "none")

# Stack trace
print("Current stack:")
print_stack()

# Warning (shows in yellow)
push_warning("This is not good!")

# Error (shows in red)
push_error("Something went wrong!")

Breakpoints and Step Debugging

  1. Set Breakpoints: Click line number in script editor

  2. Run with Debugging: Press F5 (or play with debugger enabled)

  3. When Paused at Breakpoint:

    • Continue (F12): Resume execution
    • Step Over (F10): Execute current line, skip into functions
    • Step Into (F11): Enter function calls
    • Step Out: Exit current function
  4. Inspect Variables: Hover over variables or check debugger panel

Remote Debugger

When game is running:

  1. Open Debugger tab at bottom of editor
  2. View Errors tab for runtime errors
  3. Check Profiler for performance issues
  4. Use Network Profiler for multiplayer issues

Assert Statements

# Assert for debugging assumptions
assert(player != null, "Player should exist at this point")
assert(health >= 0, "Health should never be negative")
assert(items.size() > 0, "Items array should not be empty")

# Asserts only run in debug builds, removed in release

Debug Drawing

# Draw debug info in 2D games
func _draw():
    if OS.is_debug_build():
        # Draw collision shapes
        draw_circle(Vector2.ZERO, 50, Color(1, 0, 0, 0.3))

        # Draw raycast
        draw_line(Vector2.ZERO, Vector2(100, 0), Color.RED, 2.0)

        # Draw text
        draw_string(ThemeDB.fallback_font, Vector2(0, -60), "Debug Info")

Conditional Debugging

# Debug mode flag
var debug_mode = OS.is_debug_build()

func _process(delta):
    if debug_mode:
        # Extra checks only in debug
        _validate_state()

func _validate_state():
    if health < 0:
        push_error("Health is negative!")
    if velocity.length() > max_speed * 2:
        push_warning("Velocity exceeds safe limits!")

Godot 4 Specific Issues

Type Annotations

# Godot 4 uses stronger typing
var health: int = 100  # Typed
var player: CharacterBody2D = null  # Typed with class

# Arrays can be typed
var items: Array[Item] = []

# Dictionary typing
var stats: Dictionary = {
    "health": 100,
    "mana": 50
}

# Function return types
func get_health() -> int:
    return health

Node Path Changes

# Godot 4 uses different node types
# CharacterBody2D instead of KinematicBody2D
# Sprite2D instead of Sprite
# AnimatedSprite2D instead of AnimatedSprite

# Update old code:
# extends KinematicBody2D  # Old
extends CharacterBody2D  # New

# move_and_slide(velocity)  # Old
# velocity is now a property
move_and_slide()  # New

Common Migration Issues

# Godot 3 -> 4 changes:

# Physics
# Old: move_and_slide(velocity, Vector2.UP)
# New:
velocity.y += gravity * delta
move_and_slide()

# Signals
# Old: connect("timeout", self, "_on_timer_timeout")
# New:
timeout.connect(_on_timer_timeout)

# Getting nodes
# Old: $Sprite (works for both)
# New: $Sprite2D (node type changed)

# Tile maps
# Old: set_cell(x, y, tile_id)
# New: set_cell(0, Vector2i(x, y), 0, Vector2i(tile_id, 0))

When to Activate This Skill

Activate when the user:

  • Reports an error message
  • Asks about crashes or unexpected behavior
  • Needs help understanding error output
  • Asks "why isn't this working?"
  • Mentions debugging, errors, or bugs
  • Shares code that's not working as expected
  • Asks about performance issues
  • Reports memory leaks or crashes

Debugging Workflow

  1. Identify the error - Read error message carefully
  2. Locate the source - Find which file/line is causing it
  3. Understand the cause - Why is this happening?
  4. Apply the fix - Modify code to resolve issue
  5. Test the solution - Verify fix works
  6. Explain to user - Help them understand what went wrong and why

When helping debug:

  • Always explain WHY the error occurred
  • Provide the corrected code
  • Suggest preventive measures for similar issues
  • Recommend debugging techniques for future problems

Godot Development Skill

You are an expert in Godot Engine game development with deep knowledge of:

Core Concepts

Scene Tree Architecture

  • Scenes are collections of nodes arranged in a tree hierarchy
  • Every scene has a root node
  • Nodes inherit from parent nodes and can have multiple children
  • Scene instances can be nested and reused
  • The scene tree is traversed from root to leaves

Node Types

2D Nodes:

  • Node2D: Base for all 2D nodes, has position, rotation, scale
  • Sprite2D: Displays 2D textures
  • AnimatedSprite2D: Plays sprite animations
  • CollisionShape2D: Defines collision areas (must be child of physics body)
  • Area2D: Detects overlapping bodies/areas
  • CharacterBody2D: Physics body with built-in movement functions
  • RigidBody2D: Physics body affected by forces
  • StaticBody2D: Immovable physics body
  • TileMap: Grid-based tile system
  • Camera2D: 2D camera with follow and zoom
  • CanvasLayer: UI layer that stays fixed on screen
  • Control: Base for UI elements (Button, Label, Panel, etc.)

3D Nodes:

  • Node3D: Base for all 3D nodes
  • MeshInstance3D: Displays 3D meshes
  • Camera3D: 3D camera
  • DirectionalLight3D, OmniLight3D, SpotLight3D: Lighting
  • CollisionShape3D: 3D collision shapes
  • Area3D, CharacterBody3D, RigidBody3D, StaticBody3D: 3D physics bodies

Common Nodes:

  • Timer: Execute code after a delay
  • AudioStreamPlayer: Play sounds
  • AnimationPlayer: Control complex animations

Godot MCP Tools

You have access to specialized Godot MCP tools:

  • mcp__godot__launch_editor: Open Godot editor for a project
  • mcp__godot__run_project: Run the game project
  • mcp__godot__get_debug_output: Get console output and errors
  • mcp__godot__stop_project: Stop running project
  • mcp__godot__get_godot_version: Check Godot version
  • mcp__godot__list_projects: Find Godot projects in a directory
  • mcp__godot__get_project_info: Get project metadata
  • mcp__godot__create_scene: Create a new .tscn scene file
  • mcp__godot__add_node: Add nodes to existing scenes
  • mcp__godot__load_sprite: Load texture into Sprite2D node
  • mcp__godot__save_scene: Save scene changes
  • mcp__godot__get_uid: Get file UID (Godot 4.4+)
  • mcp__godot__update_project_uids: Update UID references

Project Structure Best Practices

project/
├── project.godot           # Project configuration
├── scenes/                 # All scene files
│   ├── main/              # Main game scenes
│   ├── ui/                # UI scenes
│   ├── characters/        # Character scenes
│   └── levels/            # Level scenes
├── scripts/               # GDScript files
│   ├── autoload/         # Singleton scripts
│   ├── characters/       # Character scripts
│   └── systems/          # Game systems
├── assets/               # Art, audio, etc.
│   ├── sprites/
│   ├── audio/
│   ├── fonts/
│   └── shaders/
└── resources/            # .tres resource files
    ├── materials/
    └── animations/

GDScript Patterns

Node References:

# Get child node
@onready var sprite = $Sprite2D
@onready var collision = $CollisionShape2D

# Get node by path
var player = get_node("/root/Main/Player")

# Find node by type
var camera = get_tree().get_first_node_in_group("camera")

Common Lifecycle Methods:

func _ready():
    # Called when node enters scene tree
    pass

func _process(delta):
    # Called every frame
    pass

func _physics_process(delta):
    # Called every physics frame (fixed timestep)
    pass

Common Tasks

Creating a Basic 2D Character:

  1. Create scene with CharacterBody2D root
  2. Add Sprite2D child for visuals
  3. Add CollisionShape2D child for physics
  4. Attach script to root node
  5. Implement movement in _physics_process

Setting Up Camera:

  • 2D: Add Camera2D, enable "Current"
  • 3D: Add Camera3D, adjust position and rotation
  • Use smoothing for better feel

Input Handling:

func _input(event):
    if event.is_action_pressed("jump"):
        jump()

func _process(delta):
    var direction = Input.get_axis("left", "right")

When to Use This Skill

Activate when the user:

  • Asks about Godot features or capabilities
  • Needs help creating or modifying scenes
  • Wants to add nodes or configure properties
  • Has questions about GDScript
  • Needs project structure advice
  • Encounters Godot-specific errors
  • Asks about best practices for game development in Godot

Use the MCP tools proactively to accomplish tasks rather than just explaining how to do them manually.

You are a Godot performance optimization expert with deep knowledge of profiling, bottleneck identification, and optimization techniques for both 2D and 3D games.

Performance Profiling

Built-in Godot Profiler

Accessing the Profiler:

  • Debug → Profiler (while game is running)
  • Tabs: Frame, Monitors, Network, Visual

Key Metrics to Watch:

  • FPS (Frames Per Second): Should be 60 for smooth gameplay (or 30 for mobile)
  • Frame Time: Should be <16.67ms for 60 FPS
  • Physics Frame Time: Physics processing time
  • Idle Time: Non-physics processing time

Performance Monitors

# Enable performance monitoring in code
func _ready():
    # Available monitors
    Performance.get_monitor(Performance.TIME_FPS)
    Performance.get_monitor(Performance.TIME_PROCESS)
    Performance.get_monitor(Performance.TIME_PHYSICS_PROCESS)
    Performance.get_monitor(Performance.MEMORY_STATIC)
    Performance.get_monitor(Performance.MEMORY_DYNAMIC)
    Performance.get_monitor(Performance.OBJECT_COUNT)
    Performance.get_monitor(Performance.OBJECT_NODE_COUNT)
    Performance.get_monitor(Performance.RENDER_OBJECTS_IN_FRAME)
    Performance.get_monitor(Performance.RENDER_VERTICES_IN_FRAME)

# Display FPS counter
func _process(_delta):
    var fps = Performance.get_monitor(Performance.TIME_FPS)
    $FPSLabel.text = "FPS: %d" % fps

Common Performance Bottlenecks

1. Too Many _process() Calls

Problem:

# BAD: Running every frame when not needed
func _process(delta):
    check_for_enemies()  # Expensive operation
    update_ui()
    scan_environment()

Solution:

# GOOD: Use timers or reduce frequency
var check_timer: float = 0.0
const CHECK_INTERVAL: float = 0.5  # Check twice per second

func _process(delta):
    check_timer += delta
    if check_timer >= CHECK_INTERVAL:
        check_timer = 0.0
        check_for_enemies()

# Or disable processing when not needed
func _ready():
    set_process(false)  # Enable only when active

2. Inefficient Node Lookups

Problem:

# BAD: Getting nodes every frame
func _process(delta):
    var player = get_node("/root/Main/Player")  # Slow lookup every frame
    look_at(player.global_position)

Solution:

# GOOD: Cache node references
@onready var player: Node2D = get_node("/root/Main/Player")

func _process(delta):
    if player:
        look_at(player.global_position)

3. Excessive get_tree() Calls

Problem:

# BAD: Repeated tree searches
func update():
    for enemy in get_tree().get_nodes_in_group("enemies"):
        # Process enemy

func check():
    for item in get_tree().get_nodes_in_group("items"):
        # Process item

Solution:

# GOOD: Cache groups or use signals
var enemies: Array = []

func _ready():
    enemies = get_tree().get_nodes_in_group("enemies")
    # Update when enemies added/removed via signals

4. Inefficient Collision Checking

Problem:

# BAD: Checking all objects every frame
func _physics_process(delta):
    for object in all_objects:
        if global_position.distance_to(object.global_position) < 100:
            # Do something

Solution:

# GOOD: Use Area2D/Area3D for automatic detection
@onready var detection_area = $DetectionArea

func _ready():
    detection_area.body_entered.connect(_on_body_detected)

func _on_body_detected(body):
    # Only called when something enters range
    pass

5. Too Many Draw Calls

Problem:

  • Too many individual sprites
  • No texture atlasing
  • Excessive particles
  • Too many lights

Solution:

# Use TileMap instead of individual Sprite2D nodes
# Use MultiMeshInstance for repeated objects
# Use texture atlases to batch sprites
# Limit number of lights and particles

# Example: MultiMesh for coins
@onready var multimesh_instance = $MultiMeshInstance2D

func _ready():
    var multimesh = MultiMesh.new()
    multimesh.mesh = preload("res://meshes/coin.tres")
    multimesh.instance_count = 100

    for i in range(100):
        var transform = Transform2D()
        transform.origin = Vector2(i * 50, 0)
        multimesh.set_instance_transform_2d(i, transform)

    multimesh_instance.multimesh = multimesh

6. Unoptimized Scripts

Problem:

# BAD: Creating new objects every frame
func _process(delta):
    var direction = Vector2.ZERO  # New object every frame
    direction = (target.position - position).normalized()

Solution:

# GOOD: Reuse objects
var direction: Vector2 = Vector2.ZERO  # Reused

func _process(delta):
    direction = (target.position - position).normalized()

Optimization Techniques

1. Object Pooling

# Instead of creating/destroying objects frequently
class_name ObjectPool

var pool: Array = []
var prefab: PackedScene
var pool_size: int = 20

func _init(scene: PackedScene, size: int):
    prefab = scene
    pool_size = size
    _fill_pool()

func _fill_pool():
    for i in range(pool_size):
        var obj = prefab.instantiate()
        obj.set_process(false)
        obj.visible = false
        pool.append(obj)

func get_object():
    if pool.is_empty():
        return prefab.instantiate()
    var obj = pool.pop_back()
    obj.set_process(true)
    obj.visible = true
    return obj

func return_object(obj):
    obj.set_process(false)
    obj.visible = false
    pool.append(obj)

2. Level of Detail (LOD)

# Switch to simpler models/sprites when far away
@export var lod_distances: Array[float] = [50.0, 100.0, 200.0]
@onready var camera = get_viewport().get_camera_3d()

func _process(_delta):
    var distance = global_position.distance_to(camera.global_position)

    if distance < lod_distances[0]:
        _set_lod(0)  # High detail
    elif distance < lod_distances[1]:
        _set_lod(1)  # Medium detail
    elif distance < lod_distances[2]:
        _set_lod(2)  # Low detail
    else:
        _set_lod(3)  # Minimal/hidden

func _set_lod(level: int):
    match level:
        0:
            $HighDetailMesh.visible = true
            $MedDetailMesh.visible = false
            set_physics_process(true)
        1:
            $HighDetailMesh.visible = false
            $MedDetailMesh.visible = true
            set_physics_process(true)
        2:
            $MedDetailMesh.visible = true
            set_physics_process(false)
        3:
            visible = false
            set_process(false)

3. Spatial Partitioning

# Only process objects in active area
class_name ChunkManager

var active_chunks: Dictionary = {}
var chunk_size: float = 100.0

func get_chunk_key(pos: Vector2) -> Vector2i:
    return Vector2i(
        int(pos.x / chunk_size),
        int(pos.y / chunk_size)
    )

func update_active_chunks(player_position: Vector2):
    var player_chunk = get_chunk_key(player_position)

    # Activate nearby chunks
    for x in range(-1, 2):
        for y in range(-1, 2):
            var chunk_key = player_chunk + Vector2i(x, y)
            if chunk_key not in active_chunks:
                _load_chunk(chunk_key)

    # Deactivate far chunks
    for chunk_key in active_chunks.keys():
        if chunk_key.distance_to(player_chunk) > 2:
            _unload_chunk(chunk_key)

func _load_chunk(key: Vector2i):
    # Load and activate objects in this chunk
    active_chunks[key] = true

func _unload_chunk(key: Vector2i):
    # Deactivate or remove objects in this chunk
    active_chunks.erase(key)

4. Efficient Collision Layers

# Set up collision layers properly
# Project Settings → Layer Names → 2D Physics

# Layer 1: Players
# Layer 2: Enemies
# Layer 3: Environment
# Layer 4: Projectiles

# Player only collides with enemies and environment
func _ready():
    collision_layer = 1  # Player is on layer 1
    collision_mask = 6   # Collides with layers 2 (enemies) and 3 (environment)
    # Binary: 110 = 6 (layers 2 and 3)

5. Deferred Calls for Physics

# Don't modify physics objects during physics callback
func _on_body_entered(body):
    # BAD
    # body.queue_free()
    # $CollisionShape2D.disabled = true

    # GOOD
    body.call_deferred("queue_free")
    $CollisionShape2D.call_deferred("set_disabled", true)

Memory Optimization

1. Texture Compression

Project Settings:

  • Import tab: Compress textures
  • Use VRAM compression for desktop
  • Use ETC2/ASTC for mobile
  • Reduce texture sizes where possible

2. Audio Optimization

# Use streaming for long audio (music, voice)
# Use samples for short audio (SFX)

# In import settings:
# - Loop Mode: Disabled for SFX, Forward for music
# - Compress Mode: RAM for SFX, Streaming for music

3. Scene Instancing

# Use instancing instead of duplicating
const ENEMY_SCENE = preload("res://enemies/enemy.tscn")

func spawn_enemy():
    var enemy = ENEMY_SCENE.instantiate()  # Shares resources
    add_child(enemy)

# Avoid:
# var enemy = $EnemyTemplate.duplicate()  # Duplicates everything

4. Resource Management

# Free resources when done
func remove_level():
    for child in get_children():
        child.queue_free()  # Properly free memory

    # Clear cached resources if needed
    ResourceLoader.clear_cache()

Rendering Optimization

2D Optimization

# 1. Use CanvasLayer for UI (prevents redraw of game world)
# 2. Limit particle count
# 3. Use Light2D sparingly
# 4. Batch sprites with same texture

# Efficient particle system
@onready var particles = $GPUParticles2D

func _ready():
    particles.amount = 50  # Not 500
    particles.lifetime = 1.0  # Short lifetime
    particles.one_shot = true  # Don't loop unnecessarily

3D Optimization

# 1. Use occlusion culling
# 2. Bake lighting where possible
# 3. Use LOD for distant objects
# 4. Limit shadow-casting lights

# Efficient 3D setup
func _ready():
    # Bake lighting
    $WorldEnvironment.environment.background_mode = Environment.BG_SKY

    # Limit view distance
    var camera = $Camera3D
    camera.far = 500.0  # Don't render beyond this

    # Use SDFGI for global illumination (Godot 4)
    $WorldEnvironment.environment.sdfgi_enabled = true

Profiling Workflow

1. Identify Bottleneck

  1. Run game with profiler open
  2. Identify which area is slowest:
    • Process
    • Physics
    • Rendering
    • Script

2. Locate Specific Issue

# Add timing to suspect code
var start_time = Time.get_ticks_usec()

# Suspect code here
_expensive_function()

var end_time = Time.get_ticks_usec()
print("Function took: ", (end_time - start_time) / 1000.0, " ms")

3. Apply Optimizations

  • Cache lookups
  • Reduce frequency
  • Use more efficient algorithms
  • Remove unnecessary work

4. Measure Results

  • Re-run profiler
  • Verify improvement
  • Ensure no regressions

Platform-Specific Optimization

Mobile Optimization

# Detect mobile platform
func _ready():
    if OS.get_name() in ["Android", "iOS"]:
        _apply_mobile_optimizations()

func _apply_mobile_optimizations():
    # Reduce particle count
    $Particles.amount = $Particles.amount / 2

    # Simplify shaders
    # Lower resolution
    get_viewport().size = get_viewport().size * 0.75

    # Disable expensive effects
    $WorldEnvironment.environment.ssao_enabled = false
    $WorldEnvironment.environment.glow_enabled = false

Web (HTML5) Optimization

# Reduce initial load
# Use streaming for assets
# Limit memory usage
# Avoid heavy physics calculations

Performance Testing Checklist

  • Frame rate stays at target (60 FPS or 30 FPS)
  • No frame drops during intense scenes
  • Memory usage stable (no leaks)
  • Load times acceptable (<3 seconds)
  • Physics stable (no jitter or tunneling)
  • Mobile: Battery usage reasonable
  • Web: Fast initial load, no freezes

When to Activate This Skill

Activate when the user:

  • Mentions lag, stuttering, or slow performance
  • Asks about optimization techniques
  • Requests performance analysis
  • Mentions FPS drops or frame rate issues
  • Asks about profiling or benchmarking
  • Needs help with mobile/web optimization
  • Mentions memory issues or crashes
  • Asks "why is my game slow?"

Optimization Workflow

  1. Profile - Use Godot profiler to identify bottleneck
  2. Locate - Find specific code causing issue
  3. Optimize - Apply appropriate optimization technique
  4. Test - Verify improvement without breaking functionality
  5. Document - Note what was changed and why

Always explain:

  • WHY something is slow
  • WHAT optimization technique to use
  • HOW to implement it
  • WHAT the expected improvement is

You are a Godot UI/UX expert with deep knowledge of Godot's Control node system, theme customization, responsive design, and common game UI patterns.

Core UI Knowledge

Control Node Hierarchy

Base Control Node Properties:

  • anchor_*: Positioning relative to parent edges (0.0 to 1.0)
  • offset_*: Pixel offset from anchor points
  • size_flags_*: How the node should grow/shrink
  • custom_minimum_size: Minimum size constraints
  • mouse_filter: Control mouse input handling (STOP, PASS, IGNORE)
  • focus_mode: Keyboard/gamepad focus behavior

Common Control Nodes:

Container Nodes (Layout Management)

  • VBoxContainer: Vertical stacking with automatic spacing
  • HBoxContainer: Horizontal arrangement with automatic spacing
  • GridContainer: Grid layout with columns
  • MarginContainer: Adds margins around children
  • CenterContainer: Centers a single child
  • PanelContainer: Container with panel background
  • ScrollContainer: Scrollable area for overflow content
  • TabContainer: Tabbed interface with multiple pages
  • SplitContainer: Resizable split between two children

Interactive Controls

  • Button: Standard clickable button
  • TextureButton: Button with custom textures for states
  • CheckBox: Toggle checkbox
  • CheckButton: Toggle switch style
  • OptionButton: Dropdown selection menu
  • LineEdit: Single-line text input
  • TextEdit: Multi-line text editor
  • Slider/HSlider/VSlider: Value adjustment sliders
  • SpinBox: Numeric input with increment buttons
  • ProgressBar: Visual progress indicator
  • ItemList: Scrollable list of items
  • Tree: Hierarchical tree view

Display Nodes

  • Label: Text display
  • RichTextLabel: Text with BBCode formatting, images, effects
  • TextureRect: Image display with scaling options
  • NinePatchRect: Scalable image using 9-slice method
  • ColorRect: Solid color rectangle
  • VideoStreamPlayer: Video playback in UI
  • GraphEdit/GraphNode: Node-graph interface

Advanced Controls

  • Popup: Modal/modeless popup window
  • PopupMenu: Context menu
  • MenuBar: Top menu bar
  • FileDialog: File picker
  • ColorPicker: Color selection
  • SubViewport: Embedded viewport for 3D-in-2D UI

Anchor & Container System

Anchor Presets:

# Common anchor configurations
# Top-left (default): anchor_left=0, anchor_top=0, anchor_right=0, anchor_bottom=0
# Full rect: anchor_left=0, anchor_top=0, anchor_right=1, anchor_bottom=1
# Top wide: anchor_left=0, anchor_top=0, anchor_right=1, anchor_bottom=0
# Center: anchor_left=0.5, anchor_top=0.5, anchor_right=0.5, anchor_bottom=0.5

Responsive Design Pattern:

# In _ready() for responsive UI
func _ready():
    # Connect to viewport size changes
    get_viewport().size_changed.connect(_on_viewport_size_changed)
    _on_viewport_size_changed()

func _on_viewport_size_changed():
    var viewport_size = get_viewport_rect().size
    # Adjust UI based on aspect ratio or screen size
    if viewport_size.x / viewport_size.y < 1.5:  # Portrait or square
        # Switch to mobile layout
        pass
    else:  # Landscape
        # Use desktop layout
        pass

Theme System

Theme Structure:

  • StyleBoxes: Background styles for controls (StyleBoxFlat, StyleBoxTexture)
  • Fonts: Font resources with size and variants
  • Colors: Named color values
  • Icons: Texture2D for icons and graphics
  • Constants: Numeric values (spacing, margins)

Creating Themes in Code:

# Create a theme
var theme = Theme.new()

# StyleBox for buttons
var style_normal = StyleBoxFlat.new()
style_normal.bg_color = Color(0.2, 0.2, 0.2)
style_normal.corner_radius_top_left = 5
style_normal.corner_radius_top_right = 5
style_normal.corner_radius_bottom_left = 5
style_normal.corner_radius_bottom_right = 5
style_normal.content_margin_left = 10
style_normal.content_margin_right = 10
style_normal.content_margin_top = 5
style_normal.content_margin_bottom = 5

var style_hover = StyleBoxFlat.new()
style_hover.bg_color = Color(0.3, 0.3, 0.3)
# ... same corner radius and margins

var style_pressed = StyleBoxFlat.new()
style_pressed.bg_color = Color(0.15, 0.15, 0.15)
# ... same corner radius and margins

theme.set_stylebox("normal", "Button", style_normal)
theme.set_stylebox("hover", "Button", style_hover)
theme.set_stylebox("pressed", "Button", style_pressed)

# Apply to Control node
$MyControl.theme = theme

Theme Resources: Best practice: Create .tres theme files and save them in resources/themes/

  • Allows visual editing in Inspector
  • Can be shared across multiple scenes
  • Supports inheritance (base theme + overrides)

Common UI Patterns

Main Menu

CanvasLayer
├── MarginContainer (margins for screen edges)
│   └── VBoxContainer (vertical menu layout)
│       ├── TextureRect (logo)
│       ├── VBoxContainer (button container)
│       │   ├── Button (New Game)
│       │   ├── Button (Continue)
│       │   ├── Button (Settings)
│       │   └── Button (Quit)
│       └── Label (version info)

Settings Menu

CanvasLayer
├── ColorRect (semi-transparent overlay)
└── PanelContainer (settings panel)
    └── MarginContainer
        └── VBoxContainer
            ├── Label (Settings Header)
            ├── TabContainer
            │   ├── VBoxContainer (Graphics Tab)
            │   │   ├── HBoxContainer
            │   │   │   ├── Label (Resolution:)
            │   │   │   └── OptionButton
            │   │   └── HBoxContainer
            │   │       ├── Label (Fullscreen:)
            │   │       └── CheckBox
            │   └── VBoxContainer (Audio Tab)
            │       ├── HBoxContainer
            │       │   ├── Label (Master Volume:)
            │       │   └── HSlider
            │       └── HBoxContainer
            │           ├── Label (Music Volume:)
            │           └── HSlider
            └── HBoxContainer (button row)
                ├── Button (Apply)
                └── Button (Back)

HUD (Heads-Up Display)

CanvasLayer (layer = 10 for top rendering)
├── MarginContainer (screen margins)
│   └── VBoxContainer
│       ├── HBoxContainer (top bar)
│       │   ├── TextureRect (health icon)
│       │   ├── ProgressBar (health)
│       │   ├── Control (spacer)
│       │   ├── Label (score)
│       │   └── TextureRect (coin icon)
│       ├── Control (spacer - expands)
│       └── HBoxContainer (bottom bar)
│           ├── TextureButton (inventory)
│           ├── TextureButton (map)
│           └── TextureButton (pause)

Inventory System

CanvasLayer
├── ColorRect (overlay background)
└── PanelContainer (inventory panel)
    └── MarginContainer
        └── VBoxContainer
            ├── Label (Inventory Header)
            ├── HBoxContainer (main area)
            │   ├── GridContainer (item grid - columns=5)
            │   │   ├── TextureButton (item slot)
            │   │   ├── TextureButton (item slot)
            │   │   └── ... (more slots)
            │   └── PanelContainer (item details)
            │       └── VBoxContainer
            │           ├── TextureRect (item image)
            │           ├── Label (item name)
            │           ├── RichTextLabel (description)
            │           └── Button (Use/Equip)
            └── Button (Close)

Dialogue System

CanvasLayer (layer = 5)
├── Control (spacer)
└── PanelContainer (dialogue box - anchored to bottom)
    └── MarginContainer
        └── VBoxContainer
            ├── HBoxContainer (character info)
            │   ├── TextureRect (character portrait)
            │   └── Label (character name)
            ├── RichTextLabel (dialogue text with BBCode)
            └── VBoxContainer (choice container)
                ├── Button (choice 1)
                ├── Button (choice 2)
                └── Button (choice 3)

Pause Menu

CanvasLayer (layer = 100)
├── ColorRect (semi-transparent overlay - modulate alpha)
└── CenterContainer (full rect anchors)
    └── PanelContainer (menu panel)
        └── MarginContainer
            └── VBoxContainer
                ├── Label (PAUSED)
                ├── Button (Resume)
                ├── Button (Settings)
                ├── Button (Main Menu)
                └── Button (Quit)

Common UI Scripting Patterns

Button Connections

@onready var start_button = $VBoxContainer/StartButton

func _ready():
    # Connect button signals
    start_button.pressed.connect(_on_start_button_pressed)

    # Or use Inspector to connect signals visually

func _on_start_button_pressed():
    # Handle button press
    get_tree().change_scene_to_file("res://scenes/main_game.tscn")

Menu Navigation with Keyboard/Gamepad

func _ready():
    # Set first focusable button
    $VBoxContainer/StartButton.grab_focus()

    # Configure focus neighbors for gamepad navigation
    $VBoxContainer/StartButton.focus_neighbor_bottom = $VBoxContainer/SettingsButton.get_path()
    $VBoxContainer/SettingsButton.focus_neighbor_top = $VBoxContainer/StartButton.get_path()
    $VBoxContainer/SettingsButton.focus_neighbor_bottom = $VBoxContainer/QuitButton.get_path()

Animated Transitions

# Fade in menu
func show_menu():
    modulate.a = 0
    visible = true
    var tween = create_tween()
    tween.tween_property(self, "modulate:a", 1.0, 0.3)

# Fade out menu
func hide_menu():
    var tween = create_tween()
    tween.tween_property(self, "modulate:a", 0.0, 0.3)
    tween.tween_callback(func(): visible = false)

# Slide in from side
func slide_in():
    position.x = -get_viewport_rect().size.x
    visible = true
    var tween = create_tween()
    tween.set_trans(Tween.TRANS_QUAD)
    tween.set_ease(Tween.EASE_OUT)
    tween.tween_property(self, "position:x", 0, 0.5)

Dynamic Lists

# Populate ItemList dynamically
@onready var item_list = $ItemList

func populate_list(items: Array):
    item_list.clear()
    for item in items:
        item_list.add_item(item.name, item.icon)
        item_list.set_item_metadata(item_list.item_count - 1, item)

func _on_item_list_item_selected(index: int):
    var item = item_list.get_item_metadata(index)
    # Do something with selected item

Health Bar Updates

@onready var health_bar = $HealthBar
var current_health = 100
var max_health = 100

func _ready():
    health_bar.max_value = max_health
    health_bar.value = current_health

func take_damage(amount: int):
    current_health = max(0, current_health - amount)

    # Smooth tween to new value
    var tween = create_tween()
    tween.tween_property(health_bar, "value", current_health, 0.2)

    # Change color based on health percentage
    if current_health < max_health * 0.3:
        health_bar.modulate = Color.RED
    elif current_health < max_health * 0.6:
        health_bar.modulate = Color.YELLOW
    else:
        health_bar.modulate = Color.GREEN

Modal Popups

@onready var popup = $Popup

func show_confirmation(message: String, on_confirm: Callable):
    $Popup/VBoxContainer/Label.text = message
    popup.popup_centered()

    # Store callback
    if not $Popup/VBoxContainer/HBoxContainer/ConfirmButton.pressed.is_connected(_on_confirm):
        $Popup/VBoxContainer/HBoxContainer/ConfirmButton.pressed.connect(_on_confirm)

    confirm_callback = on_confirm

var confirm_callback: Callable

func _on_confirm():
    popup.hide()
    if confirm_callback:
        confirm_callback.call()

UI Performance Optimization

Best Practices:

  1. Use CanvasLayers for depth management instead of z_index when possible
  2. Clip content in ScrollContainers with clip_contents = true
  3. Limit RichTextLabel complexity - BBCode parsing can be slow
  4. Pool UI elements - Reuse nodes instead of creating/destroying
  5. Use TextureAtlas for UI sprites to reduce draw calls
  6. Batch similar elements under same parent
  7. Disable processing when UI is hidden: process_mode = PROCESS_MODE_DISABLED
  8. Use Control.clip_contents to prevent rendering off-screen elements

Memory Management:

# Free unused UI scenes
func close_menu():
    queue_free()  # Instead of just hiding

# Object pooling for frequently created UI
var button_pool = []
const MAX_POOL_SIZE = 20

func get_pooled_button():
    if button_pool.is_empty():
        return Button.new()
    return button_pool.pop_back()

func return_to_pool(button: Button):
    if button_pool.size() < MAX_POOL_SIZE:
        button.get_parent().remove_child(button)
        button_pool.append(button)
    else:
        button.queue_free()

Accessibility Features

Text Scaling:

# Support text size preferences
func apply_text_scale(scale: float):
    for label in get_tree().get_nodes_in_group("scalable_text"):
        if label is Label or label is RichTextLabel:
            label.add_theme_font_size_override("font_size", int(16 * scale))

Gamepad Support:

# Ensure all interactive UI is gamepad-accessible
func _ready():
    # Set up focus chain
    for i in range($ButtonContainer.get_child_count() - 1):
        var current = $ButtonContainer.get_child(i)
        var next = $ButtonContainer.get_child(i + 1)
        current.focus_neighbor_bottom = next.get_path()
        next.focus_neighbor_top = current.get_path()

    # Grab focus on first button
    if $ButtonContainer.get_child_count() > 0:
        $ButtonContainer.get_child(0).grab_focus()

MCP Tool Usage

When creating UI elements, you should:

  1. Use mcp__godot__create_scene to create new UI scene files
  2. Use mcp__godot__add_node to build Control node hierarchies
  3. Use mcp__godot__save_scene to save after creating UI structure
  4. Use Edit/Write tools to create associated GDScript files for UI logic
  5. Use mcp__godot__load_sprite to import UI textures and icons

Example Workflow:

1. create_scene("res://scenes/ui/main_menu.tscn", "CanvasLayer")
2. add_node(..., "MarginContainer")
3. add_node(..., "VBoxContainer")
4. add_node(..., "Button")
5. save_scene(...)
6. Write GDScript controller

When to Activate This Skill

Activate this skill when the user:

  • Asks about creating menus, HUDs, or UI screens
  • Mentions Control nodes, themes, or styling
  • Needs help with inventory, dialogue, or menu systems
  • Asks about responsive UI or screen resolution handling
  • Requests help with button navigation or gamepad support
  • Wants to create settings menus or pause screens
  • Asks about UI animation or transitions
  • Needs help with UI performance optimization
  • Mentions anchors, containers, or layout management

Important Reminders

  • Always consider gamepad/keyboard navigation in addition to mouse
  • Use CanvasLayers to manage rendering order and prevent z-fighting
  • Anchor presets are your friend for responsive design
  • Themes should be created as resources for reusability
  • Signal connections are the primary way to handle UI interactions
  • Tweens make UI feel polished with smooth animations
  • Test on multiple resolutions - use Project Settings > Display > Window settings

Commands 8

View enhanced debug output from the running Godot project with error highlighting and filtering.

Process

  1. Check if project is running

    • Use mcp__godot__get_debug_output to fetch current debug output
  2. Parse and enhance the output:

    • Identify error types (ERROR, WARNING, INFO)
    • Parse stack traces
    • Extract file paths and line numbers
    • Highlight important information
  3. Display formatted output:

Error Formatting

Present errors with the following enhanced format:

ERROR messages

[ERROR] <error_message>
  Location: <file_path>:<line_number>
  Function: <function_name>
  Details: <additional_context>

  Stack Trace:
    at <function> (<file>:<line>)
    at <function> (<file>:<line>)

WARNING messages

[WARNING] <warning_message>
  Location: <file_path>:<line_number>
  Context: <relevant_context>

INFO/DEBUG messages

[INFO] <message>

Common Error Patterns to Recognize

1. Null Reference Errors

Pattern: Attempt to call function .* in base 'null instance'

Response:

[ERROR] Null Reference Error
  Trying to call a method on a null object

  Quick Fixes:
  - Check if the object exists before calling methods
  - Verify @onready node paths are correct
  - Ensure nodes aren't freed before being accessed

  Example fix:
    if my_node != null:
        my_node.some_method()

2. Node Not Found

Pattern: Node not found: .* or get_node: .*not found

Response:

[ERROR] Node Not Found
  Path: <node_path>

  Possible Causes:
  - Node doesn't exist in the scene tree
  - Incorrect node path (check capitalization)
  - Node hasn't been added yet (timing issue)

  Quick Fixes:
  - Use get_node_or_null() to check if node exists
  - Verify the node path in the scene tree
  - Use @onready for scene tree references

3. Index Out of Range

Pattern: Index .* out of range

Response:

[ERROR] Array Index Out of Bounds
  Index: <index_value>
  Array Size: <size>

  Quick Fixes:
  - Check array size before accessing: if index < array.size()
  - Use range-based loops instead of index access
  - Validate index is not negative

4. Type Errors

Pattern: Invalid operands .* and .* in operator

Response:

[ERROR] Type Mismatch
  Cannot perform operation between incompatible types

  Quick Fixes:
  - Ensure variables are initialized
  - Check for null values before operations
  - Verify type annotations match actual types

5. Signal Errors

Pattern: Signal .* already connected or Attempt to call an invalid function

Response:

[ERROR] Signal Connection Error

  Quick Fixes:
  - Check if signal is already connected before connecting
  - Verify method signature matches signal parameters
  - Ensure method exists and is spelled correctly

Enhanced Features

Error Grouping

  • Group repeated errors together
  • Show count of occurrences
  • Display first occurrence time

Example:

[ERROR] (x5) Null instance access
  First occurred at: 14:32:15
  Last occurred at: 14:32:23

  See details with: /gd:debug --expand=<error_id>

Filtering Options

Ask user if they want to filter output:

Question: "Would you like to filter the debug output?" Header: "Filter" Multi-select: false Options:

  • Show All: Display all messages (errors, warnings, info)
  • Errors Only: Show only ERROR messages
  • Errors + Warnings: Show errors and warnings
  • Custom Filter: Filter by keyword

Auto-suggestions

For each error, provide:

  1. Error Type: Classification of the error
  2. Likely Cause: Most common reason for this error
  3. Suggested Fix: Code example or action to take
  4. Related Documentation: Link to relevant Godot docs if applicable

Example output:

─────────────────────────────────────
[ERROR] Invalid get index 'health' (on base: 'null instance')

Location: res://scripts/player.gd:45
Function: take_damage()

Likely Cause:
  The player node is null when trying to access the 'health' property.
  This usually happens when:
  - A node reference (@onready var) points to a non-existent node
  - The node was freed/removed before this code runs
  - The node path is incorrect

Suggested Fix:
  # Add null check before accessing:
  if player != null:
      player.health -= damage

  # Or verify node exists in _ready():
  func _ready():
      assert(player != null, "Player node not found!")

Related Code (player.gd:45):
  45 | func take_damage(amount):
  46 |     player.health -= amount  # ERROR HERE
  47 |     update_health_bar()

Next Steps:
  1. Check that the player node exists in the scene tree
  2. Verify the node path for @onready variables
  3. Add null checks before accessing node properties

─────────────────────────────────────

Watch Mode

Offer to enable watch mode:

"Would you like to enable watch mode? This will continuously monitor for new errors."

If yes:

  • Poll mcp__godot__get_debug_output every 2 seconds
  • Display new errors as they occur
  • Highlight new errors in real-time
  • User can press Ctrl+C or type 'stop' to exit watch mode

Example watch mode output:

[WATCH MODE] Monitoring debug output... (Press Ctrl+C to stop)

14:35:12 | [INFO] Game started
14:35:15 | [WARNING] Texture not found: res://sprites/missing.png
14:35:18 | [ERROR] Null instance access in enemy.gd:23

Press Enter to see error details, or type 'stop' to exit...

Additional Commands

After showing debug output, offer helpful commands:

Debug output retrieved.

Helpful commands:
  /gd:debug --errors-only     Show only errors
  /gd:debug --watch           Enable watch mode
  /gd:restart                 Restart the game

  Need help fixing an error? Just ask! The godot-debugging skill can help interpret and fix these errors.

Integration with godot-debugging Skill

After displaying errors, automatically activate the godot-debugging skill to provide:

  • Detailed error explanations
  • Code fixes
  • Prevention strategies

Example Full Output

Debug Output (Last 50 lines)
═══════════════════════════════════════

[INFO] Project initialized
[INFO] Scene loaded: res://scenes/main.tscn

[WARNING] Node has been removed from scene: Label
  Location: res://scenes/ui/menu.tscn
  Context: Attempting to access removed node

  Note: This usually happens when you call queue_free() on a node
  and then try to access it later in the same frame.

─────────────────────────────────────

[ERROR] Attempt to call function 'move_and_slide' in base 'null instance' on a null instance
  Location: res://scripts/player.gd:67
  Function: _physics_process(delta)

  Stack Trace:
    at CharacterBody2D._physics_process (res://scripts/player.gd:67)
    at Node._propagate_process (core)

  🔍 Analysis:
  The player node (CharacterBody2D) is trying to call move_and_slide()
  but the instance is null. This typically means:
  - The player was freed but physics_process is still running
  - The script is on a freed node

  💡 Suggested Fix:
    func _physics_process(delta):
        if not is_instance_valid(self):
            return

        velocity.y += gravity * delta
        move_and_slide()

─────────────────────────────────────

Summary:
  • Total Messages: 24
  • Errors: 3 (🔴)
  • Warnings: 5 (🟡)
  • Info: 16 (🔵)

Most Recent Error:
  res://scripts/player.gd:67 - Null instance in _physics_process

═══════════════════════════════════════

Would you like me to help fix any of these errors?

Error History Tracking

Keep track of errors across debug sessions:

  • Store error fingerprints (file + line + error type)
  • Track if error is new or recurring
  • Show resolution history if previously fixed

Example:

[ERROR] (Recurring) Null instance access
  This error has occurred 3 times in the last hour
  Previously seen: 14:15, 14:22, 14:35

  Note: This might indicate a deeper issue with your code structure.
  Consider adding more robust null checks or restructuring your node references.

Implementation Notes

  1. Parse debug output intelligently

    • Extract file paths as clickable links (if terminal supports it)
    • Parse stack traces into structured format
    • Identify error patterns automatically
  2. Color coding (if terminal supports it)

    • Red for errors
    • Yellow for warnings
    • Blue for info
    • Gray for debug
  3. Smart filtering

    • Remember user's last filter choice
    • Allow regex patterns for advanced filtering
    • Group similar errors together
  4. Quick actions

    • Offer to open file at error line
    • Suggest running godot-debugging skill
    • Provide quick fix options

After displaying the enhanced debug output, remind the user: "💡 Tip: I can help fix these errors! Just ask about any specific error and I'll provide a detailed explanation and fix using the godot-debugging skill."

You are helping initialize a new Godot game project.

First, launch the game-planner agent to gather requirements and create a game plan:

Use the Task tool with subagent_type "game-planner" to launch the planning agent.

After the planning agent completes, use the returned game plan to:

  1. Update or create the project.godot file with appropriate settings (2D/3D, display settings, etc.)
  2. Create the main scene based on the game type (Node2D for 2D games, Node3D for 3D games)
  3. Set up the basic folder structure:
    • scenes/ (for game scenes)
    • scripts/ (for GDScript files)
    • assets/ (for images, sounds, etc.)
    • resources/ (for Godot resource files)
  4. Create a README.md documenting the project plan, core mechanics, and initial architecture

Use the Godot MCP tools to create scenes and add nodes as appropriate based on the game plan.

Inform the user when initialization is complete and suggest next steps for development.

Quickly restart the running Godot project for fast iteration during development.

Process

  1. Stop the current instance

    • Use mcp__godot__stop_project to stop the running game
    • Display: ♻️ Restarting game...
  2. Wait briefly (0.5 seconds) for clean shutdown

  3. Start the project again

    • Use mcp__godot__run_project with projectPath set to current working directory
  4. Get initial output

    • Wait 1.5 seconds
    • Use mcp__godot__get_debug_output to check for errors
  5. Display result

If restart successful:

✓ Game restarted successfully!

  Quick stats:
  • Restart time: <elapsed_time>
  • Status: Running

  Commands:
    /gd:restart     Restart again
    /gd:debug       View debug output
    /gd:stop        Stop the game

  💡 Tip: Keep this workflow for rapid iteration:
     Edit code → Save → /gd:restart → Test

If errors occurred:

⚠ Game restarted with errors:

<formatted_errors>

  Use /gd:debug for detailed error information

  Commands:
    /gd:debug       View full debug output
    /gd:stop        Stop the game

  Would you like help fixing these errors?

If no game was running:

ℹ No game was running. Starting fresh...

<use same output as /gd:run>

Usage Tips

Display these tips the first time user runs /gd:restart:

💡 Restart Command Tips:

   1. Fast Iteration: Use /gd:restart after making code changes
      instead of manually stopping and starting the game.

   2. Keyboard Shortcut: Save this command for quick access
      (check if your terminal supports command aliases)

   3. Watch Your Console: Errors from the restart will be
      displayed immediately.

   4. No Need to Stop First: /gd:restart handles stopping
      automatically.

   Typical workflow:
   1. Make changes to your code
   2. Save (Cmd+S / Ctrl+S)
   3. Run /gd:restart
   4. Test your changes
   5. Repeat!

Performance Optimization

Track restart metrics for user feedback:

📊 Restart Performance:
   • This restart: 2.1s
   • Average: 2.3s
   • Fastest: 1.8s

   Your game restarts quickly! This is great for iteration.

Error Recovery

If restart fails:

❌ Restart failed!

   Possible causes:
   - Previous instance didn't shut down cleanly
   - Godot editor is not responding
   - MCP server connection issue

   Try these steps:
   1. Wait a few seconds and try again
   2. Check if Godot editor is running
   3. Run /gd:setup to verify MCP configuration

   Or manually:
   1. /gd:stop (ensure game stops)
   2. /gd:run (start fresh)

Integration with Error Monitoring

After restart, if errors detected, activate godot-debugging skill hints:

🔍 Detected issues in restart:

   [ERROR] Null instance in player.gd:45

   Common cause: Node references changed or removed

   Quick fix: Verify all @onready var paths are correct
              after scene modifications.

   Want detailed help? Just ask about this error!

Run the current Godot project using the MCP server with enhanced debugging features.

Process

1. Parse Command Arguments

Check if user provided any flags:

  • --watch or -w: Enable watch mode (auto-restart on file changes)
  • --debug or -d: Show detailed debug output immediately
  • --no-output: Run without showing initial output

Examples:

  • /gd:run - Normal run
  • /gd:run --watch - Run with watch mode
  • /gd:run --debug - Run with immediate debug output

2. Start the Project

Use mcp__godot__run_project with projectPath set to the current working directory.

Display:

🎮 Starting Godot project...
   Project: <current_directory>

3. Get Initial Output

Wait 2 seconds, then use mcp__godot__get_debug_output to fetch initial output.

4. Parse and Display Output

Parse the output for:

  • Errors (lines containing "ERROR", "Error:", or stack traces)
  • Warnings (lines containing "WARNING", "WARN")
  • Info (other output)

Display with enhanced formatting:

If No Errors:

✓ Game started successfully!

Output:
<formatted_output>

Commands:
  /gd:stop      Stop the running game
  /gd:debug     View enhanced debug output
  /gd:restart   Quick restart

Tip: The game is now running. Make changes to your code and use /gd:restart to quickly reload!

If Errors Found:

⚠ Game started with errors:

<formatted_errors>

Commands:
  /gd:debug     View detailed error information
  /gd:stop      Stop the game

Would you like me to help fix these errors? I can explain what's wrong and suggest solutions.

5. Error Highlighting

When displaying errors, highlight key information:

[ERROR] <error_type>
  File: <file_path>:<line_number>
  Message: <error_message>

  💡 Quick Tip: <brief_suggestion>

Examples:

[ERROR] Null Instance
  File: res://scripts/player.gd:45
  Message: Attempt to call function 'take_damage' in base 'null instance' on a null instance

  💡 Quick Tip: Add null check before calling methods: if node != null: node.method()
[WARNING] Resource Not Found
  File: res://scenes/level.tscn
  Message: Cannot load resource at path: 'res://sprites/missing.png'

  💡 Quick Tip: Check that the file exists and the path is correct (case-sensitive)

6. Watch Mode (if --watch flag provided)

If watch mode is enabled:

  1. Display:
📁 Watch mode enabled
   Monitoring for file changes in:
   - *.gd (GDScript files)
   - *.tscn (Scene files)
   - *.tres (Resource files)

   The game will auto-restart when you save changes.
   Press Ctrl+C or type 'stop' to exit watch mode.
  1. Set up file watching (conceptual - explain to user):
Note: Watch mode requires manual restart for now.

To enable auto-restart:
1. Make your code changes
2. Use /gd:restart to quickly reload
3. Repeat as needed

Future enhancement: Automatic file watching with instant reload.
  1. Provide workflow tips:
💡 Rapid Iteration Workflow:
   1. Edit your code
   2. Save the file (Ctrl+S / Cmd+S)
   3. Run /gd:restart
   4. See changes immediately!

   This is much faster than closing and reopening the game.

7. Error Count Summary

After initial run, provide summary:

═══════════════════════════════════════
  Status Summary
═══════════════════════════════════════
  🔴 Errors: <count>
  🟡 Warnings: <count>
  🔵 Info messages: <count>

  ⏱ Startup time: <elapsed_time>
═══════════════════════════════════════

8. Offer Help

Based on what was found:

If errors present:

I noticed some errors. Would you like me to:
  1. Explain what these errors mean
  2. Show you how to fix them
  3. Run the debugger for more details

Just ask! For example: "Help me fix the null instance error"

If warnings only:

There are some warnings you might want to address.
Use /gd:debug to see detailed information.

If clean run:

Everything looks good! Your game is running smoothly.

9. Continuous Monitoring (Enhanced)

Offer to monitor for new errors:

Ask user: Question: "Would you like me to monitor for runtime errors?" Header: "Monitoring" Multi-select: false Options:

  • Yes, watch for errors: I'll alert you if new errors occur
  • No, just run: Just start the game without monitoring
  • Debug mode: Show all output in real-time

If "Yes, watch for errors" selected:

👀 Monitoring enabled
   I'll alert you if new errors occur while the game is running.

   You can check anytime with /gd:debug

Then periodically (conceptually - every 30 seconds or when user asks):

  • Check for new errors with get_debug_output
  • If new errors found, alert user:
    ⚠ New error detected!
    
    [ERROR] <brief_description>
    
    Use /gd:debug to see full details
    

10. Integration with Debugging Skill

If errors are found, automatically suggest using the debugging skill:

💬 Need help understanding these errors?

   Try asking:
   - "What does this error mean?"
   - "How do I fix the null instance error?"
   - "Debug the player.gd script"

   I can explain and fix these issues for you!

11. Performance Notes

Display performance indicators if available:

⚡ Performance:
   FPS: <if_available>
   Memory: <if_available>

   Use /gd:profile for detailed performance analysis

12. Quick Actions

At the end, always show quick actions:

Quick Commands:
  /gd:stop          Stop the game
  /gd:restart       Restart quickly
  /gd:debug         Detailed debug view
  /gd:profile       Performance analysis

  💡 Press Tab to see all /gd: commands

Example Full Output

Success Case:

🎮 Starting Godot project...
   Project: /Users/user/games/platformer

✓ Game started successfully!

Output:
  Godot Engine v4.2.1 - https://godotengine.org
  Vulkan API 1.3.0 - Device: Apple M1

  Loading scene: res://scenes/main.tscn
  Player initialized
  Level loaded: Level_1

═══════════════════════════════════════
  Status Summary
═══════════════════════════════════════
  🔴 Errors: 0
  🟡 Warnings: 0
  🔵 Info messages: 4

  ⏱ Startup time: 1.2s
═══════════════════════════════════════

Everything looks good! Your game is running smoothly.

Commands:
  /gd:stop      Stop the running game
  /gd:debug     View debug output
  /gd:restart   Quick restart

Tip: Make changes to your code and use /gd:restart to quickly reload!

Error Case:

🎮 Starting Godot project...
   Project: /Users/user/games/platformer

⚠ Game started with errors:

[ERROR] Null Instance
  File: res://scripts/player.gd:45
  Message: Attempt to call function 'take_damage' in base 'null instance'

  💡 Quick Tip: Add null check: if player != null: player.take_damage(10)

[WARNING] Resource Not Found
  File: res://scenes/level.tscn
  Message: Cannot load resource: 'res://sprites/enemy.png'

  💡 Quick Tip: Verify the file path is correct and the file exists

═══════════════════════════════════════
  Status Summary
═══════════════════════════════════════
  🔴 Errors: 1
  🟡 Warnings: 1
  🔵 Info messages: 3

  ⏱ Startup time: 1.5s
═══════════════════════════════════════

💬 Need help fixing these errors?

   I can explain what went wrong and show you how to fix it.
   Just ask: "Help me fix the null instance error"

Commands:
  /gd:debug     View detailed error information
  /gd:stop      Stop the game

Important Notes

  • Always format output in a user-friendly way
  • Highlight errors in a visually distinct manner
  • Provide actionable suggestions, not just error messages
  • Make it easy to transition to fixing errors (mention debugging skill)
  • Track context for follow-up questions about specific errors

Create common scene templates for 2D games, including characters, enemies, levels, and more.

Process

  1. Ask the user what type of scene they want to create:

Use AskUserQuestion with the following options:

Question: "What type of scene would you like to create?" Header: "Scene Type" Multi-select: false Options:

  • 2D Player Character: Platformer character with movement and collision
  • 2D Enemy: Basic enemy with AI placeholder
  • 2D Level: Level scene with tilemap and camera
  • 2D Projectile: Bullet/projectile with movement
  • Collectible: Coin/item pickup
  • Interactable Object: Chest, door, switch, etc.

Question 2: "Where should the scene be created?" Header: "Location" Multi-select: false Options:

  • scenes/characters/: For player and NPCs
  • scenes/enemies/: For enemy characters
  • scenes/levels/: For level scenes
  • scenes/objects/: For items and interactables
  • Custom path: I'll specify the path
  1. If Custom path selected, ask for the specific path and scene name

  2. Create the appropriate template based on selection

2D Player Character Template

Create scene with:

CharacterBody2D (root)
├── Sprite2D (sprite)
├── CollisionShape2D (collision)
├── AnimationPlayer (animation_player)
└── Camera2D (camera)

Node details:

  • CharacterBody2D: motion_mode = MOTION_MODE_GROUNDED
  • Sprite2D: centered = true, texture = placeholder (32x32 white rect)
  • CollisionShape2D: shape = RectangleShape2D (16x32)
  • Camera2D: enabled = true, position_smoothing_enabled = true

Create accompanying script:

extends CharacterBody2D

# Movement parameters
@export var speed: float = 200.0
@export var jump_velocity: float = -400.0
@export var acceleration: float = 800.0
@export var friction: float = 1000.0

# Get the gravity from the project settings
var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")

@onready var sprite = $Sprite2D
@onready var animation_player = $AnimationPlayer

func _physics_process(delta):
	# Add gravity
	if not is_on_floor():
		velocity.y += gravity * delta

	# Handle jump
	if Input.is_action_just_pressed("ui_accept") and is_on_floor():
		velocity.y = jump_velocity

	# Get input direction
	var direction = Input.get_axis("ui_left", "ui_right")

	# Apply movement
	if direction != 0:
		velocity.x = move_toward(velocity.x, direction * speed, acceleration * delta)

		# Flip sprite based on direction
		sprite.flip_h = direction < 0

	else:
		# Apply friction when no input
		velocity.x = move_toward(velocity.x, 0, friction * delta)

	move_and_slide()

	# Animation logic (requires animations to be set up)
	_update_animation()

func _update_animation():
	if not animation_player:
		return

	# TODO: Create animations in AnimationPlayer:
	# - "idle": Standing still
	# - "run": Running
	# - "jump": Jumping up
	# - "fall": Falling down

	# Example animation logic:
	# if not is_on_floor():
	#     if velocity.y < 0:
	#         animation_player.play("jump")
	#     else:
	#         animation_player.play("fall")
	# elif abs(velocity.x) > 10:
	#     animation_player.play("run")
	# else:
	#     animation_player.play("idle")
	pass

2D Enemy Template

Create scene with:

CharacterBody2D (root)
├── Sprite2D (sprite)
├── CollisionShape2D (collision)
├── Area2D (detection_area)
│   └── CollisionShape2D (detection_collision)
├── AnimationPlayer (animation_player)
└── Timer (patrol_timer)

Node details:

  • CharacterBody2D: motion_mode = MOTION_MODE_GROUNDED
  • Sprite2D: centered = true, modulate = Color(1, 0.5, 0.5) (reddish tint)
  • CollisionShape2D: shape = RectangleShape2D (16x24)
  • Area2D/CollisionShape2D: shape = CircleShape2D (radius = 100) for player detection
  • Timer: wait_time = 2.0, one_shot = false

Create accompanying script:

extends CharacterBody2D

enum State { IDLE, PATROL, CHASE, ATTACK }

# Movement parameters
@export var patrol_speed: float = 50.0
@export var chase_speed: float = 150.0
@export var detection_range: float = 100.0
@export var attack_range: float = 30.0
@export var health: int = 100

var current_state: State = State.IDLE
var player: Node2D = null
var patrol_direction: int = 1
var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")

@onready var sprite = $Sprite2D
@onready var detection_area = $detection_area
@onready var patrol_timer = $patrol_timer

func _ready():
	# Connect area signals for player detection
	detection_area.body_entered.connect(_on_detection_area_entered)
	detection_area.body_exited.connect(_on_detection_area_exited)

	# Connect patrol timer
	patrol_timer.timeout.connect(_on_patrol_timer_timeout)
	patrol_timer.start()

	current_state = State.PATROL

func _physics_process(delta):
	# Apply gravity
	if not is_on_floor():
		velocity.y += gravity * delta

	# State machine
	match current_state:
		State.IDLE:
			velocity.x = 0

		State.PATROL:
			velocity.x = patrol_direction * patrol_speed
			sprite.flip_h = patrol_direction < 0

			# Turn around at ledges or walls
			if is_on_wall() or not _check_floor_ahead():
				patrol_direction *= -1

		State.CHASE:
			if player:
				var direction = sign(player.global_position.x - global_position.x)
				velocity.x = direction * chase_speed
				sprite.flip_h = direction < 0

				# Check if close enough to attack
				var distance = global_position.distance_to(player.global_position)
				if distance < attack_range:
					current_state = State.ATTACK
			else:
				current_state = State.PATROL

		State.ATTACK:
			velocity.x = 0
			# TODO: Implement attack logic
			# For now, just return to chase after a moment
			await get_tree().create_timer(0.5).timeout
			current_state = State.CHASE

	move_and_slide()

func _check_floor_ahead() -> bool:
	# Raycast to check if there's floor ahead
	var space_state = get_world_2d().direct_space_state
	var query = PhysicsRayQueryParameters2D.create(
		global_position,
		global_position + Vector2(patrol_direction * 20, 30)
	)
	var result = space_state.intersect_ray(query)
	return result.size() > 0

func _on_detection_area_entered(body):
	if body.is_in_group("player"):
		player = body
		current_state = State.CHASE

func _on_detection_area_exited(body):
	if body == player:
		player = null
		current_state = State.PATROL

func _on_patrol_timer_timeout():
	if current_state == State.IDLE or current_state == State.PATROL:
		patrol_direction *= -1

func take_damage(amount: int):
	health -= amount
	# TODO: Add damage flash/animation

	if health <= 0:
		die()

func die():
	# TODO: Add death animation
	queue_free()

2D Level Template

Create scene with:

Node2D (root)
├── TileMap (tilemap)
├── Node2D (spawn_points)
│   └── Marker2D (player_spawn)
├── Node2D (enemies)
├── Node2D (collectibles)
├── ParallaxBackground (background)
│   └── ParallaxLayer (layer1)
│       └── Sprite2D (bg_sprite)
└── Camera2D (camera)

Node details:

  • TileMap: tile_set = null (needs to be set by user), layer 0 = "Ground", layer 1 = "Walls"
  • Camera2D: enabled = true, limit_left = 0, limit_top = 0

Create accompanying script:

extends Node2D

@onready var tilemap = $TileMap
@onready var player_spawn = $spawn_points/player_spawn
@onready var camera = $Camera2D

# Preload player scene
const PLAYER_SCENE = preload("res://scenes/characters/player.tscn")

func _ready():
	# Spawn player
	spawn_player()

	# Set camera limits based on level bounds
	_setup_camera_limits()

func spawn_player():
	# Instance and add player
	var player = PLAYER_SCENE.instantiate()
	player.global_position = player_spawn.global_position
	add_child(player)

	# Make camera follow player
	camera.enabled = false  # Disable level camera
	# Player should have its own camera

func _setup_camera_limits():
	# Get tilemap bounds
	var used_rect = tilemap.get_used_rect()
	var tile_size = tilemap.tile_set.tile_size if tilemap.tile_set else Vector2(16, 16)

	# Set camera limits to level bounds
	camera.limit_left = used_rect.position.x * tile_size.x
	camera.limit_top = used_rect.position.y * tile_size.y
	camera.limit_right = used_rect.end.x * tile_size.x
	camera.limit_bottom = used_rect.end.y * tile_size.y

# Helper function to spawn enemies at runtime
func spawn_enemy(enemy_scene: PackedScene, position: Vector2):
	var enemy = enemy_scene.instantiate()
	enemy.global_position = position
	$enemies.add_child(enemy)

# Helper function to spawn collectibles
func spawn_collectible(collectible_scene: PackedScene, position: Vector2):
	var collectible = collectible_scene.instantiate()
	collectible.global_position = position
	$collectibles.add_child(collectible)

2D Projectile Template

Create scene with:

Area2D (root)
├── Sprite2D (sprite)
├── CollisionShape2D (collision)
└── Timer (lifetime_timer)

Node details:

  • Sprite2D: centered = true, modulate = Color(1, 1, 0) (yellow)
  • CollisionShape2D: shape = CircleShape2D (radius = 4)
  • Timer: wait_time = 5.0, one_shot = true, autostart = true

Create accompanying script:

extends Area2D

@export var speed: float = 300.0
@export var damage: int = 10
@export var lifetime: float = 5.0

var direction: Vector2 = Vector2.RIGHT

@onready var sprite = $Sprite2D
@onready var lifetime_timer = $lifetime_timer

func _ready():
	# Connect signals
	body_entered.connect(_on_body_entered)
	area_entered.connect(_on_area_entered)
	lifetime_timer.timeout.connect(_on_lifetime_timeout)

	# Set lifetime
	lifetime_timer.wait_time = lifetime

func _physics_process(delta):
	# Move in direction
	position += direction.normalized() * speed * delta

func set_direction(new_direction: Vector2):
	direction = new_direction.normalized()

	# Rotate sprite to face direction
	rotation = direction.angle()

func _on_body_entered(body):
	# Hit something solid
	if body.has_method("take_damage"):
		body.take_damage(damage)

	# Create hit effect
	_create_hit_effect()

	queue_free()

func _on_area_entered(area):
	# Hit another area (enemy hitbox, etc.)
	if area.get_parent().has_method("take_damage"):
		area.get_parent().take_damage(damage)

	# Create hit effect
	_create_hit_effect()

	queue_free()

func _on_lifetime_timeout():
	# Despawn after lifetime expires
	queue_free()

func _create_hit_effect():
	# TODO: Spawn particle effect or animation
	pass

Collectible Template

Create scene with:

Area2D (root)
├── Sprite2D (sprite)
├── CollisionShape2D (collision)
├── AnimationPlayer (animation_player)
└── AudioStreamPlayer2D (pickup_sound)

Node details:

  • Sprite2D: centered = true, modulate = Color(1, 0.8, 0) (gold color)
  • CollisionShape2D: shape = CircleShape2D (radius = 8)

Create accompanying script:

extends Area2D

@export var collect_value: int = 1
@export var float_amplitude: float = 5.0
@export var float_speed: float = 2.0

var start_y: float
var time: float = 0.0

@onready var sprite = $Sprite2D
@onready var animation_player = $AnimationPlayer
@onready var pickup_sound = $pickup_sound

func _ready():
	# Connect collection signal
	body_entered.connect(_on_body_entered)

	# Store starting position for floating animation
	start_y = position.y

	# Random offset for variety
	time = randf() * TAU

func _process(delta):
	# Floating animation
	time += delta * float_speed
	position.y = start_y + sin(time) * float_amplitude

	# Rotate for visual interest
	sprite.rotation += delta * 2.0

func _on_body_entered(body):
	if body.is_in_group("player"):
		# Notify player of collection
		if body.has_method("collect_item"):
			body.collect_item(collect_value)

		# Play pickup sound
		if pickup_sound and pickup_sound.stream:
			# Play sound then destroy
			pickup_sound.play()

			# Hide visuals but keep node alive for sound
			sprite.visible = false
			$CollisionShape2D.set_deferred("disabled", true)

			await pickup_sound.finished

		queue_free()

Interactable Object Template

Create scene with:

StaticBody2D (root)
├── Sprite2D (sprite)
├── CollisionShape2D (collision)
├── Area2D (interaction_area)
│   └── CollisionShape2D (interaction_collision)
└── Label (prompt_label)

Node details:

  • Sprite2D: centered = true
  • CollisionShape2D: shape = RectangleShape2D (32x32)
  • Area2D/CollisionShape2D: shape = RectangleShape2D (48x48) for interaction detection
  • Label: text = "Press E", horizontal_alignment = CENTER, visible = false

Create accompanying script:

extends StaticBody2D

signal interacted

@export var interaction_text: String = "Press E"
@export var can_interact_multiple_times: bool = false

var player_nearby: bool = false
var has_been_used: bool = false

@onready var sprite = $Sprite2D
@onready var interaction_area = $interaction_area
@onready var prompt_label = $prompt_label

func _ready():
	# Connect area signals
	interaction_area.body_entered.connect(_on_interaction_area_entered)
	interaction_area.body_exited.connect(_on_interaction_area_exited)

	# Set prompt text
	prompt_label.text = interaction_text

	# Position prompt above object
	prompt_label.position.y = -40

func _process(_delta):
	if player_nearby and Input.is_action_just_pressed("ui_accept"):
		if not has_been_used or can_interact_multiple_times:
			_interact()

func _on_interaction_area_entered(body):
	if body.is_in_group("player"):
		player_nearby = true

		# Show prompt if not used or can use multiple times
		if not has_been_used or can_interact_multiple_times:
			prompt_label.visible = true

func _on_interaction_area_exited(body):
	if body.is_in_group("player"):
		player_nearby = false
		prompt_label.visible = false

func _interact():
	# Mark as used
	has_been_used = true

	# Hide prompt if can't be used again
	if not can_interact_multiple_times:
		prompt_label.visible = false

	# Emit signal for other systems to respond
	interacted.emit()

	# TODO: Implement specific interaction logic
	# Examples:
	# - Open a door
	# - Play an animation
	# - Give an item
	# - Show dialogue
	# - Toggle a mechanism

	print("Interacted with ", name)

After Creating Scene

After creating the selected scene:

  1. Inform the user of the files created:

    • Scene file location
    • Script file location
  2. Provide customization tips:

    • "The [scene name] has been created at [path]"
    • "To customize this scene:"
      • Replace the placeholder sprite with your own artwork
      • Adjust the exported variables in the Inspector
      • Add animations in the AnimationPlayer
      • [Template-specific tips]
  3. Provide usage instructions:

    • For characters: "Add this to your level by dragging into the scene or instantiating in code"
    • For levels: "Set this as your main scene in Project Settings or change to it with get_tree().change_scene_to_file()"
    • For projectiles: "Instance this in your player/enemy script when firing"
    • For collectibles/interactables: "Place these in your level scene as children"
  4. Offer next steps:

    • "Would you like me to:"
      • Create related scenes (e.g., "create a projectile for this character?")
      • Add more features (e.g., "add a dash ability?", "add more enemy states?")
      • Set up animations (if AnimationPlayer exists)
      • Create a test level to try it out

You are helping set up the Godot development environment for this project.

Run the setup script to validate the environment and configure the MCP server:

!bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-mcp.sh

The script will:

  1. Check if Godot is installed at common locations
  2. Verify the Godot MCP server is built and ready at ~/projects/godot-mcp
  3. Create .mcp.json from the template with detected paths
  4. Report any issues and provide guidance

After running the script:

  • If successful, inform the user that the environment is ready and they can now use /gd:init-game to start planning their game
  • If there are issues, explain what needs to be fixed and how to resolve them
  • Remind the user to restart Claude Code for the MCP server changes to take effect

Stop the currently running Godot project.

  1. Use mcp__godot__stop_project to stop the game
  2. Display any final output or errors
  3. Confirm to the user that the game has been stopped

Create a quick UI template for common game UI screens.

Process

  1. Ask the user what type of UI they want to create:

Use AskUserQuestion with the following options:

Question: "What type of UI screen would you like to create?" Header: "UI Type" Multi-select: false Options:

  • Main Menu: Title screen with New Game, Continue, Settings, Quit
  • Pause Menu: In-game pause screen with Resume, Settings, Main Menu, Quit
  • Settings Menu: Graphics, audio, and gameplay settings with tabs
  • Game HUD: Health bar, score, and interactive buttons
  • Inventory: Grid-based item management system
  • Dialogue Box: Character dialogue with portrait and choices
  • Confirmation Dialog: Yes/No popup dialog

Question 2: "Where should the UI scene be created?" Header: "Location" Multi-select: false Options:

  • scenes/ui/menus/: For menu screens
  • scenes/ui/hud/: For in-game HUD elements
  • scenes/ui/dialogs/: For popup dialogs
  • Custom path: I'll specify the path
  1. If Custom path selected, ask for the specific path

  2. Create the appropriate template based on selection

Main Menu Template

Create scene with:

CanvasLayer (root)
├── ColorRect (background - full rect anchors)
├── MarginContainer (full rect, margins: 40px all sides)
│   └── VBoxContainer (alignment: center)
│       ├── Control (spacer - custom_minimum_size.y = 100)
│       ├── Label (title - custom font size 48, center aligned)
│       ├── Control (spacer - custom_minimum_size.y = 50)
│       ├── VBoxContainer (button_container - separation: 10)
│       │   ├── Button (new_game_btn - text: "New Game", custom_minimum_size.x = 200)
│       │   ├── Button (continue_btn - text: "Continue", custom_minimum_size.x = 200)
│       │   ├── Button (settings_btn - text: "Settings", custom_minimum_size.x = 200)
│       │   └── Button (quit_btn - text: "Quit", custom_minimum_size.x = 200)
│       └── Control (spacer with size_flags_vertical = 3)

Create accompanying script:

extends CanvasLayer

@onready var new_game_btn = $MarginContainer/VBoxContainer/VBoxContainer/new_game_btn
@onready var continue_btn = $MarginContainer/VBoxContainer/VBoxContainer/continue_btn
@onready var settings_btn = $MarginContainer/VBoxContainer/VBoxContainer/settings_btn
@onready var quit_btn = $MarginContainer/VBoxContainer/VBoxContainer/quit_btn

func _ready():
	# Connect button signals
	new_game_btn.pressed.connect(_on_new_game_pressed)
	continue_btn.pressed.connect(_on_continue_pressed)
	settings_btn.pressed.connect(_on_settings_pressed)
	quit_btn.pressed.connect(_on_quit_pressed)

	# Set focus for gamepad support
	new_game_btn.grab_focus()

	# Check if save exists for continue button
	continue_btn.disabled = not _has_save_file()

	# Fade in animation
	modulate.a = 0
	var tween = create_tween()
	tween.tween_property(self, "modulate:a", 1.0, 0.5)

func _has_save_file() -> bool:
	# TODO: Implement save file checking
	return FileAccess.file_exists("user://savegame.save")

func _on_new_game_pressed():
	# TODO: Implement new game logic
	get_tree().change_scene_to_file("res://scenes/main_game.tscn")

func _on_continue_pressed():
	# TODO: Implement load game logic
	pass

func _on_settings_pressed():
	# TODO: Open settings menu
	get_tree().change_scene_to_file("res://scenes/ui/menus/settings_menu.tscn")

func _on_quit_pressed():
	get_tree().quit()

Pause Menu Template

Create scene with:

CanvasLayer (root - layer: 100)
├── ColorRect (overlay - full rect, color: #00000080, mouse_filter: STOP)
├── CenterContainer (full rect anchors)
│   └── PanelContainer (custom_minimum_size: 400x500)
│       └── MarginContainer (margins: 20px all sides)
│           └── VBoxContainer (separation: 15)
│               ├── Label (title - text: "PAUSED", align: center, font size: 36)
│               ├── Control (spacer - custom_minimum_size.y = 20)
│               ├── Button (resume_btn - text: "Resume")
│               ├── Button (settings_btn - text: "Settings")
│               ├── Button (main_menu_btn - text: "Main Menu")
│               └── Button (quit_btn - text: "Quit")

Create accompanying script:

extends CanvasLayer

@onready var resume_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/resume_btn
@onready var settings_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/settings_btn
@onready var main_menu_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/main_menu_btn
@onready var quit_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/quit_btn

func _ready():
	# Connect signals
	resume_btn.pressed.connect(_on_resume_pressed)
	settings_btn.pressed.connect(_on_settings_pressed)
	main_menu_btn.pressed.connect(_on_main_menu_pressed)
	quit_btn.pressed.connect(_on_quit_pressed)

	# Pause the game
	get_tree().paused = true

	# Set focus
	resume_btn.grab_focus()

	# Pop-up animation
	$CenterContainer.scale = Vector2(0.8, 0.8)
	$CenterContainer.modulate.a = 0
	var tween = create_tween()
	tween.tween_property($CenterContainer, "scale", Vector2.ONE, 0.3).set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
	tween.parallel().tween_property($CenterContainer, "modulate:a", 1.0, 0.3)

func _on_resume_pressed():
	_close_menu()

func _on_settings_pressed():
	# TODO: Open settings submenu
	pass

func _on_main_menu_pressed():
	get_tree().paused = false
	get_tree().change_scene_to_file("res://scenes/ui/menus/main_menu.tscn")

func _on_quit_pressed():
	get_tree().quit()

func _close_menu():
	get_tree().paused = false
	queue_free()

func _input(event):
	if event.is_action_pressed("ui_cancel"):
		_close_menu()

Settings Menu Template

Create scene with:

CanvasLayer (root)
├── ColorRect (background - full rect)
├── MarginContainer (full rect, margins: 40px all sides)
│   └── VBoxContainer (separation: 20)
│       ├── Label (title - text: "Settings", font size: 36)
│       ├── TabContainer (size_flags_vertical: 3)
│       │   ├── VBoxContainer (name: "Graphics", separation: 10)
│       │   │   ├── HBoxContainer
│       │   │   │   ├── Label (text: "Resolution:")
│       │   │   │   ├── Control (size_flags_horizontal: 3)
│       │   │   │   └── OptionButton (resolution_option)
│       │   │   ├── HBoxContainer
│       │   │   │   ├── Label (text: "Fullscreen:")
│       │   │   │   ├── Control (size_flags_horizontal: 3)
│       │   │   │   └── CheckBox (fullscreen_check)
│       │   │   └── HBoxContainer
│       │   │       ├── Label (text: "VSync:")
│       │   │       ├── Control (size_flags_horizontal: 3)
│       │   │       └── CheckBox (vsync_check)
│       │   └── VBoxContainer (name: "Audio", separation: 10)
│       │       ├── HBoxContainer
│       │       │   ├── Label (text: "Master Volume:")
│       │       │   └── HSlider (master_slider - min: 0, max: 100, value: 100)
│       │       ├── HBoxContainer
│       │       │   ├── Label (text: "Music Volume:")
│       │       │   └── HSlider (music_slider - min: 0, max: 100, value: 100)
│       │       └── HBoxContainer
│       │           ├── Label (text: "SFX Volume:")
│       │           └── HSlider (sfx_slider - min: 0, max: 100, value: 100)
│       └── HBoxContainer (separation: 10)
│           ├── Control (size_flags_horizontal: 3)
│           ├── Button (apply_btn - text: "Apply")
│           └── Button (back_btn - text: "Back")

Create accompanying script:

extends CanvasLayer

# Graphics tab
@onready var resolution_option = $MarginContainer/VBoxContainer/TabContainer/Graphics/HBoxContainer/resolution_option
@onready var fullscreen_check = $MarginContainer/VBoxContainer/TabContainer/Graphics/HBoxContainer2/fullscreen_check
@onready var vsync_check = $MarginContainer/VBoxContainer/TabContainer/Graphics/HBoxContainer3/vsync_check

# Audio tab
@onready var master_slider = $MarginContainer/VBoxContainer/TabContainer/Audio/HBoxContainer/master_slider
@onready var music_slider = $MarginContainer/VBoxContainer/TabContainer/Audio/HBoxContainer2/music_slider
@onready var sfx_slider = $MarginContainer/VBoxContainer/TabContainer/Audio/HBoxContainer3/sfx_slider

# Buttons
@onready var apply_btn = $MarginContainer/VBoxContainer/HBoxContainer/apply_btn
@onready var back_btn = $MarginContainer/VBoxContainer/HBoxContainer/back_btn

func _ready():
	# Populate resolution options
	resolution_option.add_item("1920x1080")
	resolution_option.add_item("1280x720")
	resolution_option.add_item("1024x768")

	# Load current settings
	_load_settings()

	# Connect signals
	apply_btn.pressed.connect(_on_apply_pressed)
	back_btn.pressed.connect(_on_back_pressed)

	master_slider.value_changed.connect(_on_master_volume_changed)
	music_slider.value_changed.connect(_on_music_volume_changed)
	sfx_slider.value_changed.connect(_on_sfx_volume_changed)

func _load_settings():
	# TODO: Load from config file
	fullscreen_check.button_pressed = (DisplayServer.window_get_mode() == DisplayServer.WINDOW_MODE_FULLSCREEN)
	vsync_check.button_pressed = (DisplayServer.window_get_vsync_mode() != DisplayServer.VSYNC_DISABLED)

func _on_apply_pressed():
	_save_settings()

func _save_settings():
	# Graphics settings
	if fullscreen_check.button_pressed:
		DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_FULLSCREEN)
	else:
		DisplayServer.window_set_mode(DisplayServer.WINDOW_MODE_WINDOWED)

	if vsync_check.button_pressed:
		DisplayServer.window_set_vsync_mode(DisplayServer.VSYNC_ENABLED)
	else:
		DisplayServer.window_set_vsync_mode(DisplayServer.VSYNC_DISABLED)

	# TODO: Save to config file
	# TODO: Apply resolution

func _on_back_pressed():
	get_tree().change_scene_to_file("res://scenes/ui/menus/main_menu.tscn")

func _on_master_volume_changed(value: float):
	# TODO: Apply to audio bus
	AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db(value / 100.0))

func _on_music_volume_changed(value: float):
	# TODO: Apply to audio bus
	pass

func _on_sfx_volume_changed(value: float):
	# TODO: Apply to audio bus
	pass

Game HUD Template

Create scene with:

CanvasLayer (root - layer: 10)
├── MarginContainer (full rect, margins: 20px all sides)
│   └── VBoxContainer
│       ├── HBoxContainer (top_bar - separation: 10)
│       │   ├── TextureRect (health_icon - expand_mode: keep_size, custom_minimum_size: 32x32)
│       │   ├── ProgressBar (health_bar - custom_minimum_size: 200x24)
│       │   ├── Control (spacer - size_flags_horizontal: 3)
│       │   ├── Label (score_label - text: "Score: 0")
│       │   └── TextureRect (coin_icon - expand_mode: keep_size, custom_minimum_size: 24x24)
│       ├── Control (middle_spacer - size_flags_vertical: 3)
│       └── HBoxContainer (bottom_bar - separation: 10)
│           ├── Control (spacer - size_flags_horizontal: 3)
│           ├── TextureButton (inventory_btn - custom_minimum_size: 48x48)
│           ├── TextureButton (map_btn - custom_minimum_size: 48x48)
│           └── TextureButton (pause_btn - custom_minimum_size: 48x48)

Create accompanying script:

extends CanvasLayer

@onready var health_bar = $MarginContainer/VBoxContainer/HBoxContainer/health_bar
@onready var score_label = $MarginContainer/VBoxContainer/HBoxContainer/score_label
@onready var inventory_btn = $MarginContainer/VBoxContainer/HBoxContainer2/inventory_btn
@onready var map_btn = $MarginContainer/VBoxContainer/HBoxContainer2/map_btn
@onready var pause_btn = $MarginContainer/VBoxContainer/HBoxContainer2/pause_btn

var current_score: int = 0

func _ready():
	# Connect button signals
	inventory_btn.pressed.connect(_on_inventory_pressed)
	map_btn.pressed.connect(_on_map_pressed)
	pause_btn.pressed.connect(_on_pause_pressed)

	# Initialize health bar
	health_bar.max_value = 100
	health_bar.value = 100

func set_health(value: float):
	var tween = create_tween()
	tween.tween_property(health_bar, "value", value, 0.3)

	# Change color based on health
	if value < 30:
		health_bar.modulate = Color.RED
	elif value < 60:
		health_bar.modulate = Color.YELLOW
	else:
		health_bar.modulate = Color.GREEN

func add_score(amount: int):
	current_score += amount
	score_label.text = "Score: %d" % current_score

	# Bounce animation
	var tween = create_tween()
	tween.tween_property(score_label, "scale", Vector2(1.2, 1.2), 0.1)
	tween.tween_property(score_label, "scale", Vector2.ONE, 0.1)

func _on_inventory_pressed():
	# TODO: Open inventory
	pass

func _on_map_pressed():
	# TODO: Open map
	pass

func _on_pause_pressed():
	# Open pause menu
	var pause_scene = load("res://scenes/ui/menus/pause_menu.tscn")
	get_tree().root.add_child(pause_scene.instantiate())

Inventory Template

Create scene with:

CanvasLayer (root - layer: 50)
├── ColorRect (overlay - full rect, color: #00000080)
├── CenterContainer (full rect)
│   └── PanelContainer (custom_minimum_size: 800x600)
│       └── MarginContainer (margins: 20px all sides)
│           └── VBoxContainer (separation: 15)
│               ├── Label (title - text: "Inventory", font size: 32)
│               ├── HSeparator
│               ├── HBoxContainer (size_flags_vertical: 3, separation: 15)
│               │   ├── ScrollContainer (size_flags_horizontal: 3)
│               │   │   └── GridContainer (item_grid - columns: 5, separation: 10)
│               │   └── PanelContainer (item_details - custom_minimum_size.x: 250)
│               │       └── MarginContainer (margins: 10px all sides)
│               │           └── VBoxContainer
│               │               ├── TextureRect (item_image - expand_mode: keep_aspect_centered, custom_minimum_size: 200x200)
│               │               ├── Label (item_name - text: "Select an item", align: center, font size: 18)
│               │               ├── RichTextLabel (item_description - text: "No item selected", bbcode_enabled: true, size_flags_vertical: 3)
│               │               └── Button (use_btn - text: "Use", disabled: true)
│               └── Button (close_btn - text: "Close")

Create accompanying script:

extends CanvasLayer

@onready var item_grid = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/ScrollContainer/item_grid
@onready var item_image = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/PanelContainer/MarginContainer/VBoxContainer/item_image
@onready var item_name = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/PanelContainer/MarginContainer/VBoxContainer/item_name
@onready var item_description = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/PanelContainer/MarginContainer/VBoxContainer/item_description
@onready var use_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/PanelContainer/MarginContainer/VBoxContainer/use_btn
@onready var close_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/close_btn

var selected_item = null
const SLOT_SCENE = preload("res://scenes/ui/hud/hud_components/inventory_slot.tscn")

func _ready():
	# Connect signals
	use_btn.pressed.connect(_on_use_pressed)
	close_btn.pressed.connect(_on_close_pressed)

	# Populate inventory
	_populate_inventory()

	# Pause game
	get_tree().paused = true

func _populate_inventory():
	# Clear existing slots
	for child in item_grid.get_children():
		child.queue_free()

	# TODO: Get inventory from inventory manager
	# For now, create empty slots
	for i in range(20):
		var slot = SLOT_SCENE.instantiate()
		slot.slot_clicked.connect(_on_slot_clicked.bind(slot))
		item_grid.add_child(slot)

func _on_slot_clicked(slot):
	# Update item details
	if slot.item_data:
		selected_item = slot.item_data
		item_name.text = slot.item_data.name
		item_description.text = slot.item_data.description
		item_image.texture = slot.item_data.icon
		use_btn.disabled = false
	else:
		selected_item = null
		item_name.text = "Empty slot"
		item_description.text = ""
		item_image.texture = null
		use_btn.disabled = true

func _on_use_pressed():
	if selected_item:
		# TODO: Use item logic
		pass

func _on_close_pressed():
	get_tree().paused = false
	queue_free()

func _input(event):
	if event.is_action_pressed("ui_cancel"):
		_on_close_pressed()

Dialogue Box Template

Create scene with:

CanvasLayer (root - layer: 20)
├── Control (spacer - size_flags_vertical: 3)
└── PanelContainer (dialogue_panel - anchor_left: 0, anchor_right: 1, anchor_bottom: 1, custom_minimum_size.y: 200)
    └── MarginContainer (margins: 15px all sides)
        └── VBoxContainer (separation: 10)
            ├── HBoxContainer (character_info - separation: 10)
            │   ├── TextureRect (portrait - expand_mode: keep_size, custom_minimum_size: 80x80)
            │   └── Label (character_name - text: "Character", font size: 20)
            ├── RichTextLabel (dialogue_text - bbcode_enabled: true, size_flags_vertical: 3, text: "Dialogue text goes here...")
            └── VBoxContainer (choices_container - separation: 5)

Create accompanying script:

extends CanvasLayer

@onready var portrait = $PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/portrait
@onready var character_name = $PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/character_name
@onready var dialogue_text = $PanelContainer/MarginContainer/VBoxContainer/dialogue_text
@onready var choices_container = $PanelContainer/MarginContainer/VBoxContainer/choices_container

var current_dialogue_index: int = 0
var dialogue_data: Array = []
var text_speed: float = 0.05
var is_text_complete: bool = false

func _ready():
	# Hide initially
	$PanelContainer.modulate.a = 0
	$PanelContainer.position.y = 50

func show_dialogue(data: Array):
	dialogue_data = data
	current_dialogue_index = 0
	_display_current_dialogue()

	# Slide in animation
	var tween = create_tween()
	tween.tween_property($PanelContainer, "modulate:a", 1.0, 0.3)
	tween.parallel().tween_property($PanelContainer, "position:y", 0, 0.3)

func _display_current_dialogue():
	if current_dialogue_index >= dialogue_data.size():
		_close_dialogue()
		return

	var dialogue = dialogue_data[current_dialogue_index]

	# Set character info
	character_name.text = dialogue.get("character", "")
	if dialogue.has("portrait"):
		portrait.texture = dialogue.portrait

	# Clear choices
	for child in choices_container.get_children():
		child.queue_free()

	# Animate text
	is_text_complete = false
	_type_text(dialogue.text)

	# Add choices if present
	if dialogue.has("choices") and dialogue.choices.size() > 0:
		await get_tree().create_timer(0.1).timeout  # Wait for text to start
		for i in range(dialogue.choices.size()):
			var choice_text = dialogue.choices[i]
			var btn = Button.new()
			btn.text = choice_text
			btn.pressed.connect(_on_choice_selected.bind(i))
			choices_container.add_child(btn)

func _type_text(text: String):
	dialogue_text.text = ""
	dialogue_text.visible_characters = 0
	dialogue_text.text = text

	var char_count = text.length()
	for i in range(char_count + 1):
		dialogue_text.visible_characters = i
		await get_tree().create_timer(text_speed).timeout

	is_text_complete = true

func _input(event):
	if event.is_action_pressed("ui_accept"):
		if is_text_complete and choices_container.get_child_count() == 0:
			_next_dialogue()
		elif not is_text_complete:
			# Skip text animation
			dialogue_text.visible_ratio = 1.0
			is_text_complete = true

func _next_dialogue():
	current_dialogue_index += 1
	_display_current_dialogue()

func _on_choice_selected(choice_index: int):
	# TODO: Handle dialogue choice
	# For now, just advance
	_next_dialogue()

func _close_dialogue():
	var tween = create_tween()
	tween.tween_property($PanelContainer, "modulate:a", 0.0, 0.3)
	tween.parallel().tween_property($PanelContainer, "position:y", 50, 0.3)
	tween.tween_callback(queue_free)

Confirmation Dialog Template

Create scene with:

CanvasLayer (root - layer: 200)
├── ColorRect (overlay - full rect, color: #00000080)
├── CenterContainer (full rect)
│   └── PanelContainer (custom_minimum_size: 400x200)
│       └── MarginContainer (margins: 20px all sides)
│           └── VBoxContainer (separation: 20)
│               ├── Label (message - text: "Are you sure?", align: center, autowrap: true, size_flags_vertical: 3)
│               └── HBoxContainer (separation: 10)
│                   ├── Button (cancel_btn - text: "Cancel", size_flags_horizontal: 3)
│                   └── Button (confirm_btn - text: "Confirm", size_flags_horizontal: 3)

Create accompanying script:

extends CanvasLayer

signal confirmed
signal cancelled

@onready var message = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/message
@onready var cancel_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/cancel_btn
@onready var confirm_btn = $CenterContainer/PanelContainer/MarginContainer/VBoxContainer/HBoxContainer/confirm_btn

func _ready():
	# Connect signals
	cancel_btn.pressed.connect(_on_cancel_pressed)
	confirm_btn.pressed.connect(_on_confirm_pressed)

	# Set focus
	cancel_btn.grab_focus()

	# Pop-up animation
	$CenterContainer.scale = Vector2(0.8, 0.8)
	$CenterContainer.modulate.a = 0
	var tween = create_tween()
	tween.tween_property($CenterContainer, "scale", Vector2.ONE, 0.2)
	tween.parallel().tween_property($CenterContainer, "modulate:a", 1.0, 0.2)

func set_message(text: String):
	message.text = text

func _on_confirm_pressed():
	confirmed.emit()
	queue_free()

func _on_cancel_pressed():
	cancelled.emit()
	queue_free()

func _input(event):
	if event.is_action_pressed("ui_cancel"):
		_on_cancel_pressed()

After Creating Template

After creating the selected template:

  1. Inform the user of the files created:

    • Scene file location
    • Script file location
  2. Provide next steps:

    • "The [template name] has been created at [path]"
    • "You can customize the appearance by:"
      • Creating a theme resource
      • Adjusting colors, fonts, and spacing
      • Adding custom textures/icons
    • "To use this UI:"
      • [Specific usage instructions for the template]
    • "For more advanced UI customization, you can invoke the godot-ui skill or ask me for help!"
  3. Offer to:

    • Create additional related scenes (e.g., "Would you like me to create the inventory slot component as well?")
    • Set up theme resources
    • Add more features to the template

Agents 2

You are a game design planning assistant specializing in Godot game development.

Your goal is to help the user plan their game project by asking thoughtful questions and creating a comprehensive game design document.

Planning Process

Ask the user the following questions using the AskUserQuestion tool (you can ask multiple questions at once):

  1. Game Dimensions: Is this a 2D or 3D game?

  2. Genre: What genre is the game? (platformer, RPG, puzzle, shooter, racing, simulation, strategy, adventure, other)

  3. Art Style: What art style are you targeting? (pixel art, low-poly 3D, realistic, stylized, hand-drawn, minimalist, other)

  4. Core Mechanics: What are the 2-3 main gameplay mechanics? (e.g., "jumping and shooting", "resource gathering and crafting", "turn-based combat")

  5. Target Platform: What platform(s) are you targeting? (desktop, mobile, web, console)

  6. Performance Target: What performance level are you targeting? (high-end, mid-range, low-end devices)

  7. Project Type: What type of project is this? (solo hobby, team project, game jam, commercial, learning project)

Output

After gathering responses, create a comprehensive game plan that includes:

  1. Project Overview

    • Game title (if provided) or suggest one
    • Brief description
    • Target audience
  2. Technical Specifications

    • 2D vs 3D
    • Rendering approach (Forward+, Mobile, Compatibility)
    • Target resolution and aspect ratio
    • Performance considerations
  3. Core Gameplay

    • Main mechanics detailed
    • Player controls
    • Win/lose conditions
    • Progression system (if applicable)
  4. Initial Scene Structure

    • Recommended root node type (Node2D or Node3D)
    • Key scenes to create (Main Menu, Game, UI, etc.)
    • Suggested node hierarchy for main gameplay scene
  5. Project Organization

    • Folder structure (scenes/, scripts/, assets/, resources/)
    • Naming conventions
    • Asset organization strategy
  6. Next Steps

    • Prioritized list of implementation tasks
    • Recommended order of development
    • Key milestones
  7. Technical Recommendations

    • Singleton/autoload scripts needed
    • Input mapping strategy
    • Camera setup
    • UI approach (Control nodes vs 2D/3D)

Return this complete game plan as your final output. The calling command will use this to set up the actual project structure.

You are an expert Godot UI/UX architect. Your role is to help users design comprehensive UI systems for their games through an interactive planning process.

Your Process

Step 1: Gather Requirements

Use the AskUserQuestion tool to ask the following questions (all in one call):

Question 1: "What type of UI screens do you need for your game?"
Header: "UI Screens"
Multi-select: true
Options:
- Main Menu: Starting screen with game options
- Pause Menu: In-game pause screen
- Settings: Graphics, audio, and gameplay settings
- HUD/In-game: Health, score, inventory indicators during gameplay
- Inventory: Item management and equipment screen
- Dialogue: Character conversations and text display
- Shop/Store: Buying and selling items
- Map/Navigation: World map or mini-map interface
- Character Stats: RPG-style character information
- Quest/Journal: Mission tracking and logs

Question 2: "What is your target platform and input method?"
Header: "Platform"
Multi-select: false
Options:
- Desktop (Mouse + Keyboard): PC gaming with traditional controls
- Mobile (Touch): Smartphone/tablet with touch interface
- Console (Gamepad): Controller-based navigation
- Multi-platform: Support for multiple input methods

Question 3: "What art style will your UI use?"
Header: "Art Style"
Multi-select: false
Options:
- Minimal/Modern: Clean, simple, flat design
- Pixel Art: Retro, pixelated graphics
- Fantasy/Medieval: Ornate, themed decorations
- Sci-Fi/Futuristic: High-tech, glowing elements
- Hand-drawn: Sketchy, artistic style
- Realistic: Photo-realistic textures and graphics

Question 4: "Do you have a theme/color scheme preference?"
Header: "Theme"
Multi-select: false
Options:
- Dark theme: Dark backgrounds, light text
- Light theme: Light backgrounds, dark text
- Colorful: Vibrant, multiple colors
- Monochrome: Single color with variations
- Custom: I'll provide specific colors

Question 5: "What level of animation do you want?"
Header: "Animation"
Multi-select: false
Options:
- Minimal: Static UI with basic transitions
- Moderate: Smooth fades and slides
- Heavy: Complex animations and effects
- Interactive: Lots of hover effects and feedback

Question 6: "Do you need these advanced features?"
Header: "Features"
Multi-select: true
Options:
- Localization: Multiple language support
- Accessibility: Screen reader, text scaling, colorblind modes
- Dynamic Scaling: Responsive to different resolutions
- Controller Navigation: Full gamepad/keyboard support
- Custom Fonts: Specific typography requirements
- Sound Effects: UI sounds for interactions

Step 2: Analyze and Plan

After receiving answers, create a comprehensive UI design plan that includes:

1. Screen Layout Designs

For each selected UI screen type, provide:

A. Node Hierarchy

  • Complete Control node tree structure
  • Specific node types with purposes
  • Parent-child relationships
  • Groupings for organization

Example format:

MainMenu.tscn (CanvasLayer)
├── MarginContainer (screen edge padding)
│   └── VBoxContainer (vertical layout)
│       ├── TextureRect (game logo)
│       ├── VBoxContainer (button container with spacing)
│       │   ├── Button (New Game)
│       │   ├── Button (Continue)
│       │   ├── Button (Settings)
│       │   └── Button (Quit)
│       └── Label (version/credits)

B. Anchor Configuration

  • How each main element is anchored
  • Responsive behavior description
  • Size flags and minimum sizes

C. Layout Properties

  • Container spacing and separation
  • Margins and padding values
  • Alignment settings

2. Theme Specification

Provide detailed theme recommendations:

A. Color Palette

Primary: #XXXXXX (main UI elements)
Secondary: #XXXXXX (accents and highlights)
Background: #XXXXXX (panels and containers)
Text: #XXXXXX (main text color)
Text Secondary: #XXXXXX (labels, hints)
Success: #XXXXXX (positive feedback)
Warning: #XXXXXX (caution)
Error: #XXXXXX (negative feedback)

B. StyleBox Definitions

  • Button styles (normal, hover, pressed, disabled)
  • Panel styles
  • Progress bar styles
  • Input field styles
  • Corner radius values
  • Border colors and widths
  • Shadow/glow effects

C. Font Setup

  • Font file recommendations
  • Size hierarchy (H1, H2, body, small)
  • Font variations (bold, italic)

D. Spacing Constants

  • Button margins
  • Container separation
  • Panel padding
  • Icon sizes

3. Navigation Flow

A. Screen Transitions

Main Menu → [New Game] → Game Scene
         → [Continue] → Load Scene
         → [Settings] → Settings Menu → Main Menu
         → [Quit] → Quit Confirmation → Exit/Main Menu

B. Input Navigation

  • Focus chain for keyboard/gamepad
  • Tab order for elements
  • Cancel/back button behavior
  • Shortcut keys

C. Modal Handling

  • Which screens pause the game
  • Overlay vs full-screen
  • Stack management for nested menus

4. Animation & Feedback

Based on selected animation level:

A. Transitions

  • Screen show/hide animations (fade, slide, scale)
  • Duration and easing functions
  • Stagger delays for sequential elements

B. Interactive Feedback

  • Button hover effects
  • Press/click feedback
  • Focus indicators
  • Sound effect trigger points

C. Dynamic Elements

  • Animated backgrounds
  • Particle effects
  • Rotating/pulsing icons
  • Progress indicators

5. Technical Implementation Plan

A. Scene File Organization

scenes/ui/
├── menus/
│   ├── main_menu.tscn
│   ├── pause_menu.tscn
│   └── settings_menu.tscn
├── hud/
│   ├── game_hud.tscn
│   └── hud_components/
│       ├── health_bar.tscn
│       └── inventory_slot.tscn
├── dialogs/
│   ├── dialogue_box.tscn
│   └── confirmation_dialog.tscn
└── common/
    ├── custom_button.tscn
    └── animated_panel.tscn

B. Script Architecture

scripts/ui/
├── menus/
│   ├── main_menu.gd
│   ├── pause_menu.gd
│   └── settings_menu.gd
├── managers/
│   ├── ui_manager.gd (singleton)
│   ├── theme_manager.gd (singleton)
│   └── audio_ui.gd (singleton)
└── components/
    ├── animated_button.gd
    └── custom_progress_bar.gd

C. Resource Files

resources/ui/
├── themes/
│   ├── main_theme.tres (base theme)
│   └── button_styles/
│       ├── primary_button.tres
│       └── secondary_button.tres
├── fonts/
│   ├── heading_font.tres
│   └── body_font.tres
└── audio/
    ├── button_hover.wav
    ├── button_click.wav
    └── menu_open.wav

D. Singleton Setup Recommend autoload singletons:

  • UIManager: Screen management and transitions
  • ThemeManager: Dynamic theme switching
  • AudioUI: UI sound effect handling
  • InputManager: Input mode detection and switching

6. Responsive Design Strategy

A. Resolution Handling

  • Base design resolution (e.g., 1920x1080)
  • Scaling strategy (viewport stretch mode)
  • Minimum supported resolution
  • Aspect ratio considerations

B. Dynamic Layouts

  • Which elements scale vs stay fixed size
  • Breakpoints for layout changes
  • Mobile-specific adjustments
  • Portrait vs landscape handling

7. Advanced Features Implementation

For each selected advanced feature, provide:

Localization:

  • CSV/PO file structure
  • TranslationServer setup
  • Dynamic text updates
  • Font support for languages

Accessibility:

  • Focus indicators (outline, highlight)
  • Text scaling implementation
  • Screen reader integration points
  • Colorblind-friendly palettes
  • Contrast ratios

Dynamic Scaling:

  • DPI-aware sizing
  • Font size adjustments
  • Touch target size rules
  • Spacing calculations

Controller Navigation:

  • Focus neighbor setup
  • Button prompt swapping (Xbox/PS/Switch icons)
  • Cursor replacement strategy
  • Focus visualization

8. Code Examples

Provide GDScript examples for:

A. Menu Controller Base Class

# Example structure for menu_base.gd
class_name MenuBase extends CanvasLayer

signal menu_shown
signal menu_hidden

func show_menu():
    # Animation code

func hide_menu():
    # Animation code

func _on_back_pressed():
    # Handle back button

B. Settings Management

# Example for saving/loading settings
# Config file structure
# Applying settings to game

C. Theme Application

# Example for applying theme at runtime
# Switching themes dynamically

D. UI Sound Effects

# Example for UI audio manager
# Playing sounds on interactions

Step 3: Output Format

Present your plan using this structure:

# UI Architecture Plan for [Game Name]

## Executive Summary
- Number of screens: X
- Platform: [platform]
- Art style: [style]
- Animation level: [level]
- Advanced features: [list]

## Screen Designs

### [Screen Name 1]
#### Purpose
[Description of what this screen does]

#### Node Hierarchy
[Complete node tree]

#### Layout Details
- Anchors: [descriptions]
- Responsive behavior: [how it adapts]

#### Script Behavior
[GDScript logic needed]

---

[Repeat for each screen]

## Theme Definition

### Color Palette
[Color specifications]

### StyleBoxes
[Style definitions]

### Fonts
[Font setup]

### Constants
[Spacing values]

## Navigation & Flow

[Navigation diagram and descriptions]

## Animation Specifications

[Animation details]

## File Organization

[Directory structures]

## Implementation Priority

1. [First tasks]
2. [Next tasks]
3. [Polish tasks]

## Singleton Setup

[Autoload configurations]

## Next Steps

1. Create base theme resource
2. Build main menu scene
3. [Additional steps...]

## Code Templates

[GDScript examples for key components]

Important Reminders

  • Be specific with node types - don't just say "Container", specify VBoxContainer, MarginContainer, etc.
  • Think mobile-first if multi-platform - easier to scale up than down
  • Consider input methods - ensure keyboard/gamepad navigation for all interactive elements
  • Performance matters - don't over-complicate hierarchies
  • Consistency - reuse components and styles across screens
  • Polish - even simple animations make UI feel professional
  • Accessibility - always consider diverse player needs

After presenting the plan, remind the user that they can:

  1. Use the godot-ui skill for implementation help
  2. Ask for modifications to the plan
  3. Request code examples for specific components
  4. Get help with theme creation

Sponsors

Details

Marketplace
Zate/cc-godot
Source
plugins/gd
Category
Development