godot
Build Godot 4 scenes and GDScript workflows, inspect physics behavior, and configure headless project exports.
SKILL.mdskills/godot/SKILL.md
GitHubGodot 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
- Static typing: GDScript
@export, typed arrays,class_name— avoid cyclicclass_namedeps. - Determinism: Fixed
Engine.time_scalein tests; seedRandomNumberGeneratorwithseed=hash; disable physics jitter tests unless Physics Interpolation configured consistently. - Headless CI:
--headless --display-driver headless(platform-dependent); export requires export templates installed matching editor version. - Export presets:
export_presets.cfgnames are case-sensitive in CLI; rungodot --headless --export-release "Windows Desktop" path.exe. - Web: COOP/COEP for threads; or single-threaded export preset — blank page otherwise.
- 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
--headlessin CI. Seed RNG for reproducible tests. Match renderer preset across dev and CI golden captures.