C# basics

소개

경고

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# 설치하기

Prerequisites

Install the latest stable version of .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

In summary, you must have installed .NET Core SDK and the Mono-enabled version of Godot.

추가 정보

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the Compiling with Mono page.

외부 편집기 설정

C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio for Mac

  • JetBrains Rider

See the following sections for how to configure an external editor:

JetBrains Rider

After reading the "Prerequisites" section, you can download and install JetBrains Rider.

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

Rider 에서:

  • Set MSBuild version to .NET Core.

  • Godot support 플러그인을 설치.

Visual Studio Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.

Visual Studio (Windows only)

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

Next, you need to download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

C# 스크립트 만들기

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

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

일부 세부 사항이 변경되는 동안, 대부분의 작업은 스크립팅을 C#으로 하는 것과 동일합니다. Godot를 처음 접해보신다면, 이 시점에서 스크립팅(Scripting) 튜토리얼을 정독하시는 것이 좋습니다. 문서의 일부는 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에서 클래스 참조 페이지를 참고하세요.

참고

Keep in mind that the class you wish to attach to your node should have the same name as the .cs file. Otherwise, you will get the following error and won't be able to run the scene: "Cannot find class XXX for script res://XXX.cs"

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

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

더 자세한 내용은, C# API differences to GDScript 페이지를 참고하세요.

경고

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에 대화하려면 마샬링이 필요합니다.

Godot에서 NuGet 패키지 사용하기

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

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

As of Godot 3.2.3, Godot automatically downloads and sets up newly added NuGet packages the next time it builds the project.

C# 코드 프로파일링

  • Mono log profiler is available for Linux and macOS. Due to a Mono change, it does not work on Windows currently.

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