Godot Agent Skill

Godot 4.x (GDScript + C#)

Build 2D and 3D the way the engine is designed: scenes as reusable units, composition over deep node

trees, signals for decoupling, static typing for speed and safety. GDScript (typed) is primary; C#

parity snippets sit beside it.

Version contract — read first

This is Godot 4.x. Never emit Godot 3 APIs. Godot 4 renamed core nodes, moved annotations

behind @, replaced yield with await, and switched signal/file/tween APIs. A Godot 3 snippet

will not even parse in 4.x. Before writing or accepting any line, check it against this ban-list:

| Never (Godot 3) | Always (Godot 4.x) |

| --- | --- |

| yield(timer, "timeout") | await timer.timeout |

| onready var x = ... | @onready var x = ... |

| export var hp = 3 | @export var hp := 3 |

| tool (script mode line) | @tool (annotation, first line) |

| KinematicBody / KinematicBody2D | CharacterBody3D / CharacterBody2D |

| Spatial | Node3D |

| Area / RigidBody / StaticBody | Area3D / RigidBody3D / StaticBody3D |

| Sprite | Sprite2D |

| scene.instance() | scene.instantiate() |

| move_and_slide(velocity, UP) (positional) | set velocity property, then move_and_slide() — no args |

| connect("hit", self, "_on_hit") | node.hit.connect(_on_hit) (Callable) |

| File.new() / Directory.new() | FileAccess.open(...) / DirAccess.open(...) |

| standalone Tween node + interpolate_property | create_tween() → tween.tween_property(...) |

| OS.get_ticks_msec for gameplay timing | Time.get_ticks_msec() (OS timing moved to Time) |

| PoolByteArray / PoolVector2Array | PackedByteArray / PackedVector2Array |

Lifecycle overrides must chain the parent with super() (Godot 3 called it implicitly; Godot 4

does not). If you override _ready, _process, _init, etc. in a script that extends another

script defining them, call super() / super._ready() or the base logic silently never runs.

Silent-breakers (compile fine, behave wrong — the dangerous class):

• Array.slice(begin, end) — end is now exclusive (was inclusive in Godot 3). [1,2,3,4].slice(1,3) → [2,3].
• Camera2D.zoom is inverted vs Godot 3: a larger zoom now means zoomed in (magnified). Vector2(2,2) = 2× magnification, not half.
• TileMap is deprecated → use one TileMapLayer node per layer (since 4.3).
• Angles are radians; _process(delta) delta is a float (GDScript) / double (C#) in seconds.

Full table with every rename → references/godot3-to-4-traps.md.

Project & scene organization

• The scene (.tscn) is the reusable unit — a self-contained tree you instance many times

(a Player, a Bullet, a HUD). Prefer composition: small scenes/nodes assembled, not one

60-node monolith. If a subtree has its own behavior, make it its own scene.

• One responsibility per script. Attach behavior to the scene's root; child nodes are parts.
• class_name Foo registers a global type usable in the inspector and as Foo.new(). Use it for

reusable scripts and custom Resources; skip it for one-off scene scripts.

• Files: snake_case.gd / snake_case.tscn for scenes and scripts; PascalCase for node

names in the tree and for class_name. Group by feature (player/, enemy/, ui/), not by type.

Nodes vs scenes vs scripts vs custom Resources

| You need | Use |

| --- | --- |

| A thing in the tree that renders / moves / collides / processes | a Node (typed subclass) |

| A reusable, instanceable bundle of nodes | a scene (.tscn) |

| Behavior attached to a node | a script (.gd / .cs) |

| Pure data (stats, items, dialogue, level config) with no place in the tree | a custom Resource (.tres) |

Custom Resources are Godot's typed, savable, inspector-editable data objects — reach for them

instead of loose Dictionaries or JSON for game data. See references/nodes-scenes-resources.md.

class_name EnemyStats extends Resource
@export var max_health: int = 30
@export var speed: float = 120.0
@export var loot_table: Array[ItemDrop] = []

Autoloads / singletons + EventBus

Register a script or scene as an autoload (Project → Project Settings → Globals/Autoload) to get

one always-present instance reachable by name from anywhere. Use it for cross-cutting state (save

game, audio, run config) — not as a dumping ground.

The EventBus pattern decouples unrelated systems: an autoload that owns only signals. Emitters

and listeners never reference each other, just the bus.

# event_bus.gd  (autoload named "Events")
extends Node
signal enemy_died(position: Vector2, xp: int)
signal score_changed(new_score: int)

# emitter                              # listener (anywhere)
Events.enemy_died.emit(global_position, 10)
Events.enemy_died.connect(_on_enemy_died)

Keep gameplay logic in nodes; let the bus carry the *notification*, not the behavior.

Node access & lifecycle

• _init() runs at construction (no tree, no @onready yet). _ready() runs once the node and

all children are in the tree — do node wiring here.

• @onready var x = $Path defers the assignment to _ready, so the child exists. Never grab

children in _init.

• Prefer unique names: mark a node Unique Name in Owner (%) and access %HealthBar

instead of the fragile, refactor-breaking get_node("../../UI/HealthBar"). $Foo is fine for a

direct child — get_node/$ on a missing path returns null and errors.

• Cache node lookups in @onready vars; don't call get_node every frame.
• Freeing: call queue_free() (safe, end of frame), not free() mid-signal. Guard reused refs

with is_instance_valid(node).

• Never busy-wait; await get_tree().create_timer(1.0).timeout or await a signal.

extends CharacterBody2D
@onready var sprite: Sprite2D = $Sprite2D
@onready var health_bar: ProgressBar = %HealthBar   # unique name, position-independent

func _ready() -> void:
    super()                       # chain the parent's _ready if the base defines one
    health_bar.value = 100

Signals

Signals are Godot's decoupling primitive. In Godot 4 you connect a Callable, not strings.

• Declare with typed params; name in the past tense for facts that happened

(health_depleted, item_collected), present-tense imperative only for requests.

• Connect: node.signal_name.connect(_on_thing) — a direct method reference, checked at parse

time. Add CONNECT_ONE_SHOT for auto-disconnect after one fire.

• Disconnect discipline: a connection to a node that gets freed is cleaned up automatically, but

connections you make to *long-lived* objects (autoloads, the bus) from a short-lived node must be

disconnected in _exit_tree(), or use CONNECT_ONE_SHOT, to avoid calls into freed instances.

signal health_depleted
signal health_changed(current: int, max: int)

func take_damage(amount: int) -> void:
    _health -= amount
    health_changed.emit(_health, _max_health)
    if _health <= 0:
        health_depleted.emit()

@export / @tool (inspector config)

@export exposes a variable in the Inspector so designers tune it without touching code. Use ranges,

groups, and typed exports so the inspector gives real widgets and validation.

@export var title: String = "Level 1"
@export_range(0.0, 1.0, 0.05) var volume := 0.8
@export_group("Movement")
@export var speed: float = 300.0
@export var jump_velocity: float = -400.0
@export var projectile: PackedScene           # drag a .tscn in the inspector
@export var stats: EnemyStats                 # a custom Resource slot

@tool at the top of a script runs it in the editor too — for gizmos, procedural previews, or

validating exported data. Guard runtime-only code with if Engine.is_editor_hint(): return.

Static (typed) GDScript

Type everything. Typed GDScript is faster (the VM skips dynamic dispatch) and catches errors at parse

time. Use := when the type is inferable, : Type when it isn't, and avoid Variant/untyped.

var speed: float = 300.0          # explicit
var dir := Vector2.ZERO           # inferred
var enemies: Array[Enemy] = []    # typed array

func distance_to(target: Node2D) -> float:
    return global_position.distance_to(target.global_position)

func _on_body_entered(body: Node) -> void:
    var enemy := body as Enemy     # safe cast → null if wrong type, no crash
    if enemy:
        enemy.take_damage(10)

Naming: snake_case vars/funcs/signals, PascalCase types/class_name/nodes, CONSTANT_CASE

consts, tabs for indent, lines < 100 cols. Cheat-sheet → references/gdscript-style.md.

_process vs _physics_process

• _physics_process(delta) — fixed tick (default 60 Hz), the same every step. All movement,

move_and_slide(), forces, and collision-dependent logic go here.

• _process(delta) — runs once per rendered frame (variable rate). Use for visuals, UI, and

non-physics polish.

• Always scale rate-based change by delta so behavior is framerate-independent. move_and_slide()

and move_and_collide() already fold in delta internally — do not multiply the velocity you

hand them by delta again.

Resources & data — .tres / .tscn are strict text formats

.tscn and .tres are line-oriented text with a strict header/section grammar. **Do not hand-edit

them past trivial value tweaks, and never launch on a file you hand-authored without validating** —

one bad ext_resource id, [node] line, or load_steps count corrupts the whole scene and Godot

refuses to open it. Prefer editing through the editor or building Resources in code and ResourceSaver.save().

• preload("res://x.tscn") resolves at parse/compile time — the dependency is baked in; use

for assets you always need.

• load("res://x.tscn") resolves at runtime — use for dynamic/optional paths (and to avoid

circular preloads). Both return a PackedScene; call .instantiate() to get a node.

2D / 3D bodies quickstart

The move-anything-controllable body is CharacterBody2D / CharacterBody3D. The Godot 4 flow is:

write the velocity property, then call move_and_slide() with no arguments.

extends CharacterBody2D
@export var speed: float = 300.0
@export var jump_velocity: float = -400.0

func _physics_process(delta: float) -> void:
    if not is_on_floor():
        velocity += get_gravity() * delta        # get_gravity(): project-configured vector
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = jump_velocity
    var dir := Input.get_axis("move_left", "move_right")
    velocity.x = dir * speed
    move_and_slide()                             # NO args in Godot 4 — reads the velocity property

3D is identical with CharacterBody3D, Vector3, and an X/Z input plane; body/area suffixes are

3D. Deeper body/physics tuning → gamedev-physics.

Language parity — GDScript ↔ C#

Same engine, same nodes; C# uses PascalCase members, partial classes, and attributes. Signals

become C# events (generated by source-gen). C# support requires the .NET (Mono) build of Godot.

# GDScript
extends Node
signal health_depleted
@export var speed: float = 300.0

func _ready() -> void:
    health_depleted.connect(_on_depleted)
    health_depleted.emit()

func _on_depleted() -> void:
    print("dead")

// C# — same node, .NET build
using Godot;

public partial class Player : Node
{
    [Signal] public delegate void HealthDepletedEventHandler();
    [Export] public float Speed { get; set; } = 300.0f;

    public override void _Ready()
    {
        base._Ready();                       // chain the parent (== super())
        HealthDepleted += OnDepleted;        // connect via the generated event
        EmitSignal(SignalName.HealthDepleted);
    }

    private void OnDepleted() => GD.Print("dead");
}

move_and_slide()→MoveAndSlide(), $Node→GetNode<T>("Node"), %Node→GetNode<T>("%Node"),

preload→GD.Load<T>(...). Full parity table → references/export-and-testing.md.

GDExtension / C++: for hot native code, build a godot-cpp GDExtension (.gdextension file,

GDREGISTER_CLASS, _bind_methods()) rather than a Godot module — no engine recompile, and it loads

like any other library. That is native-tooling territory → pair with cpp.

Export & testing

• Test with GUT 9.x (GDScript, extends GutTest) or gdUnit4 (GDScript + C#). Put tests

under test/ or res://tests/; assert behavior, not private state.

• Run headless in CI: godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://test -gexit

(GUT). Export via templates: godot --headless --export-release "Linux/X11" build/game.x86_64.

• Validate a project before shipping: open in the editor once (catches broken .tscn/.tres),

then export-check per platform. Details → references/export-and-testing.md.

Hand off to

Mechanics, loops, and feel *before* you script them → game-design.

.gdshader / visual shaders → gamedev-shaders. Joints, RigidBody

tuning, deep collision layers → gamedev-physics. NavigationAgent,

A*, steering → gamedev-pathing. MultiplayerSynchronizer/RPC/netcode

→ gamedev-multiplayer. Store builds, signing, platform export at

scale → gamedev-shipping. The GDExtension / godot-cpp native side

and its CMake/build tooling → cpp.