godot

Build Godot 4 scenes and GDScript workflows, inspect physics behavior, and configure headless project exports.

SKILL.md

GitHub

Godot Engine 4.x Game Development AI Skill Guide (Claude)

Overview & Engine Architecture

Godot 4.3+ / 4.4 (pin in project.godot config/features) uses SceneTree, GDScript 2.0, optional C# .NET, renderers Forward+, Mobile, Compatibility (GL). Claude acts as Principal Game Developer: headless export CI, GUT tests, deterministic simulation, Dedicated server builds.

┌─────────────────────────────────────────────────────────────┐
│  godot --headless --export-release "Preset" out.exe         │
│  godot --headless -s addons/gut/gut_cmdln.gd -gexit           │
│  Physics: _physics_process; ProjectSettings physics FPS       │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when: 2D/3D indie pipelines, tool-first games, lightweight server builds, scripted batch export.

Do not use when: AAA Nanite-scale content; console cert without export platform docs.


Operational Capabilities & Agent Directives

  1. Static typing: GDScript @export, typed arrays, class_name — avoid cyclic class_name deps.
  2. Determinism: Fixed Engine.time_scale in tests; seed RandomNumberGenerator with seed=hash; disable physics jitter tests unless Physics Interpolation configured consistently.
  3. Headless CI: --headless --display-driver headless (platform-dependent); export requires export templates installed matching editor version.
  4. Export presets: export_presets.cfg names are case-sensitive in CLI; run godot --headless --export-release "Windows Desktop" path.exe.
  5. Web: COOP/COEP for threads; or single-threaded export preset — blank page otherwise.
  6. Color/render: Forward+ vs Compatibility changes lighting; golden screenshots only on pinned renderer + same GPU driver class.

Headless export + test

godot --headless --path . --export-release "Windows Desktop" "build/game.exe"
godot --headless --path . -s addons/gut/gut_cmdln.gd -gdir=res://test -gexit

Dedicated server example: project main scene server-only; -- --port=7777 after -- passes user args to OS.get_cmdline_args().


Failure taxonomy

Symptom Cause Fix
Export failed: templates Missing export templates Install via Editor
Blank WebGL Missing COOP/COEP Headers or single-thread
Camera stutter _process vs _physics_process Move camera to physics tick
class_name cycle Circular typing Decouple interfaces
Vulkan crash Old GPU Compatibility renderer

Agent Operational Directive

MANDATORY: Pin Godot version + export templates. Use --headless in CI. Seed RNG for reproducible tests. Match renderer preset across dev and CI golden captures.