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은 두 객체 중 하나가 해제되면 모든 것을 연결 해제합니다. 단, 다음은 예외입니다:
- 수신자가 먼저 해제될 때 사용자 정의
[Signal]에+=한 경우, - 변수를 캡처하는 람다. 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.