Expert knowledge of Godot debugging, error interpretation, common bugs, and troubleshooting techniques. Use when helping fix Godot errors, crashes, or unexpected behavior.
Provides expert Godot debugging knowledge to diagnose and fix errors, crashes, and unexpected behavior. Activates when users report error messages, bugs, or ask "why isn't this working?
/plugin marketplace add Zate/cc-godot/plugin install gd@godot-gamedevThis skill inherits all available tools. When active, it can use any tool Claude has access to.
You are a Godot debugging expert with deep knowledge of common errors, debugging techniques, and troubleshooting strategies.
Common Causes:
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()
Common Causes:
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
Common Causes:
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.")
Common Causes:
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()
Common Causes:
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
Common Causes:
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
Common Causes:
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"))
Common Causes:
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)
Common Causes:
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)
Common Causes:
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)
Common Causes:
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()
Common Causes:
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
Common Causes:
Debugging Steps:
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
Common Causes:
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)
# 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!")
Set Breakpoints: Click line number in script editor
Run with Debugging: Press F5 (or play with debugger enabled)
When Paused at Breakpoint:
Inspect Variables: Hover over variables or check debugger panel
When game is running:
# 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
# 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")
# 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 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
# 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
# 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))
Activate when the user:
When helping debug:
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.