godot

Godot Engine Development Skill

Specialized guidance for developing games and applications with Godot Engine, with emphasis on effective collaboration between LLM coding assistants and Godot's unique file structure.

Overview

Godot projects use a mix of GDScript code files (.gd) and text-based resource files (.tscn for scenes, .tres for resources). While GDScript is straightforward, the resource files have strict formatting requirements that differ significantly from GDScript syntax. This skill provides file format expertise, proven architecture patterns, validation tools, code templates, and debugging workflows to enable effective development of Godot projects.

When to Use This Skill

Invoke this skill when:

• Working on any Godot Engine project
• Creating or modifying .tscn (scene) or .tres (resource) files
• Implementing game systems (interactions, attributes, spells, inventory, etc.)
• Debugging "file failed to load" or similar resource errors
• Setting up component-based architectures
• Creating signal-driven systems
• Implementing resource-based data (items, spells, abilities)

Key Principles

1. Understand File Format Differences

GDScript (.gd) - Full Programming Language:

extends Node
class_name MyClass

var speed: float = 5.0
const MAX_HEALTH = 100

func _ready():
    print("Ready")

Scene Files (.tscn) - Strict Serialization Format:

[ext_resource type="Script" path="res://script.gd" id="1"]

[node name="Player" type="CharacterBody3D"]
script = ExtResource("1")  # NOT preload()!

Resource Files (.tres) - NO GDScript Syntax:

[ext_resource type="Script" path="res://item.gd" id="1"]

[resource]
script = ExtResource("1")  # NOT preload()!
item_name = "Sword"        # NOT var item_name = "Sword"!

2. Critical Rules for .tres and .tscn Files

NEVER use in .tres/.tscn files:

• preload() - Use ExtResource("id") instead
• var, const, func - These are GDScript keywords
• Untyped arrays - Use Array[Type]([...]) syntax

ALWAYS use in .tres/.tscn files:

• ExtResource("id") for external resources
• SubResource("id") for inline resources
• Typed arrays: Array[Resource]([...])
• Proper ExtResource declarations before use

3. Separation of Concerns

Keep logic in .gd files, data in .tres files:

src/
  spells/
    spell_resource.gd      # Class definition + logic
    spell_effect.gd        # Effect logic
resources/
  spells/
    fireball.tres          # Data only, references scripts
    ice_spike.tres         # Data only

This makes LLM editing much safer and clearer.

4. Component-Based Architecture

Break functionality into small, focused components:

Player (CharacterBody3D)
├─ HealthAttribute (Node)     # Component
├─ ManaAttribute (Node)        # Component
├─ Inventory (Node)            # Component
└─ StateMachine (Node)         # Component
    ├─ IdleState (Node)
    ├─ MoveState (Node)
    └─ AttackState (Node)

Benefits:

• Each component is a small, focused file
• Easy to understand and modify
• Clear responsibilities
• Reusable across different entities

5. Signal-Driven Communication

Use signals for loose coupling:

# Component emits signals
signal health_changed(current, max)
signal death()

# Parent connects to signals
func _ready():
    $HealthAttribute.health_changed.connect(_on_health_changed)
    $HealthAttribute.death.connect(_on_death)

Benefits:

• No tight coupling between systems
• Easy to add new listeners
• Self-documenting (signals show available events)
• UI can connect without modifying game logic

Using Bundled Resources

Validation Scripts

Validate .tres and .tscn files before testing in Godot to catch syntax errors early.

Validate .tres file:

python3 scripts/validate_tres.py resources/spells/fireball.tres

Validate .tscn file:

python3 scripts/validate_tscn.py scenes/player/player.tscn

Use these scripts when:

• After creating or editing .tres/.tscn files programmatically
• When debugging "failed to load" errors
• Before committing scene/resource changes
• When user reports issues with custom resources

Reference Documentation

Load reference files when needed for detailed information:

references/file-formats.md - Deep dive into .gd, .tscn, .tres syntax:

• Complete syntax rules for each file type
• Common mistakes with examples
• Safe vs risky editing patterns
• ExtResource and SubResource usage

references/architecture-patterns.md - Proven architectural patterns:

• Component-based interaction system
• Attribute system (health, mana, etc.)
• Resource-based effect system (spells, items)
• Inventory system
• State machine pattern
• Examples of combining patterns

Read these references when:

• Implementing new game systems
• Unsure about .tres/.tscn syntax
• Debugging file format errors
• Planning architecture for new features

Code Templates

Use templates as starting points for common patterns. Templates are in assets/templates/:

component_template.gd - Base component with signals, exports, activation:

# Copy and customize for new components
cp assets/templates/component_template.gd src/components/my_component.gd

attribute_template.gd - Numeric attribute (health, mana, stamina):

# Use for any numeric attribute with min/max
cp assets/templates/attribute_template.gd src/attributes/stamina_attribute.gd

interaction_template.gd - Interaction component base class:

# Extend for custom interactions (pickup, door, switch, etc.)
cp assets/templates/interaction_template.gd src/interactions/lever_interaction.gd

spell_resource.tres - Example spell with effects:

# Use as reference for creating new spell data
cat assets/templates/spell_resource.tres

item_resource.tres - Example item resource:

# Use as reference for creating new item data
cat assets/templates/item_resource.tres

Workflows

Workflow 1: Creating a New Component System

Example: Adding a health system to enemies.

Steps:

1. Read architecture patterns reference:

   # Check for similar patterns
   Read references/architecture-patterns.md
   # Look for "Attribute System" section
   

2. Create base class using template:

   cp assets/templates/attribute_template.gd src/attributes/attribute.gd
   # Customize the base class
   

3. Create specialized subclass:

   # Create health_attribute.gd extending attribute.gd
   # Add health-specific signals (damage_taken, death)
   

4. Add to scene via .tscn edit:

   [ext_resource type="Script" path="res://src/attributes/health_attribute.gd" id="4_health"]
   
   [node name="HealthAttribute" type="Node" parent="Enemy"]
   script = ExtResource("4_health")
   value_max = 50.0
   value_start = 50.0
   

5. Test immediately in Godot editor

6. If issues, validate the scene file:

   python3 scripts/validate_tscn.py scenes/enemies/base_enemy.tscn
   

Workflow 2: Creating Resource Data Files (.tres)

Example: Creating a new spell.

Steps:

1. Reference the template:

   cat assets/templates/spell_resource.tres
   

2. Create new .tres file with proper structure:

   [gd_resource type="Resource" script_class="SpellResource" load_steps=3 format=3]
   
   [ext_resource type="Script" path="res://src/spells/spell_resource.gd" id="1"]
   [ext_resource type="Script" path="res://src/spells/spell_effect.gd" id="2"]
   
   [sub_resource type="Resource" id="Effect_1"]
   script = ExtResource("2")
   effect_type = 0
   magnitude_min = 15.0
   magnitude_max = 25.0
   
   [resource]
   script = ExtResource("1")
   spell_name = "Fireball"
   spell_id = "fireball"
   mana_cost = 25.0
   effects = Array[ExtResource("2")]([SubResource("Effect_1")])
   

3. Validate before testing:

   python3 scripts/validate_tres.py resources/spells/fireball.tres
   

4. Fix any errors reported by validator

5. Test in Godot editor

Workflow 3: Debugging Resource Loading Issues

When user reports "resource failed to load" or similar errors.

Steps:

1. Read the file reported in error:

   # Check file syntax
   Read resources/spells/problem_spell.tres
   

2. Run validation script:

   python3 scripts/validate_tres.py resources/spells/problem_spell.tres
   

3. Check for common mistakes:

   • Using preload() instead of ExtResource()
   • Using var, const, func keywords
   • Missing ExtResource declarations
   • Incorrect array syntax (not typed)

4. Read file format reference if needed:

   Read references/file-formats.md
   # Focus on "Resource Files (.tres)" section
   # Check "Common Mistakes Reference"
   

5. Fix errors and re-validate

Workflow 4: Implementing from Architecture Patterns

When implementing a known pattern (interaction system, state machine, etc.).

Steps:

1. Read the relevant pattern:

   Read references/architecture-patterns.md
   # Find the specific pattern (e.g., "Component-Based Interaction System")
   

2. Copy relevant template:

   cp assets/templates/interaction_template.gd src/interactions/door_interaction.gd
   

3. Customize the template:

   • Override _perform_interaction()
   • Add custom exports for configuration
   • Add custom signals if needed

4. Create scene structure following pattern:

   [node name="Door" type="StaticBody3D"]
   script = ExtResource("base_interactable.gd")
   
   [node name="DoorInteraction" type="Node" parent="."]
   script = ExtResource("door_interaction.gd")
   interaction_text = "Open Door"
   

5. Test incrementally

Common Pitfalls and Solutions

Pitfall 1: Using GDScript Syntax in .tres Files

Problem:

# ❌ WRONG
script = preload("res://script.gd")
var items = 

---

*Content truncated.*