Godot Gdscript Architect

The Problem

You ask your AI agent to write a player controller for your Godot 4 game. It produces code that uses KinematicBody2D (renamed to CharacterBody2D in Godot 4), calls move_and_slide(velocity) instead of capturing the return value velocity = move_and_slide(), uses yield() instead of await, and connects signals with string-based connect("signal_name", self, "_on_signal") — all of which compile in Godot 3 but fail or behave wrong in Godot 4. Worse, it builds a deep inheritance tree (Enemy → FlyingEnemy → BatEnemy → BossBatEnemy) when Godot's composition model expects small, reusable component scenes. You spend more time fixing the agent's Godot 3 artifacts than you would have spent writing the code yourself.

What You Get

• Godot 3 → 4 API baseline with a complete deprecated/replacement table covering yield→await, get_node→@onready, untyped signals→typed signals, KinematicBody→CharacterBody, export var→@export, move_and_slide return value changes, and 15+ other API migrations
• Composition-over-inheritance architecture teaching scene-based design with small focused components (HealthComponent, HitboxComponent, StateMachine) instead of deep class hierarchies — with ready-to-use GDScript templates for each pattern
• State machine pattern using Godot 4's node hierarchy — StateMachine node with child state nodes, each implementing enter()/exit()/process()/physics_process(), with @export-driven initial state configuration and typed signal transitions
• Signal system mastery covering typed signal declarations, editor connections (preferred for static wiring), code connections with callable syntax, one-shot connections (CONNECT_ONE_SHOT), lambda connections, and disconnect patterns
• @export-driven designer architecture separating configuration from code so designers can tweak move speed, jump velocity, damage values, and scene references from the editor without touching scripts
• Resource-based data design replacing raw Dictionaries with typed Resource subclasses (ItemResource, WeaponData, DialogueTree) that are serializable, inspector-editable, and saveable as .tres files
• Performance rules including _physics_process vs _process placement, object pooling for spawned entities, @onready node caching, call_deferred for scene changes during physics, and typed Array performance benefits

Why This Beats Prompting It Yourself

When you tell an agent "write a Godot 4 player controller," it produces syntactically valid GDScript — but valid for Godot 3, not 4. The API differences are subtle enough that the agent doesn't flag them as errors: yield() compiles with a deprecation warning, get_node() works but is fragile, and move_and_slide(velocity) silently drops the return value. This skill hardcodes the Godot 4 API baseline so every generated line uses correct patterns from the start. It also enforces Godot's composition philosophy — agents naturally reach for OOP inheritance when the engine rewards scene composition.

Example Session

You: "Create an enemy AI that patrols between waypoints and chases the player when detected."

Agent output (with skill):

class_name EnemyPatrolState
extends State

@export var move_speed: float = 100.0
@export var patrol_points: Array[Marker2D] = []
@export var detection_range: float = 200.0

var current_point_index: int = 0
var enemy: CharacterBody2D
var player_detection_area: Area2D

func enter(data: Dictionary = {}) -> void:
    enemy = state_machine.owner as CharacterBody2D
    player_detection_area = enemy.get_node("PlayerDetectionArea")
    player_detection_area.body_entered.connect(_on_body_entered_detection)

func exit() -> void:
    player_detection_area.body_entered.disconnect(_on_body_entered_detection)

func physics_process(delta: float) -> void:
    if patrol_points.is_empty():
        return
    var target: Vector2 = patrol_points[current_point_index].global_position
    var direction: Vector2 = (target - enemy.global_position).normalized()
    enemy.velocity = direction * move_speed
    enemy.move_and_slide()  # Godot 4: return value is velocity
    if enemy.global_position.distance_to(target) < 10.0:
        current_point_index = (current_point_index + 1) % patrol_points.size()

Use Cases

• Creating new Godot 4 scenes, scripts, or game systems from scratch with correct patterns
• Auditing existing GDScript for Godot 3-isms, performance anti-patterns, and architectural violations
• Designing game systems (player controller, inventory, save/load, enemy AI, UI) using composition
• Setting up autoloads for global systems (EventBus, SaveManager, AudioManager) with proper boundaries
• Optimizing performance: object pooling, physics layer setup, _process/_physics_process placement

Known Limitations

The skill targets Godot 4.x specifically and does not generate Godot 3-compatible code. For projects maintaining Godot 3 compatibility, this skill should not be active. The composition patterns assume familiarity with Godot's scene/node system; developers brand-new to Godot may need additional onboarding. The state machine pattern provided is a specific implementation — Godot supports multiple state machine approaches (node-based, resource-based, enum-based) and the right choice depends on project complexity.