Community코딩 & 개발github.com

godot-csharp

Godot 4.7 C#/.NET 올바르게 사용하기 - csproj/SDK 설정, 부분 클래스와 소스 생성기, [Export]/[Signal]/[GlobalClass]/[Tool], 반드시 해제해야 하는 C# 시그널과 이벤트(ObjectDisposedException), StringName 캐싱, Variant/컬렉션 마샬링, 비동기 ToSignal, GDScript 상호운용, 문화권 버그, 웹 내보내기 미지원, dotnet 빌드 오류 JSON. 모든 .cs 파일에 사용.

godot-csharp란 무엇인가요?

이 스킬은 Godot 4.7 엔진에서 C#/.NET 개발을 할 때 필요한 핵심 설정과 모범 사례를 제공합니다. 프로젝트 설정(csproj, sln)부터 시작하여, 소스 생성기에 의존하는 `partial class` 규칙, `[Export]`, `[Signal]`, `[GlobalClass]`, `[Tool]` 같은 C# 특성을 올바르게 사용하는 방법, 그리고 시그널 수명 주기 관리(ObjectDisposedException 방지)까지 상세히 다룹니다. StringName 캐싱, Variant/컬렉션 마샬링, 문화권 버그 회피, async/await (ToSignal) 패턴, GDScript와의 상호운용 등 성능과 정확성을 위한 다양한 팁을 포함합니다. 이 문서는 Claude Code, Cursor, Codex 같은 AI 에이전트가 .cs 파일을 편집할 때 Godot 4.7 C# 코드를 올바르게 생성하고 디버깅할 수 있도록 안내합니다. 또한 `cs_build.py`를 통한 빌드 오류 JSON 파싱, `api_lookup.py`를 통한 C# 이름 조회 등 개발 워크플로우를 돕는 유틸리티도 설명합니다.

지원 대상~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/EL4CTEO/godot-skills/tree/main/skills/godot-csharp

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Godot 4.7에서 C# / .NET 사용하기

편집 후 항상 빌드: python scripts/cs_build.py는 오류를 {file, line, code, msg} 형식으로 반환합니다. --doctor로 설정을 확인하고 --init으로 csproj와 sln을 4.7 편집기와 정확히 동일하게 생성합니다. 엔진은 .godot/mono/temp/bin/에 있는 마지막으로 빌드된 어셈블리를 실행하므로, 실행하기 전에 반드시 빌드하세요. C# 이름: api_lookup.py Node3D.look_at은 Node3D.LookAt(Vector3, Vector3?, bool)을 출력합니다. C# 이름은 쿼리로도 사용할 수 있습니다.

프로젝트 설정 (4.7.2 템플릿 확인 완료)

<Project Sdk="Godot.NET.Sdk/4.7.2">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net9.0</TargetFramework>
    <EnableDynamicLoading>true</EnableDynamicLoading>
  </PropertyGroup>
</Project>
  • Godot.NET.Sdk/x.y.z 버전은 엔진 버전과 반드시 일치해야 합니다. Godot을 업그레이드할 때 함께 올리세요. net8.0이 최소이며, net9.0+도 허용됩니다. <Nullable>enable</Nullable>을 권장합니다.
  • project.godot에는 config/features에 "C#"가, [dotnet] project/assembly_name이 필요합니다. 어셈블리 이름은 csproj 이름과 일치해야 합니다.
  • NuGet 패키지는 정상적으로 작동합니다(dotnet add package). 어셈블리는 순수 관리 코드여야 하거나, 모든 대상 플랫폼에 네이티브 라이브러리를 함께 제공해야 합니다.
  • 지원되지 않음: C# 프로젝트의 웹 내보내기(4.7에서도 여전히 해당; 웹 빌드에는 GDScript 사용). Android는 net9.0이 필요합니다(템플릿이 처리). iOS는 작동합니다. 데스크톱은 모든 곳에서 작동합니다.

스크립트 규칙 (소스 생성기가 의존함)

  • public partial class Player : CharacterBody3D. 파일 이름은 클래스 이름과 같아야 합니다(Player.cs). 네임스페이스는 괜찮습니다. Godot 파생 클래스는 partial이어야 합니다.
  • [GlobalClass]는 GDScript의 class_name처럼 클래스를 생성 대화상자와 내보내기 가능한 Resource 타입으로 등록합니다. [Tool]은 편집기에서 클래스를 실행합니다.
  • 내보내기: [Export] public float Speed { get; set; } = 5f; 및 [ExportGroup("Movement")], [ExportSubgroup], [ExportCategory], [Export(PropertyHint.Range, "0,100,1")]와 [ExportToolButton("Bake")] public Callable BakeButton => Callable.From(Bake);.
  • 시그널: [Signal] public delegate void HitEventHandler(int damage);. 접미사는 필수입니다. 생성기는 Hit 이벤트와 SignalName.Hit을 만듭니다. EmitSignal(SignalName.Hit, 5)로 방출하고, enemy.Hit += OnHit;로 연결합니다.
  • API에서 이름이 필요한 곳에는 SignalName.*, MethodName.*, PropertyName.*(생성된 StringName)을 사용하여 문자열을 절대 할당하지 않도록 합니다.
  • 구조체는 복사됩니다: Position.X = 5는 컴파일되지 않습니다(CS1612). Position = Position with { X = 5 };로 작성하세요.

시그널 수명 (공식 규칙)

Godot은 두 객체 중 하나가 해제되면 모든 것을 연결 해제합니다. 단, 다음은 예외입니다:

  1. 수신자가 먼저 해제될 때 사용자 정의 [Signal]에 += 한 경우,
  2. 변수를 캡처하는 람다. Godot은 이를 인스턴스에 연결할 수 없으며, Callable.From도 도움이 되지 않습니다. 두 경우 모두 _ExitTree에서 -=로 구독을 해제하세요(람다의 경우 델리게이트를 필드에 보관). 그렇지 않으면 해제된 객체로 방출할 때 ObjectDisposedException이 발생합니다.

성능 및 정확성

  • 입력 액션, 그룹 및 기타 이름을 static readonly StringName으로 캐시하세요. 매 프레임 "jump"를 전달하면 할당이 발생합니다.
  • 내부 로직에는 System.Collections.Generic을 사용하세요. Godot 경계(내보내기, 시그널, GDScript 호출)에서만 Godot.Collections.Array<T>/Dictionary<TK,TV>를 사용하세요. 교차할 때마다 데이터가 마샬링됩니다.
  • 압축 배열(Vector3[], byte[])은 모든 API 호출에서 복사됩니다. 메시 배열을 한 번 읽고 복사본에서 작업하세요.
  • _Process/_PhysicsProcess 핫 루프에서 LINQ와 클로저를 피하세요. _Ready에서 GetNode<T>()를 한 번 호출하고 결과를 필드에 유지하는 것을 선호하세요.
  • 문화권 버그: $"{1.5f}", float.Parse 및 ToString()은 OS 로케일을 따릅니다(이탈리아어, 독일어 등에서 1,5). 저장, 네트워크 데이터, JSON 및 UI 숫자 형식에는 CultureInfo.InvariantCulture를 사용하세요. (4.7.2 테스트 머신에서 관찰됨.)
  • 콜백에서의 예외는 기록될 뿐, 치명적이지는 않습니다. 출력/디버거 패널을 확인하거나 run_godot.py smoke 오류를 확인하세요.
  • GD.Print는 할당합니다. 핫 경로에서 제거하거나, #if DEBUG 또는 OS.IsDebugBuild() 뒤에 넣으세요.

비동기

  • await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout);은 메인 스레드에서 시그널을 대기합니다.
  • CPU 작업은 Task.Run/WorkerThreadPool에서 실행한 후, 노드를 건드리기 전에 CallDeferred 또는 Callable.From(...).CallDeferred()를 사용하여 메인 스레드로 돌아오세요.
  • _Ready/_Process 내부에서 async void 핸들러를 통해서만 await하고, 짧게 유지하세요. await 후에는 IsInstanceValid(this)를 확인하세요.

GDScript ↔ C#

  • C#에서: var gd = GetNode("Inventory"); gd.Call("add_item", "sword", 2); var n = gd.Get("count").AsInt32();. gd.Connect("changed", Callable.From<int>(OnChanged))로 시그널에 연결합니다.
  • GDScript에서: C# public 멤버는 C# 이름으로 나타납니다(node.Speed, node.Damage(5)). 시그널은 C# 이름을 유지합니다(node.Hit.connect(...)).
  • C#에서 GDScript 객체 생성: GD.Load<GDScript>("res://x.gd").New().AsGodotObject().
  • Variant: Variant.From(x), v.As<T>(), v.AsInt32(), v.VariantType. GDScript가 동적으로 호출하는 메서드에서 Variant를 반환하세요.

패턴, 상호운용 및 편집기/핫 리로드 노트(테스트를 통해 수집): references/patterns.md.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

관련 스킬