game-godot
Skill26 starsChanged yesterdayMITView on GitHub
Covers building a game client in Godot 4 for this pack: when Godot fits, GDScript or C#, editing text scenes and running headless imports, scripts, tests and exports from the command line, Godot 3 habits that break in Godot 4, what to commit, community MCP servers, and connecting to the Bun game server over WebSocketPeer with Better Auth, saves and translations. Use when a game's client, editor tooling or export pipeline is in Godot, when GDScript or .tscn files written from an older Godot fail, or when a Godot build must talk to the pack's authoritative server.
In this repository46 other files it gives its agents.
- asaasSkill
- betterauth-integrationSkill
- bullmq-game-queuesSkill
- character-design-narrativeSkill
- ci-cd-gameSkill
- claude-agent-sdkSkill
- database-performance-tuningSkill
- elevenlabs-sound-musicSkill
- foundry-vtt-devSkill
- game-anti-cheatSkill
- game-backend-architectureSkill
- game-blenderSkill
- game-clientSkill
- game-design-fundamentalsSkill
- game-architectSkill
- game-balanceSkill
- game-buildSkill
- game-expandSkill
- game-loreSkill
- game-questSkill
- game-reviewSkill
- game-devSkill
- game-economy-designSkill
- game-localizationSkill
- gameplay-analyticsSkill
- game-save-loadSkill
- game-state-syncSkill
- game-unitySkill
- judgeSkill
- level-designSkill
- matchmaking-systemSkill
- mmo-designSkill
- monitoring-game-opsSkill
- nuvemshop-sdkSkill
- openclaw-genieSkill
- postgres-game-schemaSkill
- procedural-genSkill
- quest-mission-designSkill
- quest-narrative-coherenceSkill
- react-animationsSkill
- redis-game-patternsSkill
- skill-progression-treesSkill
- story-structure-gameSkill
- stripe-game-paymentsSkill
- ui-ux-gameSkill
- worldbuildingSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 64
Commit *.uid files (4.4 and later).
- Very specific: line 69
Keep third-party add-ons in a top-level addons/ folder.
- Distinctive: line 75
Every step above has an official command-line flag, so an agent needs no MCP server to build, test and export.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot
Godot is the client. The server stays TypeScript on Bun (game-backend-architecture) and owns the game state; the Godot build sends intents and draws what the server says. This skill covers the Godot side and the seams to the rest of the pack.
Version checked
- Checked against Godot 4.7.2-stable (published 2026-08-18) on 2026-11-14. The documentation's "stable" branch is 4.7. 4.8 is in beta (4.8-beta3, 2026-11-09): re-check the traps file when 4.8 ships.
- Godot 3 is still maintained (3.6.3-stable, 2026-08-22). Find out which major a project uses before writing code: a Godot 4 project has
format=3in its.tscnheaders, Godot 3 usesformat=2. - An assistant trained on Godot 3 writes code that no longer parses.
references/gdscript-traps.mdlists the breaks from 3 to 4 and from 4.4 to 4.7.
When Godot fits
- Free and open source (MIT), 2D and 3D. The editor and exports run on Windows, macOS and Linux; Android editor support is experimental; iOS runs exported projects. For consoles, see https://godotengine.org/consoles/.
- Pick Godot over the browser stacks of
game-clientwhen the game needs an editor for scenes, tile maps and animation, or ships native desktop and mobile builds as well as the web. - Limits that decide against it, or decide the language:
- Web exports target WebGL 2 through the Compatibility renderer only. Forward+ and Mobile do not run on the web, and Godot has no WebGPU backend.
- On the web, only HTTP, WebSocket (client) and WebRTC work. Raw TCP and UDP do not.
- A browser client in Godot 4 must be GDScript (next section).
- Godot's high-level multiplayer API (
@rpc,MultiplayerPeer,WebSocketMultiplayerPeer) is built on the SceneTree for Godot peers. Godot's networking page names a custom backend server as the case where low-level work cannot be avoided. Against the pack's Bun server, use a plainWebSocketPeerand the pack's JSON messages; no Godot page documents the high-level API against a non-Godot server (this skill's rule).
GDScript or C#
| Need | Language |
| Any web export | GDScript. Godot 4 C# projects cannot export to the web |
| Desktop only, team already writes C# | C# is fine |
| Android or iOS | GDScript is the safe choice. C# on mobile is experimental since 4.2 |
C# needs the .NET-enabled editor build plus a separately installed .NET SDK: .NET 8 or later, and .NET 9 or later to export to Android. Build C# from the command line with --build-solutions. GDScript needs nothing beyond the editor binary.
Working without the editor
An agent can do most work through files and the command line. references/project-and-cli.md has the flags, the scene format and the CI recipe. The short version:
- Project: a folder with
project.godot. Paths inside the game useres://(the project) anduser://(writable player data, where saves go). - Scenes and resources (
.tscn,.tres) are text. Godot 4 writesformat=3; dropload_steps, which is deprecated and only appears in files saved before 4.6. The editor discards comments and properties equal to their defaults when it saves, so do not use comments as documentation inside a scene. - Scripts are plain
.gdfiles.godot --headless --path . --script res://tools/x.gd --check-onlyparses one script and quits. - Import first:
godot --headless --path . --importimports resources and quits. Run it on a fresh clone before scripts, tests or exports, because.godot/(the import cache) is not committed (this skill's rule, from those two facts). - Run headless:
--headlessis required on machines without a GPU, such as CI. A script run with--scriptmust extendSceneTreeorMainLoop.--quit-after <n>stops after n iterations for a smoke run. - Export:
godot --headless --path . --export-release "<preset>" builds/game.exe. The binary must be the editor, not an export template; export templates for that exact editor version must be installed; the preset name must matchexport_presets.cfg; the target directory must exist. - Tests: Godot ships no game test framework.
--testruns the engine's own C++ tests and needs an engine compiled withtests=yes. Use GUT or gdUnit4 (references/project-and-cli.md). - Language server: the editor serves the GDScript language server and debug adapter on the ports given by
--lsp-portand--dap-port.
Godot 3 code that breaks
The traps an older model hits most. The full list, with 4.4 to 4.7 changes, is in references/gdscript-traps.md.
export,onready,toolare annotations:@export,@onready,@tool.yieldis gone; useawaiton a signal or coroutine.- Connect signals through the
Signalobject:button.pressed.connect(_on_pressed), not a string name. _ready()and_process()no longer call the parent's version; callsuper()first in the override.- Renames:
SpatialisNode3D,KinematicBodyisCharacterBody3D,SpriteisSprite2D,FileandDirectoryareFileAccessandDirAccess. The Tween node is gone; use Tweeners. TileMapis deprecated; use oneTileMapLayernode per layer.randomize()now runs on project load. A deterministic run needs an explicit seed.
Project hygiene
- Commit
*.uidfiles (4.4 and later). Godot's UID article says they must not go in.gitignore; without them, references break on a fresh clone. When a script or shader moves outside the editor, move its.uidbeside it. - Ignore
.godot/(cache) and*.translation(binary files imported from CSV). - Generate
.gitignoreand.gitattributesfrom the project manager's Git option, or Project > Version Control > Generate Version Control Metadata. export_presets.cfgholds no credentials from 4.1 on, so it can be committed; Godot 3 and 4.0 could store credentials there.- Name files and folders in snake_case (C# scripts excepted, which are PascalCase), node names in PascalCase. Mixed-case file names can break after a Windows export.
- Keep third-party add-ons in a top-level
addons/folder.
Agent tooling
- Official: none. The Godot project publishes no MCP server, agent skill or
llms.txt(all threellms.txtURLs return 404). The proposal for a built-in AI assistant (godot-proposals #12409) was closed as not planned on 2025-08-23, with users encouraged to write third-party add-ons. The 2026 contribution policy requires human-authored code in engine pull requests; it says nothing about making games with AI. - Community MCP servers exist, from file-and-CLI servers that need no editor to live-editor bridges with dozens of tools. Most of the live ones can run arbitrary GDScript in the editor or the running game. The user installs them; this pack ships no MCP config. Publisher, licence, stars, what must be running and the warning for each are in
references/agent-tooling.md. - Every step above has an official command-line flag, so an agent needs no MCP server to build, test and export.
Connect to the pack
- Server and transport:
WebSocketPeer, polled every frame, sending the pack's JSON messages withsend_text(). Readreferences/networking.mdbefore writing the client: the loop, buffer sizes, and the handshake findings below. - Origin: Godot 4.7.2's native WebSocket client sends no
Originheader; a browser export sends the page's origin. A non-browser client can set anyOriginit likes (RFC 6455), so anOriginset by a native client proves nothing: security there rests on the bearer token.game-backend-architectureaccepts an upgrade with noOriginwhen it carriesAuthorization: Bearerand the session check passes; an untrustedOriginis still refused. Native builds do not fake anOrigin. - Authentication (
betterauth-integrationreads the session from the upgrade's headers and cookies):- Web export:
handshake_headersis not supported, so noAuthorizationheader. Serve the game page from the same site as the auth server, sign in on the hosting page (not inside Godot), and the browser sends the session cookie with the handshake; this works with the pack's server as it is. - Web export from another site (a store or portal): the cookie does not come along. Better Auth's one-time-token plugin is a documented cross-domain mechanism (single-use, 3-minute default expiry); putting it in the WebSocket URL is this skill's inference. It needs a server change, was not run for this skill, and how the export obtains a session on a portal is not covered by any page opened.
- Native: send
Authorization: Bearer <token>throughhandshake_headerswith Better Auth's bearer plugin, and noOrigin. Keep the token in memory, and if it must survive a restart, in the platform's secure store (a plainuser://file is weaker); never inres://, a URL or a log (this skill's rule). - Details, sources and the server changes each option needs are in
references/networking.md.
- Web export:
- State sync:
game-state-sync's boilerplate is TypeScript, so a GDScript client reimplements prediction and the snapshot bracket. Predicted ticks run on a fixed step, remote entities interpolate in_process. Godot's physics interpolation smooths physics ticks only and does not replace the snapshot buffer. - Saves:
game-save-loadowns the format, versioning and where saves live. In Godot, write touser://; never callget_var(true)orbytes_to_var_with_objectson data from outside the build. Readreferences/saves-and-data.md. - Translations: Godot translates with
tr("KEY"),tr_n()for plurals and a context argument for ambiguous words, from CSV or gettext PO files. Keepgame-localization's rules (stable IDs, whole messages, translator comments) and use the same IDs as Godot message keys. Godot's docs say PO files work better with Git than CSV. - Anti-cheat:
game-anti-cheatapplies unchanged. A Godot build, native or web, is under the player's control. Godot's own multiplayer page says to treat all client input as untrusted. - Input: define actions in the InputMap and read gameplay input in
_unhandled_input, so GUI controls get events first. 4.7 changed mouse and keyboard device IDs (traps file).
Pitfalls
- Exporting a C# project to the web: Godot 4 cannot.
connect_to_url()returnsOKbefore the socket connects. Nothing moves until you callpoll()each frame.- Expecting
handshake_headersorheartbeat_intervalto work in a web export: neither does. - A native build that fakes a trusted
Origininstead of sending the bearer token: theOriginproves nothing, and without the token the upgrade fails. - Large snapshots with the default 65535-byte
WebSocketPeerbuffers: raiseinbound_buffer_sizebefore connecting (this skill's rule). - Treating JSON numbers as ints: Godot parses every JSON number as a float.
get_var(true)on a downloaded save: deserialized objects can run code..uidfiles missing from Git, or left behind when files move outside the editor.- Code with
yield, string signal connections,Spatial,TileMapor a missingsuper(): Godot 3 habits. - Exporting with an export template binary, or without templates matching the editor version.
- Running scripts or tests on a fresh clone before
--import. - Freeing nodes in a
@toolscript: it runs in the editor and can crash it. - Setting physics ticks to the server's 20 Hz: Godot warns that physics can break down below about 30.
- A community MCP server's
game_eval,godot_execorexecute_editor_script: they run arbitrary GDScript.
Files
references/project-and-cli.md: read when creating a project, editing.tscnor.tresby hand, running headless imports, scripts, tests or exports, or setting up CI.references/gdscript-traps.md: read when writing or fixing GDScript, or porting code written for Godot 3 or an older 4.x.references/networking.md: read when connecting a Godot client to the Bun server: the WebSocketPeer loop, the Origin and authentication options per platform, and where interpolation runs.references/saves-and-data.md: read when saving player data, parsing JSON from the server, or loading files a player could have touched.references/agent-tooling.md: read when a user asks for a Godot MCP server or skill set, or before installing one.references/sources.md: read when you need the page behind a rule or want to re-check the version.
Related skills
game-backend-architecture: the authoritative Bun server, rooms, message protocol and upgrade check this client connects to.betterauth-integration: the session check on the WebSocket upgrade.game-state-sync: prediction, reconciliation and snapshot interpolation to reimplement in GDScript.game-client: the browser alternative in TypeScript.game-save-load: save format, migrations and where saves live.game-localization: string IDs, plurals and the translation process.game-anti-cheat: server-side validation; the Godot build is untrusted.ci-cd-game: the pipeline that runs the headless import, tests and export.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

