Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

C# の基本

はじめに

このページでは、C# の概要と、Godot での使用方法について簡単に説明します。その後 特定の機能の使用方法 を参照したり、 C# と GDScript API の違い について読んだり、ステップバイステップのチュートリアルの スクリプト セクション を (再度) 参照したりすることをお勧めします。

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with .NET 8.0.

注意

Godot 4 を使用して C# で記述されたプロジェクトは、現在 Web プラットフォームにエクスポートできません。Web プラットフォームで C# を使用する場合は、代わりに Godot 3 の使用を検討してください。Android および iOS プラットフォームのサポートは Godot 4.2 以降で利用可能ですが、実験段階であり いくつかの制限が適用されます 。

注釈

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

前提条件

Godot には既にコンパイルされたゲームを実行するために必要な .NET の部分がバンドルされています。ただしGodot には、MSBuild や C# コンパイラなど、ゲームのビルドとコンパイルに必要なツールはバンドルされていません。これらは .NET SDK に含まれており、別途インストールする必要があります。

要約すると、.NET SDK および .NET 対応バージョンの Godot をインストールしておく必要があります。

.NET ダウンロードページ から SDK の最新の安定バージョンをダウンロードしてインストールします。

重要

Godot の64ビット バージョンを使用している場合は、必ず SDK の64ビット バージョンをインストールしてください。

Godot をソースからビルドする場合は、 Compiling with .NET ページで説明されている手順に従って、ビルドで .NET サポートを有効にしてください。

外部エディタの設定

Godot の組み込みスクリプト エディタでの C# のサポートは最小限です。Visual Studio Code や MonoDevelop などの外部 IDE またはエディターの使用を検討してください。これらは C# の自動補完、デバッグ、およびその他の便利な機能を提供します。Godot で外部エディタを選択するには、[エディター] → [エディター設定] をクリックし、[.NET] までスクロールします。[.NET] の下で、[エディター] をクリックし、External Editorを選択します。Godot は現在、次の外部エディタをサポートしています。

  • Visual Studio 2022

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio for Mac

  • JetBrains Rider

外部エディターを構成する方法については、次のセクションを参照してください。

JetBrains Rider

「前提条件」セクションを読んだ後、JetBrains Rider をダウンロードしてインストールできます。

Godot の エディター → エディター設定 メニューで:

  • .NET -> エディター -> External Editor を JetBrains Rider に設定します。

Riderでは:

  • MSBuild version を .NET Core に設定します。

  • If you are using a Rider version below 2024.2, install the Godot support plugin. This functionality is now built into Rider.

Visual Studio Code

「前提条件」セクションを読んだ後、Visual Studio Code (別名 VS Code) をダウンロードしてインストールできます。

Godot の エディター → エディター設定 メニューで:

  • .NET -> エディター -> External Editor を Visual Studio Code に設定します。

Visual Studio Codeでは:

  • C# 拡張機能をインストールします。

プロジェクトのデバッグ実行を行うには、必要な構成を含む .vscode フォルダーに tasks.json ファイルと launch.json ファイルが必要です。

launch.json の例を次に示します。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${env:GODOT4}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
        }
    ]
}

この起動構成を機能させるには、Godot 実行可能ファイルを指す GODOT4 環境変数を設定するか、 program パラメータを Godot 実行可能ファイルへのパスに置き換える必要があります。

tasks.json の例を次に示します。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": [
                "build"
            ],
            "problemMatcher": "$msCompile"
        }
    ]
}

これで、Visual Studio Code でデバッグを開始すると、Godot プロジェクトが実行されます。

Visual Studio (Windows のみ)

最新バージョンの Visual Studio をダウンロードしてインストールします。正しいワークロードを選択した場合、Visual Studio には必要な SDK が含まれるため、「前提条件」セクションに記載されているものを手動でインストールする必要はありません。

Visual Studio のインストール時に、次のワークロードを選択します。

  • .NET デスクトップ開発

Godot の エディター → エディター設定 メニューで:

  • .NET -> エディター -> External Editor を Visual Studio に設定します。

注釈

「パッケージ Godot.NET.Sdk が見つかりません」のようなエラーが表示される場合は、NuGet の構成が正しくない可能性があり、修正する必要があります。

NuGet 構成ファイルを修正する簡単な方法は、それを再生成することです。ファイルエクスプローラーウィンドウで、%AppData%\NuGet に移動します。NuGet.Config ファイルの名前を変更するか削除します。Godot プロジェクトを再度ビルドすると、ファイルはデフォルト値で自動的に作成されます。

Visual Studio を使用して C# スクリプトをデバッグするには、エディターで最初の C# スクリプトを開いた後に生成される .sln ファイルを開きます。デバッグ メニューで、プロジェクトの デバッグ プロパティ メニュー項目に移動します。新しいプロファイルの作成 ボタンをクリックし、実行可能ファイル を選択します。実行可能ファイル フィールドで、C# バージョンの Godot エディターのパスを参照するか、Godot 実行可能ファイル パスの環境変数を作成している場合は %GODOT4% と入力します。これは、"コンソール"バージョンではなく、メインの Godot 実行可能ファイルへのパスである必要があります。作業ディレクトリ には、現在のディレクトリを意味する単一のピリオド . を入力します。ネイティブコードのデバッグを有効にする チェックボックスもオンにします。これでこのウィンドウを閉じて、デバッグ プロファイル ドロップダウンの下矢印をクリックし、新しい起動プロファイルを選択できます。緑の開始ボタンを押すと、ゲームがデバッグモードで実行されます。

C#スクリプトの作成

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

../../../_images/attachcsharpscript.webp

スクリプトに C# を使用する場合、一部の細かい仕様は変わりますが、ほとんどのコンセプトは同じように機能します。Godot を初めて使用する場合は、この時点で スクリプト言語 のチュートリアルに従うことをお勧めします。一部のドキュメントページには C# のサンプルがまだありませんが、ほとんどのコードはGDScriptから簡単に移行できます。

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

最初のC#スクリプトを作成すると、GodotはGodotプロジェクトのC#プロジェクトファイルを初期化します。これには C#ソリューション(.sln)とプロジェクトファイル(.csproj)の生成、およびいくつかのユーティリティ ファイルとフォルダー (.godot/mono) の生成が含まれます。 .godot/mono 以外のこれらはすべて重要なので、バージョン管理システムにコミットする必要があります。 .godot の下にあるものはすべて、バージョン管理の無視リストに安全に追加できます。トラブルシューティングを行うときは、 .godot/mono フォルダーを削除して再生成すると改善する場合があります。

サンプル

以下に、空白のC#スクリプトと、その動作を示すコメントを示します。

using Godot;

public partial 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(double 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の一般的な違い

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

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

警告

C#スクリプトから新しくエクスポートされた変数やシグナルをエディターで表示するには、プロジェクトアセンブリをリビルドする必要があります。このビルドはエディターの右上隅にある [ビルド] ボタンをクリックすることで手動でトリガーできます。

../../../_images/build_dotnet1.webp

また「ツール」スクリプトの変更を適用するためにも、プロジェクトアセンブリをリビルドする必要があります。

現在の課題と既知の問題

GodotでのC#のサポートは非常に新しいため、いくつかの苦労や解決すべき問題があります。以下は Godot で C# を使用する際に注意したほうがいい重要なリストですが、疑問がある場合は、公式の .NET の問題管理システム も併せて確認してください。

  • エディタプラグインの作成は可能ですが、現在は非常に複雑です。

  • 現在、エクスポートされた変数を除き、状態(State)は保存およびホットリロード時に復元されません。

  • アタッチされた C#スクリプトは、ファイル名と一致するクラス名を持つクラスを参照する必要があります。

  • Godot の snake_case API 命名規則に依存する Get()/Set() 、Call()/CallDeferred() 及びシグナル接続メソッド Connect() などのメソッドがあります。したがって、例えば CallDeferred("AddChild") を使用する場合、API は元の snake_case バージョンの add_child を想定しているため、 AddChild は機能しません。ただし、この制限なしに任意のカスタム プロパティまたはメソッドを使用できます。余分な StringName 割り当てを回避し、snake_case 命名を気にせず、 PropertyName 、 MethodName 、および SignalName で公開されている StringName を使用することをお勧めします。

Godot 4.0 以降、.NET プロジェクトのエクスポートはデスクトッププラットフォーム (Linux、Windows、macOS) でサポートされています。他のプラットフォームは、今後の 4.x リリースでサポートされる予定です。

よくある落とし穴

Godot オブジェクトの値を変更しようとしたとき。たとえば Node2D の X 座標を変更しようとすると、次のエラーが発生する場合があります。

public partial class MyNode2D : Node2D
{
    public override void _Ready()
    {
        Position.X = 100.0f;
        // CS1612: Cannot modify the return value of 'Node2D.Position' because
        // it is not a variable.
    }
}

これはまったく正常です。C# の構造体 (この例では Vector2) は代入時にコピーされます。つまりプロパティまたはインデクサーからそのようなオブジェクトを取得すると、オブジェクト本体ではなく、そのコピーが取得されてしまいます。その後で再代入せずにそのコピーを変更したとしても、何も達成されません。

回避策は簡単です。構造体全体を取得し、変更したい値を変更して、プロパティへ再代入します。

var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;

C# 10 以降では、構造体に対して with式 を使用することも可能になり、同じことを1行で実行できるようになりました。

Position = Position with { X = 100.0f };

このエラーの詳細については、C# 言語リファレンス を参照してください。

GodotにおけるC#のパフォーマンス

参考

For a performance comparison of the languages Godot supports, see Which programming language is fastest?.

GodotObject に基づく Godot C# オブジェクトのほとんどのプロパティ (例: Control のような Node や Camera3D のような Node3D) は、Godot の C++ コアと通信するため、ネイティブ (interop) 呼び出しが必要です。単一のコード中にプロパティを複数回変更または読み取る必要がある場合は、そのようなプロパティの値はローカル変数に一時的に代入することを検討してください。

using Godot;

public partial class YourCustomClass : Node3D
{
    private void ExpensiveReposition()
    {
        for (var i = 0; i < 10; i++)
        {
            // Position is read and set 10 times which incurs native interop.
            // Furthermore the object is repositioned 10 times in 3D space which
            // takes additional time.
            Position += new Vector3(i, i);
        }
    }

    private void Reposition()
    {
        // A variable is used to avoid native interop for Position on every loop.
        var newPosition = Position;
        for (var i = 0; i < 10; i++)
        {
            newPosition += new Vector3(i, i);
        }
        // Setting Position only once avoids native interop and repositioning in 3D space.
        Position = newPosition;
    }
}

生の配列 (byte[] など) または string を Godot の C# API に渡すには、比較的コストのかかるマーシャリングが必要です。

string から NodePath または StringName への暗黙的な変換では、 string をマーシャリングしてそれぞれのネイティブコンストラクターに渡す必要があるため、ネイティブinteropとマーシャリングの両方のコストが発生します。

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

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

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

Godot 3.2.3 以降では、Godot は次回プロジェクトをビルドするときに、新しく追加された NuGet パッケージを自動的にダウンロードして設定します。

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

マネージドコードのパフォーマンスとメモリのプロファイリングには、次のツールを使用できます。

  • dotTrace/dotMemory プラグインを備えた JetBrains Rider。

  • スタンドアロンの JetBrains dotTrace/dotMemory。

  • Visual Studio。

マネージドコードとアンマネージドコードを一度にプロファイリングすることは、JetBrains ツールと Visual Studio の両方で可能ですが、Windows に限定されます。