| name | gamedev-godot |
| description | Creates Godot games from empty project to exported build. Use when starting, building, validating, or shipping a Godot 2D/3D game or app. |
| compatibility | Portable core. Works on Claude Code and Codex. Godot engine facts drift between minor versions; verify volatile numbers and renamed APIs against current primary sources. |
| version | 1.1 |
| last_validated | 2026-07-11T00:00:00.000Z |
Godot Game Creation
Use this skill to take a Godot project from empty editor to a published, exported build using the engine, language, and tooling reality of Godot 4.7 (stable, released 2026-06-18; current as of July 2026). It covers the durable build spine (prototype → first playable → content → export) and fences the volatile engine layer (renderer names, minor-version API renames, physics-engine defaults, C# and web-export caveats) so you teach what is true today, not what was true in Godot 3.
Version note (verify): 4.7 is current stable (released 2026-06-18), on an active patch cycle — 4.7.1 was at RC2 as of 2026-07-11, still not stable, fixing real regressions in the 4.7.0 release (editor freezes, a Jolt temp-buffer crash, Android virtual-keyboard bugs) — pin the exact patch level in CI, not just the minor, and re-check whether 4.7.1 has shipped stable before you start a new project. 4.6 (2026-01-26) made Jolt the default 3D physics engine — a behavior-changing default when opening a pre-4.6 3D project. 4.7 replaced the old Asset Library with a new Asset Store (in-editor, threaded browsing, reviews/ratings) — old Asset Library deep links from before 4.6 no longer resolve; point contributors at the new store. Godot 5.0 has not shipped and has no announced date.
This is a software/game-development domain skill. It is self-contained: pick the stage you are in, load the one reference for that stage, do the work, verify volatile claims before quoting them.
Quick Reference
| Stage | Read or Run | Durable default (Godot 4.x, mid-2026) |
|---|
| Setup & project | references/setup-and-project.md | One editor install per project via a version manager; commit project.godot + source, gitignore .godot/; pick GDScript unless you have a concrete reason for C# (heavier export, no web export for C# without extra setup — verify) |
| Language & architecture | references/gdscript-and-architecture.md | class_name + @export + static typing (var x: int); signals up, calls down; autoload singletons for cross-scene state; _physics_process for gameplay, _process for visuals |
| Build the game | references/scenes-and-nodes.md | Compose with scenes as reusable prefabs; keep the node tree shallow; instance scenes, don't deep-nest; CharacterBody2D/3D + move_and_slide(); TileMapLayer for 2D grids (the monolithic TileMap is deprecated since 4.3 — use the editor's one-click migration); Jolt is the default 3D physics engine since 4.6 |
| Performance & traps | references/performance-and-traps.md | Cache get_node results; free with queue_free(); use object pools for bullets/particles; profile with the built-in profiler + --verbose; avoid per-frame allocations in _process |
| Rendering & platforms | references/rendering-and-export.md | Pick the renderer per target (Forward+ desktop, Mobile for phones, Compatibility for web/old GPUs); export needs matching export templates; test on-device, not just the editor |
| Ship & polish | references/rendering-and-export.md#shipping | Export presets per platform; strip debug; sign/notarize per store rules (verify per platform); one-button build via in CI |
Game Creation Workflow
The durable spine. Each step names its verification check inline — do not advance from a state you cannot describe back.
- Scope to a testable first playable → verify: one sentence — "a player controls something, can perform the core verb, and has a reason to keep playing." If you can't write it, stop and get it.
- Set up the project and repo → verify:
project.godot opens in a pinned editor version; .godot/ is gitignored; a trivial scene runs with F5. See references/setup-and-project.md.
- Prototype the core verb in one scene — placeholder art,
CharacterBody2D/3D, input map → verify: the core verb works with keyboard/gamepad and reads clearly at real speed. See references/scenes-and-nodes.md.
- Stand up the architecture skeleton — autoload for global state, signal wiring (signals up, calls down), a scene-per-concept layout → verify: two scenes communicate via signals/autoload without either holding a hard
get_node("../../..") path to the other. See references/gdscript-and-architecture.md.
- Reach First Playable — the core loop is completable end to end; scene transitions work; pause works → verify: someone else finishes the loop without you explaining the controls.
- Content pass — real art/audio, reusable scene prefabs replace placeholders,
TileMapLayer/GridMap for levels, particles and shaders for feel → verify: frame time stays inside budget on a real target device, not just the editor. See references/scenes-and-nodes.md and references/performance-and-traps.md.
- Harden — pool spawned objects, free every instanced node, disconnect one-shot signals, validate saved data on load → verify: walk
references/performance-and-traps.md Known Traps as a checklist; profiler shows no runaway per-frame allocation or leaked nodes.
- Export and ship — set the renderer per target, install matching export templates, configure export presets, strip debug, sign per platform → verify: an exported release build launches and plays on-device; a headless CI export produces the same artifact. See
references/rendering-and-export.md.
Verify every volatile fact (renderer names, minor-version API renames, physics-engine defaults, C# export support, web-export threading requirements, store signing rules) against current primary sources before quoting it. Godot changes these across minor releases. Each reference labels volatile facts as of Godot 4.7, July 2026 — verify.
ASCII Flow
Scope -> "first playable" sentence
-> Project + repo (pinned editor, gitignore .godot/)
-> Prototype core verb in one scene (CharacterBody + input map)
-> Architecture skeleton (autoload state + signals up / calls down)
-> FIRST PLAYABLE (someone else finishes the loop)
-> Content (scene prefabs, TileMapLayer/GridMap, shaders, audio)
-> Harden (pool, queue_free, disconnect signals, validate saves)
-> Export (renderer per target -> export templates -> presets -> sign)
Patterns (durable)
- Scenes are the unit of reuse. A scene is a prefab: build a thing once (enemy, pickup, UI panel), save it as a
.tscn, and instance it. Composition over deep inheritance.
- Signals up, method calls down. A parent calls methods on its children; a child emits a signal the parent connects to. This keeps children reusable and prevents fragile
get_node("../../..") coupling.
- Autoloads for genuinely global state only. Singletons (game state, audio manager, scene switcher) via Project Settings → Autoload. Do not turn every manager into a global.
_physics_process for gameplay, _process for visuals. Physics/movement/collision logic runs at a fixed timestep in _physics_process(delta); camera smoothing and cosmetic updates run in _process(delta). Multiply by delta.move_and_slide() on CharacterBody. Set velocity, call move_and_slide(); let the engine resolve collisions. Don't hand-roll integration unless you have a reason.- Static typing everywhere.
var speed: float = 200.0, typed @export, typed function signatures. Enables editor autocomplete, catches errors, and lets the compiler optimize.
- Signals earn their cost — don't emit in hot loops. Use signals for state-change events (
died, picked_up); use a direct method call or get_tree().call_group() for per-frame / per-instance communication (200 collision checks/frame is not a signal's job).
- Model pure data as a custom
Resource, not a Node or Dictionary. class_name ItemData extends Resource with typed @exports — inspector-editable, shareable, no scene-tree overhead. The veteran's default for item/ability/stat data.
- Drop below Nodes when count is the bottleneck. Nodes wrap the servers; past a few thousand identical instances use
MultiMeshInstance2D/3D / RenderingServer (visuals) or PhysicsServer (bulk queries) — but only when the profiler says so.
queue_free(), never free() mid-frame. Defer node destruction to the end of the frame so you don't invalidate iterators or signals in flight.
Anti-Patterns
- Hard-coding node paths across scene boundaries (
get_node("../../Player")) instead of signals, exported node references, or an autoload — the top cause of scenes that break when moved.
- Running movement, collision, or timers in
_process instead of _physics_process — behavior then varies with frame rate.
- Forgetting
* delta on per-frame movement, so speed scales with the player's monitor refresh rate.
- Calling
free() on a node during signal handling or iteration instead of queue_free() — use-after-free crashes.
- Instancing objects every frame (bullets, particles, damage numbers) without pooling — GC/allocation spikes and frame stutter.
- Never disconnecting one-shot or per-instance signal connections — silent leaks as the leftover connection keeps a freed context referenced.
- Assuming C# and GDScript have identical export support — as of Godot 4.7 (July 2026) C# has no web/WASM export in stable (a prototype was demoed but not shipped). For any web target, use GDScript. Re-verify, but do not promise a C# web build.
- Shipping without matching export templates installed for the editor version → export fails or produces a broken binary.
- Shipping
CSGShape geometry as final level meshes — CSG is documented as prototyping-only; bake to static meshes before release.
- Quoting a renderer name, API signature, physics default, or export caveat from Godot 3 or an older 4.x minor without re-verifying — several were renamed or re-defaulted across 4.x (e.g. Jolt became the default 3D physics engine in 4.6).
Known Traps
- Frame-rate-dependent logic — anything in
_process that moves or times gameplay drifts across machines; use _physics_process and always multiply by delta.
TileMap → TileMapLayer migration — the monolithic TileMap node was deprecated in 4.3 (present but frozen — no new features) in favor of per-layer TileMapLayer nodes; code and scenes from older tutorials will not match. Use the editor's one-click conversion tool rather than hand-porting.- Jolt-as-default silent change — since 4.6 new 3D projects use Jolt physics by default; a pre-4.6 project upgraded in place can behave differently with no code change. Re-test physics after an upgrade, or pin the engine explicitly.
@onready ordering — @onready var x = $Child resolves when the node enters the tree (after _init(), before _ready()); referencing it in _init() returns null.- C# / web export — as of 4.7 (July 2026) C# web export is not supported in stable; do not promise a web build for a C# game. Re-verify per release, but treat GDScript as the web path.
- Export templates version-lock — templates must match the exact editor version including patch level (4.7 is on an active patch cycle); a mismatch fails silently or ships a broken build. Pin the exact patch in CI and reinstall templates on every upgrade.
- Shader compilation stutter — Godot compiles shader variants lazily on first use, so effects hitch the first time they appear (worst on Android). Pre-warm materials on a loading screen (hidden
SubViewport), persist the shader cache, and test on the real target where the editor's pre-cache doesn't hide it. See references/rendering-and-shaders.md.
.res/ResourceSaver save-file RCE — loading a user-modifiable .tres/.res can execute arbitrary GDScript via resource deserialization. Use FileAccess + JSON (or ConfigFile) for save data, never ResourceSaver for user-shared files. See references/rendering-and-export.md.- Editor ≠ device — the editor runs on your desktop GPU with the editor renderer, often with shaders pre-cached; a phone or web target has different capabilities. Test an actual exported build on the real target before shipping.
Frameworks & tooling (Godot 4.7, July 2026 status — verify before adopting)
| Need | Pick | Status |
|---|
| Primary language | GDScript (typed) | First-class, fastest iteration, full web export; typed Dictionaries (Dictionary[K,V]) since 4.4 |
| Performance-critical / .NET ecosystem | C# (.NET) | First-class but heavier; no web export in stable as of 4.7 — GDScript for web targets |
| Native performance modules | GDExtension (C/C++/Rust via godot-cpp / gdext) | Stable ABI for compiled extensions; verify binding maturity |
| 3D physics | Jolt (built-in) | Default for new 3D projects since 4.6; Godot Physics still selectable |
| 2D tilemaps | TileMapLayer (per-layer) | Current node; the monolithic TileMap is deprecated since 4.3 |
| Dependency/asset sharing | Asset Store (renamed from Asset Library in 4.7) + git submodules | In-editor store with reviews/versioning; vet third-party addons for version fit |
| Console export | Third-party middleware only (e.g. W4 Games) | Godot has no official console export — MIT/open-source licensing conflicts with console NDAs; budget for a middleware partner and its own cert timeline if a console SKU is planned |
| CI export | godot --headless --export-release | Scriptable headless export; needs version-matched templates on the runner |
When Godot Is the Wrong Choice
Recommending Godot by default is itself a judgment call, not a rule — push back when the project profile doesn't fit:
- A console SKU is the primary target, not a stretch goal. Godot has no official console export (open-source licensing conflicts with console NDAs); you're committing to a third-party middleware vendor (e.g. W4 Games) as a second dependency with its own pricing, support SLA, and version lag behind Godot's own releases. If PS5/Xbox/Switch is launch-day, weigh that against Unity's or Unreal's direct console pipelines before committing.
- The team already has deep Unity or Unreal expertise and no Godot experience, and the timeline doesn't afford a learning-curve tax — re-platforming mid-project is expensive; the switching cost usually isn't worth it for its own sake.
- AAA-fidelity 3D rendering is the product (film-quality GI, Nanite-style virtualized geometry, large open-world streaming). Godot's renderer is credible for stylized and mid-scope 3D, but it doesn't have Unreal's Lumen/Nanite-class pipeline; don't promise that fidelity on Godot.
- The genre leans on a mature, licensed middleware ecosystem (large-scale multiplayer backends, advanced physics/destruction, certain anti-cheat or ad-mediation SDKs) that ships Unity/Unreal plugins first and Godot support late or not at all — check the specific vendor before assuming parity.
- The team needs a large in-house animation/rigging pipeline matching Unity's Mecanim or Unreal's Control Rig maturity — Godot's
AnimationTree/AnimationPlayer cover most 2D/indie-3D needs but are thinner for complex character-animation production pipelines.
- Godot remains a strong default for 2D, stylized/mid-scope 3D, rapid prototyping, jam games, and teams that value an open-source, royalty-free engine with fast iteration — the above are reasons to check fit, not a blanket "avoid Godot."
Navigation
Resources:
- references/setup-and-project.md — Editor versioning, project structure, repo hygiene, input maps, and GDScript-vs-C# choice
- references/gdscript-and-architecture.md — Typed GDScript, signals (and when direct calls /
call_group beat them), autoloads, _process vs _physics_process, custom Resource data modeling, @tool, _notification lifecycle, and node-communication patterns
- references/scenes-and-nodes.md — Scene composition vs inheritance, node tree design,
CharacterBody, Jolt physics default, TileMapLayer/GridMap, and instancing
- references/performance-and-traps.md — CPU/GPU profiling, the drop-below-Nodes escape hatch (
MultiMesh/servers), object pooling, node/signal lifecycle, and the full Known Traps catalog with fixes
- references/rendering-and-shaders.md — Shader compilation stutter and mitigation, lighting/GI strategy (LightmapGI/SDFGI/VoxelGI),
WorldEnvironment, and SubViewport techniques
- references/rendering-and-export.md — Renderer choice, export templates and gotchas, save systems (and the
.res security trap), high-level multiplayer, per-platform presets, and shipping/signing
- data/sources.json — Primary sources to verify volatile facts against
Related skills (same family only):
Learnings Loop
Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).
After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.
Fact-Checking
- Godot 4.x engine facts drift between minor versions. Treat renderer names, node renames (e.g.
TileMap → TileMapLayer), API signatures, C# export support, and web-export requirements as volatile and verify against current primary sources (docs.godotengine.org, godotengine.org/blog, the GitHub release notes) before quoting.
- The references separate DURABLE principles (scene composition, signals up / calls down, physics-vs-process, typed GDScript) from VOLATILE facts (renderer names, renamed nodes, export caveats) and date the volatile ones
as of mid-2026.
- Features announced on the roadmap but not confirmed shipped (verify against the milestone) are marked as such — confirm shipping status before depending on them.
- If web access is unavailable, state the limitation and mark any volatile engine claim as unverified rather than asserting it as current.
