trenchlock/.agents/skills/godot-dev/SKILL.md

name, description

name	description
godot-dev	Develops Godot 4.5+ games with GDScript. Creates scenes, scripts, resources, and nodes. Use when working on Godot projects, writing GDScript, or building game features.

Godot 4.5+ Development Skill

Capabilities

• Create and modify GDScript files with proper Godot 4.5 syntax
• Design scene hierarchies and node structures
• Implement common game patterns (state machines, singletons, signals)
• Debug and fix GDScript errors
• Create custom resources and exported properties

GDScript Quick Reference

Script Template

class_name MyClass
extends Node

signal my_signal(value: int)

@export var speed: float = 100.0
@onready var sprite: Sprite2D = $Sprite2D

var _private_var: int = 0

func _ready() -> void:
    pass

func _process(delta: float) -> void:
    pass

func _physics_process(delta: float) -> void:
    pass

Common Node Types

• Node2D/Node3D: Base spatial nodes
• CharacterBody2D/3D: Player/enemy controllers
• RigidBody2D/3D: Physics objects
• Area2D/3D: Triggers and detection zones
• Control: UI elements (Button, Label, Panel, etc.)
• AudioStreamPlayer: Sound effects and music

Signal Patterns

# Declare
signal health_changed(new_value: int)

# Emit
health_changed.emit(current_health)

# Connect in code
other_node.health_changed.connect(_on_health_changed)

# Await
await get_tree().create_timer(1.0).timeout
var result = await some_signal

Input Handling

func _input(event: InputEvent) -> void:
    if event.is_action_pressed("jump"):
        jump()

func _process(delta: float) -> void:
    var direction = Input.get_vector("left", "right", "up", "down")
    velocity = direction * speed

Resource Creation

class_name ItemData
extends Resource

@export var name: String = ""
@export var icon: Texture2D
@export var value: int = 0
@export_multiline var description: String = ""

State Machine Pattern

enum State { IDLE, WALK, JUMP, ATTACK }
var current_state: State = State.IDLE

func _physics_process(delta: float) -> void:
    match current_state:
        State.IDLE:
            _handle_idle(delta)
        State.WALK:
            _handle_walk(delta)
        State.JUMP:
            _handle_jump(delta)

Tween Animations

func fade_out() -> void:
    var tween = create_tween()
    tween.tween_property(self, "modulate:a", 0.0, 0.5)
    await tween.finished
    queue_free()

Scene Structure Best Practices

• Root node named after the scene purpose (Player, Enemy, MainMenu)
• Group related nodes under organizational Node2D/Node3D
• Use %UniqueNodeName syntax for unique node access
• Prefer composition over inheritance

Debugging Commands

# Validate project
godot --headless --quit

# Run with verbose logging
godot --verbose

# Run specific scene
godot --path . res://scenes/test.tscn

Common Fixes

• Null reference: Check @onready nodes exist, use is_instance_valid()
• Signal not found: Ensure signal is declared before connecting
• Type errors: Add explicit type hints, check return types
• Physics issues: Verify collision layers/masks are set correctly