소개

경고

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

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

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the Mono 6.x .NET framework, including full support for C# 8.0. Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime. A good starting point for checking its capabilities is the Compatibility page in the Mono documentation.

주석

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

Godot에 C# 설치하기

Windows (Visual Studio)

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

Windows (JetBrains Rider)

JetBrains Rider comes with bundled MSBuild, so you just need a recent .NET Framework Developer Pack. Make sure to set the following preferences:

  • In Godot:

    • Mono External Editor to JetBrains Rider
    • Mono Build Tool to JetBrains Mono.
  • In Rider:

    • TargetFrameworkVersion in csproj should match the installed .NET Framework Developer Pack.
    • Install Godot support plugin.

macOS와 Linux

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이어야 합니다.

외부 편집기 구성하기

C# support in Godot's 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

주석

If you are using Visual Studio Code, ensure you download and install the C# extension to enable features like syntax highlighting and IntelliSense.

주석

Visual Studio 2019를 사용하는 경우 아래 "Configure VS2019 for Debugging" 지침을 따라야합니다.

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에서 클래스 참조 페이지를 참고하세요.

주석

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는 합리적으로 가능한 것처럼 관용적이도록 노력합니다.

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

현재 문제와 알려진 문제

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

  • 위에서 설명했듯이, C# 프로젝트가 Godot에서 삭제, 이름 변경, 이동을 할 때 항상 동기화를 자동으로 하지는 않습니다 (#12917).
  • 편집기 플러그인을 작성하는 것은 가능하지만, 현재로썬 상당히 복잡합니다.
  • 내보낸 변수를 제외하고, 현재 상태는 핫 리로드 중일 때 저장되고 복원되지 않습니다.
  • Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. UWP is not currently supported. (#20271).
  • 첨부된 C# 스크립트가 파일 이름과 일치하는 클래스 이름을 가진 클래스를 참조해야 합니다.
  • Godot 의 ``snake_case" API 명명 규칙에 의존하는 ``Get ()"/"Set()" "Call()"/"CallDeferred()"와" 시그널 연결 메서드 ``Connect()"와 같은 방법이 있습니다. 그러므로 예를 들어 ``CallDeferred"("AddChild")를 사용할 때 ``AddChild"는 API가 원래의 ``snake_case" 버전의 ``add_child"를 기대하기 때문에 작동하지 않을 것입니다. 그러나 당신은 이러한 제한 없이 모든 맞춤 속성이나 메서드를 사용할 수 있습니다.

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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

주석

By default, tools like NuGet put Version as an attribute of the `PackageReference` Node. You must manually create a Version node as shown above. This is because the version of MSBuild used requires this. (This will be fixed in Godot 4.0.)

Whenever packages are added or modified, run nuget restore (not dotnet restore) in the root of the project directory. To ensure that NuGet packages will be available for msbuild to use, run:

msbuild /t:restore

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.

디버깅을 위한 VS 2019 구성

주석

Godot은 몇몇 인기 있는 C# IDE와 관련된 워크플로에 대한 기본 지원을 가지고 있습니다. Visual Studio에 대한 내장 지원은 향후 버전에서 포함되지만, 그 동안 아래 단계를 통해 Godot C# 프로젝트와 함께 사용할 VS 2019를 구성할 수 있습니다.

  1. .NET desktop development 및``Desktop development with C++``워크로드로 VS 2019를 설치하십시오.
  2. Xamarin 이 설치되지 않았는지 확인하십시오. .NET을 사용한 모바일 개발 워크로드를 선택하지 마십시오. Xamarin은 MonoDebugger에서 사용하는 DLL을 변경하여 디버깅을 중단합니다.
  3. `VSMonoDebugger 확장 프로그램 <https://marketplace.visualstudio.com/items?itemName=GordianDotNet.VSMonoDebugger0d62>`_를 설치하십시오.
  4. In VS 2019 --> Extensions --> Mono --> Settings:
    • Select Debug/Deploy to local Windows.
    • Leave Local Deploy Path blank.
    • Set the Mono Debug Port to the port in Godot --> Project --> Project Settings --> Mono --> Debugger Agent.
    • Also select Wait for Debugger in the Godot Mono options. This Godot Addon may be helpful.
  5. Run the game in Godot. It should hang at the Godot splash screen while it waits for your debugger to attach.
  6. In VS 2019, open your project and choose Extensions --> Mono --> Attach to Mono Debugger.

Configuring Visual Studio Code for debugging

To configure Visual Studio Code for debugging open up a project in Godot. Click on Project and open the project settings. Scroll down and click on Debugger Agent under the Mono category. Then turn on the setting "wait for debugger." Next, copy the port number and open up Visual Studio Code.

You need to download the Mono Debug extension from Microsoft. Then open the Godot project folder. Go to the run tab and click on create a launch.json file. Select C# Mono from the dropdown menu. When the launch.json file is automatically opened, change the port number to the number you copied previously and save the file. On the run tab, switch the run setting from launch to attach. Whenever you want to debug, make sure Wait for Debugger is turned on in Godot, run the project, and run the debugger in Visual Studio Code.