godot-csharp-and-gdextension
Use when a Godot project uses or considers C# (.NET) or native code - when C# is the right call and its export limits (no web export), C# node patterns with generated SignalName/StringName caching, plain C# rule libraries tested with dotnet test, and GDExtension (godot-cpp, godot-rust) pinning and build hygiene.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 122
- Forks
- 18
01 前言 Front Matter
- name
- godot-csharp-and-gdextension
- source
- informed by the Godot 4 C#/.NET and GDExtension documentation; own wording
- category
- architecture
- tech_stack
- Godot
- description
- Use when a Godot project uses or considers C# (.NET) or native code - when C# is the right call and its export limits (no web export), C# node patterns with generated SignalName/StringName caching, plain C# rule libraries tested with dotnet test, and GDExtension (godot-cpp, godot-rust) pinning and build hygiene.
03 SKILL.md 正文
Godot C# and GDExtension
Overview
Godot runs GDScript, C# (.NET) and native code through GDExtension (C++ via godot-cpp, Rust via godot-rust, and others). Each has a cost: C# needs the .NET build of the editor and cannot export to the web; GDExtension needs a native build per target platform. The repository's existing choice wins; adding a second language is a decision, not a convenience.
Core principle: GDScript by default, C# where the project already is .NET or the team needs it and the web is not a target, GDExtension only for measured hot spots or native libraries.
When which
| Need | Choice |
|---|---|
| Web export required | GDScript (C# web export is still unsupported in Godot 4.7) |
| Team is C#, heavy algorithms, .NET libraries | C# — on desktop and mobile targets |
| A measured hot loop GDScript cannot meet the budget with | GDExtension (C++ or Rust), or move it to C# if the project is .NET |
| Binding an existing native SDK | GDExtension |
Mixing GDScript and C# in one project works (cross-language calls go through Call, Get, signals), but keep one language per feature and a clear boundary.
C# nodes
using Godot;
public partial class Player : CharacterBody2D
{
[Signal] public delegate void HealthChangedEventHandler(int current, int maximum);
[Export] public PlayerDefinition Definition { get; set; }
static readonly StringName JumpAction = "jump";
static readonly StringName MoveLeft = "move_left";
static readonly StringName MoveRight = "move_right";
AnimatedSprite2D _sprite;
int _health;
public override void _Ready()
{
_sprite = GetNode<AnimatedSprite2D>("AnimatedSprite2D");
_health = Definition.MaxHealth;
}
public override void _PhysicsProcess(double delta)
{
var v = Velocity;
v.X = Input.GetAxis(MoveLeft, MoveRight) * Definition.MoveSpeed;
if (IsOnFloor() && Input.IsActionJustPressed(JumpAction)) v.Y = -Definition.JumpSpeed;
v.Y += Definition.Gravity * (float)delta;
Velocity = v;
MoveAndSlide();
}
public void TakeDamage(int amount)
{
_health = Mathf.Max(0, _health - amount);
EmitSignal(SignalName.HealthChanged, _health, Definition.MaxHealth);
}
}
- Classes deriving from Godot types are
partial(source generators fill in the rest); the file name matches the class name. - Use the generated
SignalName,PropertyNameandMethodNamemembers instead of string literals. - Cache
StringNames. Passing a C#stringtoInput.IsActionPressed("jump")converts it to aStringNameon every call — an allocation per frame per call. - Prefer .NET collections inside C# code;
Godot.Collections.Array/Dictionarymarshal on every access and belong only at the engine boundary (exports, signals). - Cache node references in
_Ready; neverGetNodeinside_Process. deltais adoublein Godot 4 C#.
Rules in a plain library
Game.Core/ net8.0 class library — no Godot reference; rules, math, state machines
Game.Core.Tests/ xUnit or NUnit, references Game.Core
Game/ the Godot project (.csproj references Game.Core)
dotnet test Game.Core.Tests runs anywhere, with or without Godot installed (testable-game-logic). Engine-level C# tests go through gdUnit4Net (godot-testing).
GDExtension
; res://bin/pathfinding.gdextension
[configuration]
entry_symbol = "pathfinding_library_init"
compatibility_minimum = "4.7"
[libraries]
macos.debug = "res://bin/libpathfinding.macos.template_debug.framework"
macos.release = "res://bin/libpathfinding.macos.template_release.framework"
linux.debug.x86_64 = "res://bin/libpathfinding.linux.template_debug.x86_64.so"
windows.debug.x86_64 = "res://bin/pathfinding.windows.template_debug.x86_64.dll"
- C++ (godot-cpp): pin the godot-cpp branch/tag to the project's Godot minor; build with SCons (
scons platform=macos target=template_debug) or the CMake setup the repository uses; register classes in the init function. - Rust (godot-rust / gdext): pin the
godotcrate version and its API feature to the project's Godot minor;cargo build;#[derive(GodotClass)]types appear as nodes. - Commit the
.gdextensionfile and the source; commit built binaries only if the repository already does (otherwise CI builds them). - Keep the native API small and coarse-grained: one call that processes a batch beats a thousand calls from GDScript per frame — crossing the boundary has a cost.
- Unit-test the native core in its own language (C++ test runner,
cargo test) without the engine; test the binding from GDScript with gdUnit4.
Export limits to state up front
- C#: no web export in Godot 4.7; mobile exports are supported but check the pinned version's notes; the export template must be the .NET one.
- GDExtension: one binary per platform and architecture; a missing entry in
[libraries]means the feature silently fails on that platform — test the export for every target the task names, or say which you could not build.
Common Mistakes
- Choosing C# for a game whose task lists the browser as a platform.
- String literals for action names and signal names in hot C# paths.
- Godot collections used for internal C# state.
- A GDExtension built against a different Godot minor than the project, failing to load at runtime.
- Calling into native code per entity per frame instead of per batch.
Red Flags
- A new
.csprojappearing in a GDScript-only project, or GDScript files appearing in a C#-only one, for a task that did not ask for it. GetNodeinside_Process/_PhysicsProcess.- A
.gdextensionfile with platforms listed whose binaries are not built anywhere.
04 同仓库更多 Skills
visual-craft
暂无简介
ux-copy
Use when you write any words a user reads in a mockup or a hand-off - content language and voice, buttons, labels, errors, empty states, confirmations, numbers and dates, and the longest-string check
screen-mockup-html
Use when you draw screens as the design task's HTML mockup - ONE canvas document holding every screen and every variant side by side, the sanitizer-safe recipe, phone and wide frames, the states grid, static control states, and the loopback self-check with screenshots at 375, 768 and 1440 attached to the task
performance-awareness
How the performance score moves for your role. Use when the score context shows a declining trend, or before handing off work you have not self-checked against every criterion.
design-variants
Use when a screen design needs variants - how many, variants as side-by-side rows on the one canvas, what makes two variants genuinely different, recommending one, how the human's choice is read, and narrowing to the chosen one in revision
design-system-authoring
Use when you derive, change or extend a design system - where tokens live per stack, the DTCG token tree, role-based names for both themes, base vs layer vs drift, the DESIGN.md section order, the inventory format, the contrast check and the lint every proposal returns