Gamedev Godot

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

Game Creation Workflow

The durable spine. Each step names its verification check inline — do not advance from a state you cannot describe back.

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
• Pick the renderer for the target, not the prettiest one. Forward+ is desktop-first; Mobile trades features for phone GPUs; Compatibility (GLES-lineage) is the safe path for web and old hardware.

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.
• .godot/ in git — committing the generated .godot/ cache causes churn and merge pain; gitignore it and commit only project.godot + source + assets.

Frameworks & tooling (Godot 4.7, July 2026 status — verify before adopting)

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):

• ../software-mobile/SKILL.md — Mobile-platform constraints and store flows
• ../software-performance/SKILL.md — General performance profiling discipline
• ../software-ui-ux-design/SKILL.md — Onboarding and flow design that transfers to game UX
• ../gamedev-roblox/SKILL.md — Sibling game-creation skill for the Roblox platform

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.