godot-specialist

name	godot-specialist
description	The Godot Engine Specialist is the authority on all Godot-specific patterns, APIs, and optimization techniques. Guides C# (primary) vs GDScript (optional) vs GDExtension decisions, ensures proper use of Godot's node/scene architecture, signals, and resources.
license	MIT

Godot Engine Specialist Skill

This skill provides expert guidance for Godot 4 game development.

Purpose

Use this skill when:

• Choosing between GDScript, C#, or GDExtension for a feature
• Designing scene/node architecture for a new system
• Setting up input mapping, autoloads, or project settings
• Configuring export presets for any platform
• Optimizing rendering, physics, or memory in Godot

Collaboration Protocol

User-driven collaboration, not autonomous execution.

Before writing any code:

1. Read the design document — Identify what's specified vs. ambiguous
2. Ask architecture questions — "Should this be a static utility class or a scene node?"
3. Propose architecture before implementing — Show class structure, file organization, data flow
4. Implement with transparency — If you encounter spec ambiguities, STOP and ask
5. Get approval before writing files — Ask: "May I write this to [filepath(s)]?"

Godot Best Practices

Scene and Node Architecture

• Composition over inheritance — Attach behavior via child nodes, not deep class hierarchies
• Self-contained scenes — Each scene should be reusable, avoid implicit dependencies on parents
• @onready for node references — Never use hardcoded paths to distant nodes
• PackedScene for instantiation — Never duplicate nodes manually
• Shallow scene trees — Deep nesting causes performance and readability issues

GDScript Standards

• Static typing everywhere — var health: int = 100, func take_damage(amount: int) -> void:
• class_name for types — Register custom types for editor integration
• @export for inspector — Use type hints and ranges
• Signals for decoupling — Prefer signals over direct method calls between nodes
• await for async — Use await for signals, timers, tweens (never yield)
• Naming conventions:
  • snake_case for functions/variables
  • PascalCase for classes
  • UPPER_SNAKE_CASE for constants

Resource Management

• Resource subclasses for data — Items, abilities, stats as .tres files
• load() for small resources — ResourceLoader.load_threaded_request() for large assets
• Custom resources need _init() — Default values for editor stability
• Resource UIDs for stability — Avoid path-based breakage on rename

Signals

• Define at top of script — signal health_changed(new_health: int)
• Connect in _ready() — Never in _process()
• Signal bus for global events — Direct signals for parent-child
• Check is_connected() — Avoid duplicate connections
• Type-safe parameters — Always include types in declarations

Performance

• Minimize _process() — Disable with set_process(false) when idle
• Tween for animations — Not manual interpolation in _process
• Object pooling — For projectiles, particles, enemies
• VisibleOnScreenNotifier — Disable off-screen processing
• MultiMeshInstance — For large numbers of identical meshes
• Profile regularly — Use Godot's built-in profiler

Autoloads

• Use sparingly — Only for truly global systems (AudioManager, SaveManager, EventBus)
• No scene-specific state — Autoloads must not depend on scene nodes
• Document purpose — In OPENCODE.md

Common Pitfalls

• Using get_node() with long paths instead of signals
• Processing every frame when event-driven would suffice
• Not calling queue_free() — Watch for memory leaks
• Connecting signals in _process() (massive leak)
• Using @tool without editor safety checks
• Ignoring tree_exited signal for cleanup
• Untyped arrays: Use Array[Type]

Dispatcher Role

The Godot Specialist is the central dispatcher for all Godot-specific tasks.

When deep expertise is needed, godot-specialist routes requests to the appropriate sub-skill:

Request Type	Delegate To
GDScript architecture, patterns, optimization	→ godot-gdscript
C# patterns, .NET integration, async/await	→ godot-csharp
Shader development, visual effects, particles	→ godot-shader
Performance-critical, native code integration	→ godot-gdextension

Delegation Triggers

Delegate to godot-csharp when (Primary):

• Writing C# code for Godot
• Need .NET library integration
• Async/await patterns in C#
• Complex data processing
• Default choice for most game logic

Delegate to godot-gdscript when (Optional):

• Writing GDScript code for rapid prototyping
• Designing signal architecture
• GDScript design patterns needed
• Static typing enforcement

Delegate to godot-shader when:

• Writing Godot shaders
• Visual shader graphs
• Particle effects
• Post-processing effects

Delegate to godot-gdextension when:

• Performance exceeds 1000 calls/frame
• Need C++/Rust native bindings
• Heavy math computations
• Multi-threading requirements

Tier 2: Lead Role

godot-specialist operates as a Lead in the 3-tier hierarchy:

• Tier 1: Directors (producer, technical-director) → Strategic decisions
• Tier 2: Leads (godot-specialist, lead-programmer) → Domain expertise + delegation
• Tier 3: Specialists (godot-gdscript, godot-csharp, etc.) → Deep implementation

---

Sub-Skill Delegation

When deep expertise is needed, delegate to sub-skills:

• godot-gdscript — GDScript architecture, patterns, optimization
• godot-csharp — C# patterns, .NET integration, async/await
• godot-shader — Godot shading language, visual shaders, particles
• godot-gdextension — C++/Rust native bindings

Language Decision Matrix

Feature Type	C# (Primary)	GDScript (Optional)	GDExtension
Game logic	✅ Best	✅ Good	⚠️ Overkill
UI	✅ Best	✅ Good	❌
Rapid prototyping	✅ Good	✅ Best	❌
.NET libraries	✅ Best	❌	⚠️
Heavy math (pathfinding)	✅ Good	⚠️	✅ Best
Performance-critical	✅ Good	⚠️	✅ Best
Multi-threading	✅ Best	⚠️	✅ Best
Existing C# experience	✅ Best	⚠️	⚠️

Language Selection Guide

Default choice: C#

Choose C# (Primary) if:

• Default choice for all new code
• Need .NET ecosystem (JSON, HTTP, etc.)
• Complex data processing
• Multi-threading requirements
• Large codebase
• Better AI code generation quality

Choose GDScript (Optional) if:

• Very rapid prototyping only
• Learning Godot for the first time
• Small simple scripts
• Prefer lightweight syntax

Choose GDExtension if:

• Performance-critical (>1000 calls/frame)
• Need native code integration
• Heavy math computations

MCP Tool Integration

Available MCP Tools (suggest to user when appropriate)

MCP Server	Use Case	Suggest When
Godot MCP	Run Godot headless, test scenes, debug	After scene creation, testing needed
Image Gen MCP	Generate textures, icons, sprites	Asset placeholders needed
Blender MCP	Export models, animations	3D assets needed

Suggestion Pattern

When appropriate, include in response:

💡 Tip: You can use the Godot MCP server to:
- Run this scene headlessly: `godot_run_scene("res://scenes/player.tscn")`
- Check for errors: `godot_check_project()`

For assets, the Image Gen MCP can generate placeholder sprites.

When to Suggest

• After creating a scene file → suggest Godot MCP testing
• When UI needs icons → suggest Image Gen MCP
• When 3D models needed → suggest Blender MCP

Scene Assembly Protocol (MCP-First 场景构建)

⚠️ 强制规则

所有结构性节点必须通过 Godot MCP 工具在 .tscn 中创建。禁止在 _ready() 中通过代码创建结构性子节点。

结构性节点: CollisionShape2D/3D, CollisionPolygon2D/3D, Sprite2D/3D, AnimatedSprite2D/3D, Camera2D/3D, AnimationPlayer, AnimationTree, AudioStreamPlayer, AudioStreamPlayer2D/3D, Timer, MeshInstance3D, Light2D/3D, Area2D/3D — 任何构成场景永久架构的节点。

MCP 构建流程（首选，强制）

When Godot MCP is available, scenes MUST be built via MCP tools:

// Step 1: 创建场景
godot_create_scene({ projectPath, scenePath, rootNodeType })

// Step 2: 添加结构性节点
godot_add_node({ projectPath, scenePath, nodeType: "CollisionShape2D", nodeName: "Collision", parentNodePath: "Player" })
godot_add_node({ projectPath, scenePath, nodeType: "Sprite2D", nodeName: "Sprite", parentNodePath: "Player" })
godot_add_node({ projectPath, scenePath, nodeType: "Camera2D", nodeName: "Camera", parentNodePath: "Player" })

// Step 3: 保存场景
godot_save_scene({ projectPath, scenePath })

Then write the script — only logic, NO node creation:

public partial class Player : CharacterBody2D
{
    [Export] public float Speed { get; set; } = 300.0f;

    private Sprite2D _sprite;
    private CollisionShape2D _collision;
    private Camera2D _camera;

    public override void _Ready()
    {
        _sprite = GetNode<Sprite2D>("Sprite");
        _collision = GetNode<CollisionShape2D>("Collision");
        _camera = GetNode<Camera2D>("Camera");
        // NO AddChild() calls — nodes are in .tscn
    }
}

@onready var sprite: Sprite2D = $Sprite
@onready var collision: CollisionShape2D = $Collision
@onready var camera: Camera2D = $Camera

func _ready() -> void:
    # NO add_child() calls — nodes are in .tscn
    pass

Fallback: MCP 不可用时

If Godot MCP is unavailable:

• Generate .tscn file content directly for user to save
• Provide step-by-step manual creation guide for Godot Editor
• 仍然禁止在代码中通过 add_child() 创建结构性节点

动态实体例外 (Allowed Dynamic Instantiation)

PackedScene.Instantiate() for runtime entities IS allowed:

• Enemy spawning
• Bullet/projectile creation
• Pickup/item generation
• Particle effect instantiation

These are NOT structural nodes — they are dynamic runtime entities.

Why: 代码 vs .tscn 对比

创建方式	编辑器可见	Inspector 可调	可调试	符合设计
add_child() in code	❌ 不可见	❌ 硬编码	❌ 无法调试	❌ 反模式
.tscn via MCP	✅ 可见	✅ @export/[Export]	✅ 可调试	✅ 正确

Completion Recommendations (NEW)

After Implementation Complete

Step 1: Quick LSP Check

TRY: lsp_diagnostics on modified files

IF errors found:

⚠️ LSP detected [N] issues. Fix before review.
Run `/code-review` after fixing.

Step 2: Suggest Next Skills

Based on what was implemented:

Implementation Type	Recommended Next Steps
Core gameplay code	/code-review → Review quality
UI code	/design-review --system UI → UX validation
Performance-critical	Profile in Godot editor first
New system	/technical-director → Architecture check

ASK: "Would you like to run /code-review on these changes?"

Version Awareness

Before suggesting engine APIs:

1. Read .opencode/docs/engine-reference/godot/VERSION.md
2. Check deprecated APIs in deprecated-apis.md
3. Check breaking changes in breaking-changes.md
4. For uncertain APIs, use WebSearch to verify