Godot Engineering Suite

Use this skill as a router, not as a monolithic handbook. Read only the references needed for the current task.

Non-negotiable rules

1. Detect the project's Godot version, language, renderer, target platforms, addons, and existing conventions before proposing architecture or API changes.
2. Treat repository instructions and existing project patterns as authoritative unless they are demonstrably broken.
3. Do not require an MCP server. Prefer normal file tools and the matching Godot CLI. Use an existing MCP integration only when the repository already trusts it and the user asked for or approved it.
4. Do not grant yourself tools, install packages, access the network, launch a GUI, or run untrusted project code merely because this skill is active.
5. Never edit generated import state under .godot/, imported artifacts, binary .scn or .res files, or third-party addon code unless the task explicitly requires it.
6. Keep changes narrow. Preserve scene ownership, UIDs, resource references, node paths, signal contracts, input actions, and serialized property types.
7. Verify with the smallest useful check first. Use the exact engine branch expected by the project.
8. Do not hide broken invariants behind blanket null checks, deferred calls, object pools, autoloads, or speculative abstractions.

Start every task

1. Locate project.godot and the repository root.
2. Read applicable AGENTS.md, CLAUDE.md, GODOT_PROJECT.md, README, and nearby implementation files.
3. Read project discovery.
4. Read change workflow before editing scenes, resources, project settings, addons, exports, or native code.
5. If an API, node, property, CLI flag, or compatibility detail is uncertain, read official docs and versioning and verify against documentation for the detected minor version.
6. Load the smallest relevant set of topic files below. Usually two to four references are enough.

The optional read-only command python scripts/inspect_godot_project.py --root . produces a compact project profile. Do not run it when execution is unavailable or disallowed; inspect the same facts manually instead.

Routing map

Project structure and core engine model

• Architectural boundaries, autoloads, composition, dependency direction: architecture and boundaries
• Scene ownership, node lifecycle, node references, instancing: scenes, nodes, and ownership
• Custom resources, configuration, data-driven systems: resources and data models
• Text scenes, UIDs, subresources, merge-safe edits: serialization and text scenes
• Signals, event buses, state machines, game state: signals, events, and state
• Loading screens, background loading, world chunks: scene loading and streaming

Languages and native integration

• .gd, typing, lifecycle methods, coroutines, style: GDScript
• Godot .NET projects and C# integration: C#
• Native libraries and extension APIs: GDExtension and native code
• Engine modules, source builds, custom export templates: engine modules and custom builds

Gameplay systems

• Action maps, keyboard, mouse, touch, gamepads, rebinding: input and device support
• Sprites, TileMapLayer, 2D transforms and cameras: 2D
• Meshes, transforms, environments and 3D scene composition: 3D
• Cameras, viewports, scaling, split-screen, render targets: camera, viewport, and resolution
• Bodies, areas, layers, masks, fixed-step simulation: physics
• Pathfinding, avoidance, behavior and agents: navigation and AI
• AnimationPlayer, AnimationTree, skeletons, state transitions: animation
• Audio buses, playback, spatial sound, transitions: audio
• Procedural worlds and reproducible generation: procedural generation
• Replays, lockstep assumptions, deterministic state: determinism, replays, and lockstep

UI and presentation

• Control layout, containers, anchors, themes, reusable components: UI layout and themes
• Focus, gamepad navigation, text scaling, accessibility: UI input and accessibility
• Renderers, lighting, shadows, GI, post-processing: rendering and lighting
• CanvasItem and spatial shaders, compute, particles, VFX: shaders and VFX
• Localization resources, locale changes, formatting and RTL: localization and internationalization

Content, persistence, online systems

• Source assets, import options, reimport safety, 3D pipelines: asset import and content pipeline
• Saves, settings, migrations, atomic writes and user://: save/load and persistence
• RPCs, authority, replication, dedicated servers and validation: networking and multiplayer
• WorkerThreadPool, threads, synchronization and main-thread boundaries: threading and background work

Quality and maintenance

• Test seams, unit/integration/scene tests and headless checks: testing
• Parser errors, runtime failures, crashes and diagnostic workflow: debugging
• Profiler-driven CPU, GPU, memory and loading optimization: performance and profiling
• Review checklist for scripts, scenes, resources, exports and security: code review
• Godot minor upgrades, deprecated APIs and conversion: migration and upgrades
• Project profile and durable documentation: documentation and project profile

Tooling, delivery and platforms

• @tool, EditorPlugin, inspectors, import plugins and editor safety: editor tools and tool scripts
• Third-party addons, vendoring, update policy and licenses: addons and dependencies
• Agent permissions, MCP scope, editor execution and automation: agent and MCP safety
• Filesystem, network, mods, native code and untrusted input: security and untrusted content
• Export presets, templates, reproducible artifacts, signing: export, release, and signing
• Windows, macOS and Linux behavior: desktop platforms
• Android and iOS lifecycle, touch and packaging: mobile platforms
• Browser constraints, isolation, storage and download size: web platform
• Console constraints and licensed SDK boundaries: console platforms
• OpenXR rigs, tracking, interaction and performance: XR and OpenXR
• CI imports, headless checks, exports and artifact handling: CI and headless automation

Cross-cutting load rules

• Any .tscn, .tres, UID, or external-resource edit: also load serialization and text scenes.
• Any project that accepts remote, user-authored, modded, downloaded, or save-file content: also load security and untrusted content.
• Any performance request: load performance and profiling before prescribing an optimization, then load the relevant subsystem reference.
• Any platform build or export change: load export, release, and signing plus the target-platform file.
• Any engine-version change: load migration and upgrades, official docs and versioning, and the affected subsystem references.
• Any agent-driven scene mutation or project execution: load agent and MCP safety.

Verification ladder

Stop after the first level that provides sufficient evidence, unless repository instructions require more:

1. Inspect changed files and git diff --check.
2. Parse/build the affected language: GDScript through Godot, C# through dotnet build, native code through its configured build system.
3. Run a headless import or startup check with the project's matching Godot binary.
4. Run targeted tests or the affected scene.
5. Run broader integration tests and target exports only when justified.

Before running Godot, identify whether doing so executes @tool scripts, editor plugins, autoloads, native extensions, or project startup code. Treat unfamiliar repositories as untrusted.

Completion report

State:

• files and behavior changed;
• validation actually executed and its result;
• validation not executed and why;
• compatibility or migration risks;
• any required editor-side or platform-side verification.