소개

경고

C# 지원은 Godot 3.0의 새로운 기능입니다. 따라서, 실행 중 여전히 문제가 발생할 수 있고, 문서를 개선할 수 있는 부분을 발견할 수도 있습니다. 엔진 Github 페이지에서 Godot의 C#관련 문제들을 보고해주세요. 그리고 문서상의 문제는`문서 Github 페이지 <https://github.com/godotengine/godot-docs/issues>`_에서 보고해주세요.

이 페이지는 C#에 대한 간단한 소개와 그것이 무엇인지, 그리고 그것을 Godot에서 사용하는 방법을 제공합니다. 그런 다음, 특정 기능을 사용하는 방법을 원한다면, C# 과 GDScript API의 차이점에 대해 읽고 단계별 튜토리얼의 스크립팅 섹션을 (다시) 확인하세요.

C#은 하이 레벨 프로그래밍 언어로 Microsoft가 개발했습니다. Godot에서는 Mono 5.x .NET framework로 구현되었으며, C# 7.0을 완전 지원합니다. Mono는 Microsoft의 .NET Framework의 오픈 소스로 C#을 위한 ECMA 표준과 Common Language Runtime에 기반으로 구현되었습니다. 적합성을 확인하기 위한 좋은 출발점으로 Mono 문서에 있는 `적합성<http://www.mono-project.com/docs/about-mono/compatibility/>`_ 페이지 입니다.

주석

이것은 전체적으로 C# 언어에 대한 본격적인 튜토리얼이 아닙니다. 문법이나 기능에 익숙하지 않다면 Microsoft C# 가이드를 보거나 다른 적합한 설명을 찾아보세요.

Godot에 C# 설치하기

윈도우

Visual Studio의 최신 버전을 다운로드 하고 설치하세요 (Visual Studio Code 아닙니다), 여기에는 Godot에서 C#을 사용하기 위한 기능들이 있습니다. Visual Studio IDE를 사용할 계획이 없다면, 대신 Visual Studio Build Tools를 다운로드 할 수 있습니다. 최소한 설치 대상이 .NET Framework 4.5를 갖고 있어야 합니다, 앞에서 언급한 설치 프로그램를 보면 "Individual components" 탭 안에서 그것을 얻을 수 있습니다.

macOS와 리눅스

Mono SDK의 최신 버전을 다운로드 하고 설치하세요. Godot 3.1 베타 3에서부터, Godot는 자체적인 Mono 5.18 설치를 포함하므로 버전 숫자는 문제가 되지 않습니다. Godot에서 C#을 사용하기 위해 필요한 것은 NuGet과 MSBuild 용 Mono 설치 뿐입니다.

주석

macOS에서 Mono를 다운로드 하기 위해, Mono 다운로드 페이지로 가서 "Stable Channel" 링크로 가세요. Visual Studio 채널은 이전 버전의 Mono로 작동되지 않을 것입니다.

추가 정보

당신의 Godot 버전이 Mono를 지원해야 하는데, 그러기 위해 Godot의 Mono 버전을 다운로드 해야 합니다. 소스에서 Godot를 빌드하는 경우, Compiling with Mono 페이지에서 설명하는 Mono 지원을 활성화 하는 순서를 따라야 합니다.

요약하자면, Visual Studio나 Mono가 (운영체제에 맞게) 설치되어 있어야 하며 그리고 Mono를 사용할 수 있는 버전의 Godot이어야 합니다.

외부 편집기 구성하기

Godot의 스크립트 에디터에서 C# 지원은 최소한입니다. Visual Studio Code나 MonoDevelop과 같은 외부 IDE나 편집기를 사용하는 것을 고려해보세요. 이 둘은 자동 완성, 디버깅을 제공하며 C#으로 작업하면서 쓰이는 유용한 기능이 있습니다. Godot에서 외부 편집기를 선택하려면, 에디터 → 에디터 설정으로 가서 Mono로 내려갑니다. Mono에서 Editor를 클릭하면 외부 편집기를 선택하는 페이지가 나타납니다.

주석

만약 Visual Studio Code를 사용하고 있다면, `C# 확장 프로그램<https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>`_을 설치하여 문법 하이라이트 효과와 IntelliSense같은 기능을 사용하는 것을 잊지마세요.

C# 스크립트 만들기

Godot를 위한 C# 설정이 성공적으로 마친 후, 씬의 노드 메뉴에서 스크립트 붙이기를 눌렀을 때, 다음 설정이 보여야 합니다:

../../../_images/attachcsharpscript.png

일부 세부 사항이 변경되는 동안, 대부분의 작업은 스크립팅을 C#으로 하는 것과 동일합니다. Godot를 처음 접해보신다면, 이 시점에서 스크립팅(Scripting) 튜토리얼을 정독하시는 것이 좋습니다. 문서의 일부는 C# 예제가 부족하지만, 대부분은 일찍이 GDScript에서 옮길 수 있습니다.

프로젝트 설정과 작업 흐름

첫 C# 스크립트를 생성하면, Godot는 Godot 프로젝트를 위한 C# 프로젝트 파일을 초기화합니다. 여기에는 C# 솔루션 (.sin)이나 프로젝트 파일 (.csproj) 뿐만 아니라, 일부 유용 파일과 폴더들 (.monoProperties/AssemblyInfo.cs)을 생성하는 것도 포함합니다. .mono를 제외하고는 모두 중요하므로 버전 관리 시스템에 유지해 두어야 합니다. .mono는 버전 관리 시스템의 무시 목록에 쉽게 추가할 수 있습니다. 문제를 해결할 때, .mono 폴더를 삭제하고 다시 만드는 것이 때로는 도움이 됩니다.

현재, Godot와 C# 프로젝트가 동기화되지 않는 문제가 있습니다; C# 스크립트를 삭제, 이름 변경, 이동을 한다면, 변경사항이 C# 프로젝트 파일에 반영되지 않을지도 모릅니다. 이 경우, 수동으로 C# 프로젝트 파일을 편집해야 할 것입니다.

예를 들어 스크립트를 생성하고 (예: Test.cs) Godot에서 삭제한다면,누락된 파일이 C 프로젝트 파일에 남아있기 때문에 컴파일에 실패할 것입니다. 지금은, 단순히 .csproj 파일을 열고 ItemGroup을 볼수 있고, 다음과 같은 글이 있어야 합니다:

<ItemGroup>
    <Compile Include="Test.cs" />
    <Compile Include="AnotherTest.cs" />
</ItemGroup>

단순히 이 줄을 삭제하면 프로젝트는 다시 올바르게 빌드됩니다. 이름 변경과 이동도 이와 마찬가지로, 필요에 따라 이름을 바꾸고 프로젝트 파일로 옮깁니다.

예제

여기 몇 가지 주석으로 작업이 이루어지는 방법을 설명하는 공백 C# 스크립트가 있습니다.

using Godot;
using System;

public class YourCustomClass : Node
{
    // Member variables here, example:
    private int a = 2;
    private string b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(float delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

보시다시피, Godot의 print 함수와 마찬가지로 GDScript에서 함수는 기본적으로 전역 범위에 있기 때문에 Godot 네임스페이스의 일부분인 GD 클래스에서 사용할 수 있습니다. GD 클래스에서의 메서드 목록을 보려면, @GDScript@GlobalScope에서 클래스 참조 페이지를 참고하세요.

주석

노드에 붙이고 싶은 클래스 이름이 .cs 파일이어야 한다는 사실을 명심하세요. 그렇지 않으면, 다음과 같은 오류를 받게 되며 씬을 실행할 수 없을 것입니다: "스크립트 res://XXX.cs에서 클래스 XXX를 찾을 수 없음"

C#과 GDScript와의 일반적인 차이

GDScript/C++에서는 snake_case를 쓰지만 C# API는 PascalCase를 씁니다. 가능하면 공백과 getters/setters이 속성으로 변환됩니다. 일반적으로 C# Godot API는 합리적으로 가능한 것처럼 관용적이도록 노력합니다.

더 자세한 내용은, GDScript와의 API 차이점 페이지를 참고하세요.

현재 문제와 알려진 문제

C# 지원이 Godot에서 꽤 새롭기 때문에, 성장통이 있고 다듬어야 할 곳이 여전히 있습니다. 아래에는 중요한 문제 목록으로 Godot에서 C#으로 갈아탈 때 명심해야 합니다, 하지만 의심스러운 점이 있다면 공식 Mono 이슈를 위한 이슈 트래커를 살펴보세요.

  • 위에서 설명했듯이, C# 프로젝트가 Godot에서 삭제, 이름 변경, 이동을 할 때 항상 동기화를 자동으로 하지는 않습니다 (#12917).
  • 에디터 플러그인을 작성하는 것은 가능하지만, 현재로썬 상당히 복잡합니다.
  • 내보낸 변수를 제외하고, 현재 상태는 핫 리로드 중일 때 저장되고 복원되지 않습니다.
  • Mono 프로젝트를 내보내는 것은 데스크탑 플랫폼 (Linux, 윈도우, 그리고 macOS)만 지원합니다. Android, iOS, HTML5 그리고 UWP는 현재는 지원하지 않습니다 (#20267, #20268 #20270 #20271).
  • 첨부된 C# 스크립트가 파일 이름과 일치하는 클래스 이름을 가진 클래스를 참조해야 합니다.

Godot에서 C#의 퍼포먼스

일부 예비 벤치마크에 따르면, Godot에서 C#의 퍼포먼스는 — 일반적으로 같은 순서의 크기에서 — 순수한 경우에서 대략 GDScript의 ~4x입니다. C++이 아직 조금 더 빠릅니다; 하지만 세부 사항은 사용하는 경우에 따라 다릅니다. GDScript는 대부분의 일반적인 스크립팅 작업에 충분히 빠릅니다. C#이 더 빠르지만, Godot에 대화하려면 마샬링이 필요합니다.

Godot에서 NuGet 패키지 사용하기

NuGet 패키지를 설치하여 프로젝트처럼, Godot와 사용할 수 있습니다. 많은 IDE는 직접 패키지를 추가할 수 있습니다. 또한 프로젝트 루트에 있는 .csproj 파일에 패키지 참조를 수동으로 추가할 수 있습니다:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2"/>
    </ItemGroup>
    ...
</Project>

패키지가 추가되고 수정될 때마다, 프로젝트 디렉토리 루트에서 nuget restore를 실행하여, msbuild가 사용하고 실행하기 위한 NuGet 패키지를 이용할 수 있도록 합니다:

msbuild /t:restore