C# basics

はじめに

警告

C#サポートは、Godot 3.0以降で利用可能な新しい機能です。そのため、依然としていくつかの問題に遭遇したり、ドキュメントを改善できる箇所が見つかる場合があります。 GodotのC#に関する問題を engine GitHubページ<https://github.com/godotengine/godot/issues> で報告し、ドキュメントの問題を `documentation GitHubページ<https://github.com/godotengine/godot-docs/issues> ` で報告してください。

このページでは、C#の概要と、Godotでの使用方法の両方について簡単に紹介しています。その後、特定の機能を使用する方法C#とGDScript APIの違いについて読み、(再び)ステップバイステップチュートリアルのスクリプトセクションを参照してください。

C#は、マイクロソフトが開発した高度なプログラミング言語です。Godotでは、C# 8.0の完全なサポートを含むMono 6.x .NETフレームワークで実装されています。Monoは、C#および共通言語ランタイムのECMA標準に基づいたMicrosoftの.NET Frameworkのオープンソース実装です。その機能を確認するための良い出発点は、Monoドキュメントの 互換性 <http://www.mono-project.com/docs/about-mono/compatibility/> ページです。

注釈

これはC#言語全体に関する本格的なチュートリアルではありません。まだその構文や機能に慣れていなければ、 Microsoft C#ガイド<https://docs.microsoft.com/en-us/dotnet/csharp/index> や他の適切な入門書を参照してください。

Godot用のC#のセットアップ

Windows (Visual Studio)

GodotでC#を使用するために必要なユーティリティが含まれている最新バージョンの Visual Studio <https://visualstudio.microsoft.com/downloads/> (Visual Studio Code*ではありません* )をダウンロードしてインストールします。 Visual Studio IDEを使用する予定がない場合は、代わりに Visual Studioビルドツール<https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15> のみをダウンロードできます。少なくとも.NET Framework 4.5ターゲットパックがインストールされていることを確認してください。上記の "個別コンポーネント" タブ内のインストーラーのいずれかを使用して入手できます。

Windows (JetBrains Rider)

JetBrains Rider comes with bundled MSBuild, so nothing extra is required. Make sure to set the following preferences:

  • In Godot:

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

    • Set MSBuild version to either bundled with Rider or .NET Core.
    • Install Godot support plugin.

macOSおよびLinux

Mono SDK <http://www.mono-project.com/download/> の最新バージョンをダウンロードしてインストールします。Godot 3.1 beta 3の時点では、Godotには独自のMono 5.18インストールがバンドルされているため、バージョン番号は重要ではありません。 GodotでC#を使用するために必要なNuGetおよびMSBuildのMonoインストールのみが必要です。

注釈

macOSにMonoをダウンロードするには、 Mono Downloads Page <http://www.mono-project.com/download/> から "Stable Channel" リンクを使用します。 Visual StudioチャネルはMonoの以前のバージョンであり、機能しません。

その他の注意事項

Monoサポートが有効になっているGodotを使用する必要があるため、必ず Mono version のGodotをダウンロードしてください。ソースからGodotをビルドする場合は、 Monoでコンパイルする ページに概説されている手順に従って、Monoサポートを有効にしてビルドしてください。

要約すると、Visual StudioまたはMono(オペレーティング システムによって異なります) および Mono対応バージョンのGodotがインストールされている必要があります。

外部エディタの設定

GodotのスクリプトエディタでのC#のサポートは最小限です。外部IDEまたはエディタの使用を検討してください。これらは、C#のオートコンプリート、デバッグ、およびその他の便利な機能を提供します。Godotで外部エディタを選択するには、 エディタ → エディタ設定 をクリックし、 Mono まで下にスクロールします。 Mono で、 Editor をクリックし、外部エディタを選択します。Godotは現在、次の外部エディタをサポートしています。

  • Visual Studio 2019
  • Visual Studio Code
  • MonoDevelop
  • Visual Studio for Mac
  • JetBrains Rider

注釈

Visual Studio Codeを使用している場合は、構文の強調表示やIntelliSenseなどの機能を有効にするために、必ず C# extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp> をダウンロードしてインストールしてください。

注釈

Visual Studio 2019を使用している場合は、以下の「VS2019をデバッグ用に構成する」セクションに記載されている指示に従う必要があります。

C#スクリプトの作成

Godot用にC#を正常に設定した後、シーン内のノードのコンテキストメニューで Attach script を選択すると、次のオプションが表示されます。

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

一部の仕様は変更されますが、スクリプトにC#を使用する場合でも、ほとんどの概念はGDScriptと同じように機能することに注意してください。Godotを初めて使用する場合は、この時点で スクリプト のチュートリアルに従うことをお勧めします。ドキュメント内のいくつかの場所にはまだC#の例が欠けていますが、ほとんどの概念はGDScriptから簡単に移行できます。

プロジェクトの設定とワークフロー

最初のC#スクリプトを作成すると、GodotはGodotプロジェクトのC#プロジェクトファイルを初期化します。これには、C#ソリューション(.sln)とプロジェクトファイル(.csproj)の生成、およびいくつかのユーティリティファイルとフォルダ(.mono および Properties/AssemblyInfo.cs)の生成が含まれます。 .mono を除くこれらすべては重要であり、バージョン管理システム(VCS)にコミットする必要があります。 .mono は、VCSの無視リストに安全に追加できます。 .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 ファイルと同じ名前にする必要があることに注意してください。そうしないと、次のエラーが発生し、シーンを実行できません: "Cannot find class XXX for script res://XXX.cs"

C#とGDScriptの一般的な違い

C# APIはGDScript/C++の snake_case の代わりに PascalCase を使います。 可能であれば、フィールドとゲッター/セッターはプロパティに変換されています。一般的に、C# Godot APIは合理的に可能な限り慣用的であるように努めています。

詳細については、C# API differences to GDScript ページを参照してください。

現在の課題と既知の問題

GodotでのC#のサポートは非常に新しいため、いくつかの苦労や解決する必要があるものがあります。以下は、GodotでC#に飛び込む際に注意する必要がある最も重要な問題の一覧ですが、疑問がある場合は、公式の issue tracker for Mono issues <https://github.com/godotengine/godot/labels/topic%3Amono> もご覧ください。

  • エディタプラグインの作成は可能ですが、現在は非常に複雑です。
  • 現在、エクスポートされた変数を除き、状態(State)は保存およびホットリロード時に復元されません。
  • アタッチされた C#スクリプトは、ファイル名と一致するクラス名を持つクラスを参照する必要があります。
  • Godot の snake_case API 命名規則に依存する Get()/Set()Call()/CallDeferred() 及びシグナル接続メソッド Connect() などのメソッドがあります。したがって、例えば CallDeferred("AddChild") を使用する場合、APIは本来の snake_case バージョンである add_child``を期待しているため、\ ``AddChild では動作しません。ただし、任意のカスタムプロパティまたはカスタムメソッドはこの制限なしに使用できます。

As of Godot 3.2.2, 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#のパフォーマンス

いくつかの予備的な ベンチマーク <https://github.com/cart/godot3-bunnymark> によると、一般的にGodot のC#のパフォーマンスはGDScriptと同程度ですが、いくつかの単純なケースではGDScriptの約 ~4倍 です。C++はさらにもう少し高速です。具体的な内容はユースケースによって異なります。GDScriptは、ほとんどの一般的なスクリプトワークロードに対して十分に高速である可能性があります。C#そのものは高速ですが、Godotと通信するときに負荷の高い形式変換処理が必要です。

GodotでのNuGetパッケージの使用

NuGet <https://www.nuget.org/> パッケージは、他のC#プロジェクトと同様に、Godotでインストールおよび使用できます。多くのIDEは、パッケージを直接追加できます。プロジェクトのルートにある .csproj ファイルにパッケージ参照を追加することにより、手動で追加することもできます:

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

注釈

デフォルトでは、NuGetのようなツールは Version`PackageReference` ノードの属性として配置します。 上記のように、バージョンノードを手動で作成する必要があります。 これは、使用するMSBuildのバージョンで必要なためです。(これはGodot 4.0で修正される予定です。)

パッケージが追加または変更されるたびに、プロジェクトディレクトリのルートで nuget restore (dotnet restore ではなく) を実行します。Nubuildパッケージをmsbuildで使用できるようにするには、次を実行します:

msbuild /t:restore

C#コードのプロファイリング

  • Mono log profiler はLinuxおよびmacOSで利用可能です。Monoの変更により、現在Windowsでは機能しません。
  • こちら<https://github.com/godotengine/godot/pull/34382> _ で説明されている方法で、JetBrains dotTrace <https://www.jetbrains.com/profiler/> _ のような外部のMonoプロファイラーを使用できます。

VS2019をデバッグ用に構成する

注釈

Godotには、いくつかの一般的なC# IDEに関係するワークフローのサポートが組み込まれています。 Visual Studioの組み込みサポートは将来のバージョンに含まれますが、それまでの間、以下の手順でGodot C# プロジェクトで使用するためにVS 2019を構成できます。

  1. .NETデスクトップ開発 および `` C++によるデスクトップ開発`` ワークロードを選択してVS 2019をインストールします。
  2. Xamarinがインストールされていないことを確認してください。 .NETワークロードによるモバイル開発 を選択しないでください。 Xamarinは、MonoDebuggerが使用するDLLを変更し、デバッグを中断します。
  3. VSMonoDebugger拡張機能 をインストールします。
  4. VS2019で → 拡張機能 → Mono → Setting:
    • ``Debug/Deploy to local Windows``を選択してください。.
    • ``Local Deploy Path``を空にしてください。
    • Godot --> プロジェクト--> プロジェクト設定 --> Mono --> Debugger Agentで Mono Debug Port にポートを設定してください。
    • また、GodotのMonoオプションで``Wait For Debugger`` オプションを選択してください。このGodotアドオン <https://godotengine.org/asset-library/asset/435> が役に立つかもしれません。
  5. Godotでゲームを実行してください。Godotのスプラッシュ・スクリーンでデバッガがアタッチされるのを待つために止まるでしょう。
  6. VS2019で、プロジェクトを開いて 拡張機能 --> 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.