trenchlock/AGENTS.md

Godot 4.5.1 Development - Agent Configuration

Project Info

• Engine: Godot 4.5.1
• Language: GDScript (primary), C# (optional)
• Project Root: Contains project.godot

Commands

# Run project
godot --path . 

# Run headless (for validation/testing)
godot --headless --quit --script res://path/to/script.gd

# Export project
godot --headless --export-release "preset_name" output_path

# Validate/check project
godot --headless --quit

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

# Generate documentation
godot --doctool docs/ --gdscript-docs res://

Code Style

GDScript Conventions

• Use snake_case for variables, functions, signals
• Use PascalCase for class names and node types
• Use SCREAMING_SNAKE_CASE for constants
• Prefix private members with _
• Use type hints: var speed: float = 100.0
• Use @export for editor-exposed variables
• Use @onready for node references

File Naming

• Scripts: snake_case.gd (e.g., player_controller.gd)
• Scenes: snake_case.tscn (e.g., main_menu.tscn)
• Resources: snake_case.tres (e.g., player_stats.tres)

Project Structure

res://
├── scenes/           # .tscn scene files
├── scripts/          # .gd script files
├── assets/
│   ├── sprites/
│   ├── audio/
│   └── fonts/
├── resources/        # .tres resource files
├── autoload/         # Singleton scripts
└── addons/           # Third-party plugins

Godot 4.5 Specifics

• Use @export instead of export
• Use @onready instead of onready
• Use super() instead of .call()
• Signals: signal_name.emit() instead of emit_signal("signal_name")
• Await: await signal_name instead of yield
• String formatting: "Value: %s" % value or "Value: {val}".format({"val": value})

Testing

• Use GUT (Godot Unit Test) for unit testing if available
• Test scripts in res://tests/
• Run tests: godot --headless --script res://addons/gut/gut_cmdln.gd

Common Patterns

Singleton/Autoload

# In Project Settings > AutoLoad
extends Node

var game_state: Dictionary = {}

func _ready() -> void:
	pass

Signal Pattern

signal health_changed(new_health: int)

func take_damage(amount: int) -> void:
	health -= amount
	health_changed.emit(health)

Resource Pattern

class_name WeaponData extends Resource

@export var damage: int = 10
@export var fire_rate: float = 0.5

MCP Server (Recommended)

Install Coding-Solo/godot-mcp for:

• Launch editor programmatically
• Run projects and capture debug output
• Scene management (create/modify scenes)
• UID management (Godot 4.4+)

Setup

git clone https://github.com/Coding-Solo/godot-mcp
cd godot-mcp
npm install
npm run build

Configuration (add to MCP settings)

{
  "godot": {
	"command": "node",
	"args": ["/path/to/godot-mcp/build/index.js"],
	"env": {
	  "GODOT_PATH": "/path/to/godot"
	}
  }
}

Documentation MCP (Optional)

For up-to-date Godot docs access:

{
  "godot-docs": {
	"url": "https://doc-mcp.fly.dev/mcp/"
  }
}