C# 기초

소개

경고

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

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

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

참고

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

Godot에 C# 설치하기

준비사항

안정(stable) 버전 중 가장 최신의 `.NET Core SDK <https://dotnet.microsoft.com/download/dotnet-core>`__(문서 작성 시점에는 3.1) 을 설치하십시오.

Godot 3.2.3 부터는, 엔진 소스 코드를 빌드할 것이 아니라면 Mono SDK를 설치할 필요가 없습니다.

Godot은 이미 컴파일된 게임을 실행하기 위해 필요한 Mono를 포함하고 있지만, MSBuild처럼 게임을 빌드 및 컴파일 할 수 있는 도구는 포함하고 있지 않으므로 위와 같은 도구들은 따로 설치해야 합니다. MSBuild도 Mono SDK에 포함되어 있지만, 새 csproj 포맷의 C# 프로젝트를 빌드 할 수 없기 때문에 Godot 3.2.3 이후부터는 이 도구들을 포함하고 있는 .NET Core SDK가 필요합니다.

요약하자면, .NET Core SDK와 Mono를 사용할 수 있는 버전의 Godot을 둘 다 설치해야 합니다.

추가 정보

64-bit 버전의 Godot을 사용하고 있다면 64-bit 버전의 SDK를 설치해야 합니다.

Godot을 소스에서 빌드할 생각이라면, 안정(stable) 버전중 최신의 Mono 를 설치하고 Compiling with Mono 페이지의 설명을 따라 진행하십시오.

외부 편집기 설정

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

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio for Mac

  • JetBrains Rider

외부 편집기를 설정하는 방법은 아래 구획들을 확인하십시오:

JetBrains Rider

"준비사항" 구획을 읽은 후, JetBrains Rider 를 설치할 수 있습니다.

Godot의 편집기 → 편집기 설정 메뉴에서:

  • Mono -> Editor -> External EditorJetBrains Rider 로 설정.

  • Mono -> Builds -> Build Tooldotnet CLI 로 설정.

Rider 에서:

  • MSBuild version.NET Core 로 설정.

  • Godot support 플러그인을 설치.

Visual Studio Code

"준비사항" 구획을 읽은 후, Visual Studio Code (VS Code)를 설치할 수 있습니다.

Godot의 편집기 → 편집기 설정 메뉴에서:

  • Mono -> Editor -> External EditorVisual Studio Code 로 설정.

Visual Studio Code에서:

참고

Linux를 사용한다면 C# 플러그인을 사용하기 위해 Mono SDK 를 설치해야 합니다.

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on Add Configuration.... Select C# Godot from the dropdown menu. Open the tasks.json and launch.json files that were created. Change the executable setting in launch.json and command settings in tasks.json to your Godot executable path. Now, when you start the debugger in VS Code, your Godot project will run.

Visual Studio(Windows만 가능)

최신 버전의 Visual Studio 를 설치하십시오. 올바른 워크로드를 선택했다면 Visual Studio 내에 필요한 SDK가 포함되어있을 것이므로, "준비사항" 구획에 설명된 것들을 직접 설치하지 않아도 됩니다.

Visual Studio를 설치할 때, 다음 워크로드를 선택하십시오:

  • Mobile development with .NET

  • .NET Core cross-platform development

Godot의 편집기 → 편집기 설정 메뉴에서:

  • Mono -> Editor -> External EditorVisual Studio 로 설정.

이제 github에서 Godot Visual Studio 확장 프로그램을 다운로드해야 합니다. 다운로드된 파일을 더블 클릭해 설치 과정을 진행하십시오.

C# 스크립트 만들기

Godot용 C# 을 성공적으로 설정한 후, 씬의 노드 메뉴에서 스크립트 붙이기 를 눌렀을 때, 다음 설정이 표시되어야 합니다:

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

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

프로젝트 설정과 작업 흐름

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

예제

여기 동작을 설명하는 주석이 붙은 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는 합리적으로 가능한 것처럼 관용적이도록 노력합니다.

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

경고

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the word Build in the top right corner of the editor. You can also click Mono at the bottom of the editor window to reveal the Mono panel, then click the Build Project button.

You will also need to rebuild the project assemblies to apply changes in "tool" scripts.

현재 문제와 알려진 문제

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

  • 편집기 플러그인을 작성하는 것은 가능하지만, 현재로썬 상당히 복잡합니다.

  • 내보낸 변수를 제외하고, 현재 상태는 핫 리로드 중일 때 저장되고 복원되지 않습니다.

  • 첨부된 C# 스크립트가 파일 이름과 일치하는 클래스 이름을 가진 클래스를 참조해야 합니다.

  • Godot 의 ``snake_case" API 명명 규칙에 의존하는 ``Get ()"/"Set()" "Call()"/"CallDeferred()"와" 시그널 연결 메서드 ``Connect()"와 같은 방법이 있습니다. 그러므로 예를 들어 ``CallDeferred"("AddChild")를 사용할 때 ``AddChild"는 API가 원래의 ``snake_case" 버전의 ``add_child"를 기대하기 때문에 작동하지 않을 것입니다. 그러나 당신은 이러한 제한 없이 모든 맞춤 속성이나 메서드를 사용할 수 있습니다.

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP.

Godot에서 C#의 퍼포먼스

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

Godot에서 NuGet 패키지 사용하기

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

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

Godot 버전 3.2.3부터는 프로젝트를 빌드한 후 새로 추가된 NuGet 패키지를 자동으로 다운로드 및 설정합니다.

C# 코드 프로파일링

  • Linux와 MaxOS에서는 Mono 로그 프로파일러 를 지원합니다. Windows에서는 Mono의 변경으로 현재 로그 프로파일러 사용이 불가능합니다.

  • 다른 Mono 프로파일러로는 JetBrains dotTrace 을 사용 할 수 있습니다. 해당 설명 - here.