Godot で C++ ライブラリを使用する
Using any C++ library in Godot (blog.conan.io)
要約
Godot エンジンは、GDScript でゲーム開発を行うのが一般的ですが、既存の C/C++ ライブラリを利用したい場合、GDExtension と公式 C++ バインディングである godot-cpp を通じてネイティブコードを統合できます。この記事では、Godot の C++ 拡張機能の仕組みを解説し、特に Conan と godot-cpp 10 を使用して、flecs のようなライブラリを Godot プロジェクトに組み込む方法を実例を交えて紹介します。これにより、プラットフォームごとのライブラリのコンパイルと依存関係管理が効率化されます。
全文翻訳
Godotで任意のC++ライブラリを使用する
Godotは、ここ数年で最も人気のあるゲームエンジンの1つになりました。MITライセンスの下でフリーかつオープンソースであり、ダウンロードして数分で使用を開始できるほど軽量です。ほとんどのGodotゲームは、エンジンの独自スクリプト言語であるGDScriptで記述されています。
しかし、多くのプロジェクトでは、シミュレーションライブラリ、データベース、ネットワークプロトコル、機械学習ランタイムなど、すでにCまたはC++ライブラリとして存在する機能が必要になることがあります。GDScriptはネイティブコードを呼び出せませんが、GodotはGDExtensionを通じてそれをロードできます。そして、公式C++バインディングであるgodot-cppを使用すると、そのコードを通常のエンジンクラスとして公開できます。C++コードの記述は簡単ですが、難しいのはビルドプロセスです。godot-cppはGodotのバージョンと一致させる必要があり、追加するすべてのライブラリは、配布する各プラットフォーム向けにコンパイルする必要があります。
この記事では、Godotの簡単な紹介、C++拡張機能の仕組み、そしてConanとgodot-cpp 10(ConanCenterで利用可能)を使用してGodotゲームにC++ライブラリを取り込む方法を説明します。例として、Entity Component Systemライブラリであるflecsを使用し、Godotシーン内で10万個のパーティクルをシミュレーションします。
[動画: 動画をダウンロード]
Godotシーン内でflecsを使用してシミュレーションされた10万個のパーティクルが、マウスカーソルから逃げている様子
Godotの簡単な紹介
Godotは、2Dおよび3Dゲーム向けの汎用エンジンです。Godotプロジェクトのすべては、2つの概念から構築されます。
- ノードは基本的な構成要素です。各ノードには、タイプ(
Sprite2D、Camera3D、AudioStreamPlayer、Timerなど)、インスペクターで編集できるプロパティのセット、およびゲームループ中にエンジンが呼び出す_ready()や_process()のようなコールバックがあります。 - シーンは、ディスクに
.tscnファイルとして保存されたノードのツリーです。シーンはキャラクター、メニュー、または完全なレベルになり得、シーンは他のシーン内にインスタンス化できます。
通常、ノードにスクリプトをアタッチすることで動作が追加されます。GDScriptは、エンジン向けに設計されたPythonライクな言語であり、コンパイルステップなしで変更が即座に反映されるため、ゲームプレイロジックに最適です。
C++開発者にとってGodotが興味深いのは、エンジン自体がC++で記述されており、再コンパイルなしでC++で記述された拡張機能をロードできることです。これらの拡張機能から提供されるクラスは、通常のエンジンクラスになり、エディター内で組み込みノードの隣に表示され、インスペクターにプロパティが表示され、GDScriptは他のノードと同様に使用できます。次のセクションでは、これらの拡張機能の仕組みを説明します。
C++によるGodotの拡張
GodotにC++コードを追加するには、2つの方法があります。
- エンジンモジュール:エンジン自体にコンパイルされます。内部へのフルアクセスが可能ですが、エディターと各プラットフォームのエクスポートテンプレートを含むGodotの独自のコピーをビルドして配布する必要があります。
- GDExtension:実行時に、公式の未変更のGodotビルドに共有ライブラリ(Web上では
.dll、.so、.dylib、または.wasm)をロードします。エンジンは、安定したCインターフェースを通じてライブラリと通信します。
GDExtensionは、ほとんどのプロジェクトで推奨されるアプローチであり、多くの人気のあるプラグインが今日配布されています。Cインターフェースは直接使用するには冗長であるため、Godotチームはgodot-cppを維持しています。これは、エンジン内部で使用されるAPIに非常に近いAPIでCインターフェースをラップするC++ライブラリです。Node2D、Sprite2D、Inputなどの各エンジンクラスに対してC++クラスを提供します。
独自のクラスは、これらのクラスを継承する通常のC++コードです。godot-cppで記述されたノードは次のようになります。
#include <godot_cpp/classes/node2d.hpp>
namespace godot {
class MyNode : public Node2D {
GDCLASS(MyNode, Node2D)
protected:
static void _bind_methods() {}
public:
void _process(double p_delta) override {
// 毎フレーム実行される
}
};
} // namespace godot
バージョン10.0以降、単一のgodot-cppリリースは、4.3以降の任意のGodotバージョンで動作します。api_versionビルドオプションでバージョンを選択すると、godot-cppはそのバージョンのAPIからC++クラスを生成します。Godot 4.3用にビルドされた拡張機能は、新しいバージョンでも機能しますが、古いバージョンでは機能しません。そのため、通常はサポートしたい最も古いGodotバージョンを選択します。
ビルドターゲットとフィーチャートグ
ビルドする前に知っておくべきもう1つの概念があります。godot-cppは、Godotビルドの名前にちなんで名付けられた3つのターゲットのいずれかにコンパイルされます。
template_debug:デフォルト。DEBUG_ENABLED定義を通じてデバッグチェックを有効にします。このライブラリは、エディターとデバッグエクスポートによってロードされます。template_release:リリースエクスポート用で、デバッグチェックは削除されます。editor:エディターのみでロードされるライブラリ用です。
Godotがどのライブラリをロードするかは、小さな.gdextensionファイルによって実行時に決定されます。これは、フィーチャートグをライブラリパスにマッピングします。debugタグはエディターとデバッグエクスポートに一致し、releaseタグはリリースエクスポートに一致します。
[configuration]
entry_symbol = "gdexample_library_init"
compatibility_minimum = "4.7"
[libraries]
macos.debug = "res://bin/libgdexample.template_debug.dylib"
macos.release = "res://bin/libgdexample.template_release.dylib"
linux.debug = "res://bin/libgdexample.template_debug.so"
linux.release = "res://bin/libgdexample.template_release.so"
windows.debug = "res://bin/libgdexample.template_debug.dll"
windows.release = "res://bin/libgdexample.template_release.dll"
通常のワークフロー
Godotドキュメントでは、godot-cppをGitサブモジュールとしてリポジトリに追加し、SConsを使用してライブラリと一緒にビルドすることを推奨しています。これは最初の拡張機能にはうまく機能しますが、各プロジェクトはターゲットごとに独自のgodot-cppをコンパイルすることになり、物理エンジンや機械学習ランタイムなどのラップするサードパーティライブラリは、Godotがエクスポートするすべてのプラットフォームに合わせて、ベンダー化され、一致するフラグでビルドする必要があります。
これらはまさにConanが解決するために構築された問題です。
Conanによる依存関係の管理
ConanCenterにgodot-cppレシピがあることで、godot-cppは通常のパッケージになります。上記で議論された2つのパラメータはConanオプションです。
api_version:バインディングがターゲットとするGodot APIバージョン(4.3から4.7、デフォルト)。target:template_debug(デフォルト)、template_release、またはeditor。
各組み合わせは一度ビルドされ、必要とするすべてのプロジェクトによって再利用されます。各拡張機能内でコンパイルされるのではなく。
GDExtensionは、依存関係を持つ別のC++プロジェクトになります。ConanCenterにある1,900以上のライブラリのいずれか、またはConanレシピで自分でパッケージ化したライブラリをgodot-cppの隣に追加でき、Conanはターゲットとするすべてのプラットフォームでそれらを一貫してビルドします。
実践例:10万個のパーティクルのスウォーム
この仕組みを実際に示すために、新しいSwarmノードを登録するGDExtensionを作成します。これは、マウスカーソルから逃げ、ウィンドウの端で跳ね返る10万個のパーティクルをシミュレートし、それらすべてをGodotシーンに描画します。
シミュレーションは、CおよびC++向けのEntity Component System (ECS)ライブラリであるflecsで実行されます。ECSでは、エンティティはプレーンなIDであり、コンポーネントはそれらにアタッチされたプレーンなデータ構造であり、システムは指定されたコンポーネントセットを持つすべてのエンティティに対して実行される関数です。同じタイプのコンポーネントはメモリ内で一緒に格納されるため、多数のエンティティのイテレーションが非常に高速になります。そのため、ECSはシミュレーション、群衆、または弾幕シューティングゲームで人気のある選択肢となっています。また、ネイティブコードが効果を発揮する種類の作業でもあり、毎フレームこれほど多くのエンティティを更新するのは、GDScriptよりもC++の方がはるかに高速です。
完全な例はConan examples2リポジトリで見つけることができます。
$ git clone https://github.com/conan-io/examples2.git
$ cd examples2/examples/libraries/godot-cpp/gdextension
srcフォルダには拡張機能のコードが含まれており、demoはそれをロードする通常のGodotプロジェクトです。
依存関係の宣言
conanfile.pyは、ConanCenterからgodot-cppとflecsを要求します。
from conan import ConanFile
from conan.tools.cmake import CMake, CMakeToolchain, cmake_layout
class GDExtensionExample(ConanFile):
package_type = "shared-library"
settings = "os", "compiler", "build_type", "arch"
generators = "CMakeDeps"
def requirements(self):
self.requires("godot-cpp/10.0.0")
self.requires("flecs/4.1.6")
def layout(self):
cmake_layout(self)
def generate(self):
tc = CMakeToolchain(self)
# Godotはビルド "target" によってロードするライブラリを選択するため、
# 出力名をgodot-cppがビルドされたtargetの名前に合わせます
tc.cache_variables["GODOTCPP_TARGET"] = str(self.dependencies["godot-cpp"].options.target)
tc.generate()
def build(self):
cmake = CMake(self)
cmake.configure()
cmake.build()
Godot固有の詳細はgenerate()にあります。godot-cpp依存関係のtargetオプションを読み取り、CMakeに渡すため、ライブラリ名は常にリンクされたgodot-cppバイナリと一致します。
CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(gdexample LANGUAGES CXX)
find_package(godot-cpp REQUIRED CONFIG)
find_package(flecs REQUIRED CONFIG)
add_library(gdexample SHARED
src/register_types.cpp
src/swarm.cpp
)
target_link_libraries(gdexample PRIVATE godot-cpp flecs::flecs_static)
# demo/bin/libgdexample.<target>.<ext> として出力します。
# これは demo/bin/gdexample.gdextension が Godot に指示するパスです。
# ジェネレーター式は、マルチコンフィグジェネレーターが Release/ サブフォルダを追加するのを防ぎます
set_target_properties(gdexample PROPERTIES
OUTPUT_NAME "gdexample.${GODOTCPP_TARGET}"
PREFIX "lib"
LIBRARY_OUTPUT_DIRECTORY "$<1:${CMAKE_SOURCE_DIR}/demo/bin>"
RUNTIME_OUTPUT_DIRECTORY "$<1:${CMAKE_SOURCE_DIR}/demo/bin>"
)
これは完全に標準的なCMakeプロジェクトです。拡張機能は、godot-cppとflecsを静的にリンクする共有ライブラリであり、配布する単一のライブラリファイルがあります。Godotが追加のコピー手順なしで見つけられるように、demo/binに直接書き込みます。
ノードの記述
SwarmクラスはNode2Dを継承し、flecsの世界を所有します。各パーティクルのコンポーネントはプレーンな構造体です。GDCLASSマクロは、Godotのクラスシステムが必要とする定型コードを追加し、_bind_methods()は、Godotが認識できるもの、ここではcountとflee_radiusプロパティを宣言します。クラスが登録されると、これらはインスペクターに表示され、GDScriptから使用できるようになります。これはクラスの簡略化されたビューです。
struct Position { float x, y; };
struct Velocity { float x, y; };
class Swarm : public Node2D {
GDCLASS(Swarm, Node2D)
int count = 100000;
double flee_radius = 150.0;
flecs::world world;
...
protected:
static void _bind_methods() {
ClassDB::bind_method(D_METHOD("set_count", "count"), &Swarm::set_count);
ClassDB::bind_method(D_METHOD("get_count"), &Swarm::get_count);
ADD_PROPERTY(PropertyInfo(Variant::INT, "count"), "set_count", "get_count");
// ... flee_radius についても同様
}
...
};
ノードの残りの部分は、両方の世界を接続します。_ready()は、パーティクルごとに1つのflecsエンティティと、それらを更新するflecsシステムを作成します。また、MultiMeshをセットアップします。これは、10万個のパーティクルすべてに対して1つのGodotノードでは重すぎるため、単一の描画呼び出しで同じメッシュの多数のインスタンスを描画します。
毎フレーム、_process()はマウスの位置をflecsに渡し、システムをworld.progress()で実行し、結果の位置をMultiMeshにコピーバックします。これも簡略化されたビューであり、完全なコードはリポジトリにあります。
void Swarm::_ready() {
// 各パーティクルに Position と Velocity コンポーネントを持つエンティティを作成
for (int i = 0; i < count; i++) {
world.entity().set<Position>({ ... }).set<Velocity>({ ... });
}
// 両方のコンポーネントを持つすべてのエンティティに対して実行されるシステム
world.system<Position, Velocity>("Move").each([this](flecs::iter &it, size_t, Position &p, Velocity &v) {
// マウスから逃げ、移動し、ウィンドウの端で跳ね返る
});
// すべてのエンティティの位置を描画する MultiMeshInstance2D 子ノード
...
}
void Swarm::_process(double p_delta) {
mouse = get_local_mouse_position();
world.progress(static_cast<float>(p_delta));
// 各エンティティの位置を MultiMesh バッファにコピー
render_query.each([&](const Position &p, const Velocity &v) { ... });
multimesh->set_buffer(buffer);
}
拡張機能の登録
最後に、register_types.cppは、Godotがライブラリをロードするときにクラスを登録します。
void initialize_gdexample_module(ModuleInitializationLevel p_level) {
if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
return;
}
GDREGISTER_RUNTIME_CLASS(Swarm);
}
GDREGISTER_RUNTIME_CLASSを使用してSwarmを登録します。デフォルトでは、GDExtensionクラスのコードはエディター内でも実行されるため、_ready()と_process()はシーンを編集中にシミュレーションを開始します。ランタイムクラスはエディター内のプレースホルダーにすぎません。シーンに追加してプロパティを設定できますが、コードはゲームが実行されているときにのみ実行されます。
同じファイルが、.gdextensionファイルで指定されたエントリポイントであるgdexample_library_init()を定義します。これは、すべての拡張機能で同じように見える数行の定型コードです。
ビルドと実行
すべてが整ったら、拡張機能のビルドは1つのコマンドで完了します。
$ conan build . --build=missing
...
[100%] Linking CXX shared library .../demo/bin/libgdexample.template_debug.dylib
[100%] Built target gdexample
Conanはgodot-cppとflecsを解決し、存在する場合はConanCenterから事前コンパイルされたバイナリをダウンロードし、残りをソースからビルドし、CMake統合を生成し、最後に拡張機能をビルドします。
注意: godot-cppはC++17を必要とします。デフォルトのプロファイルが古い標準を使用している場合(MSVCの場合)、コマンドに
-s compiler.cppstd=17を追加してください。
これでGodot 4.7を起動し、プロジェクトマネージャーで「インポート」をクリックし、demo/project.godotを選択します。プロジェクトが開くと、Godotはbin/gdexample.gdextensionを読み込み、ライブラリをロードし、Swarmは組み込みノードと同様に利用可能になります。組み込みノードと同様に、「新しいノードの作成」ダイアログのNode2Dの下で見つけることができます。
[画像: Godotの「新しいノードの作成」ダイアログで、Node2Dの下にSwarmクラスが表示されている様子]
デモのメインシーンにはすでにSwarmノードが含まれています。それを選択すると、_bind_methods()でバインドした2つのプロパティであるcountとflee_radiusがインスペクターに表示されます。
[画像: GodotエディターでSwarmノードが選択され、インスペクターにCountとFlee Radiusプロパティが表示されている様子]
Playを押してシーンを実行し、マウスをウィンドウ上で動かしてパーティクルを操作します。その後停止し、インスペクターでcountまたはflee_radiusを変更して再度実行し、スウォームがより多くのパーティクルまたはより広い逃走半径でどのように動作するかを確認します。
結論
GDExtensionとgodot-cppを使用すると、エンジンクラスをC++で記述でき、Conanはgodot-cppおよび拡張機能が必要とするその他のC++ライブラリのビルドを処理します。これは、拡張機能を配布する際にも大きな利点となります。配布するすべてのプラットフォーム向けにビルドするには、ビルドの設定を変更するだけで済みます。
Linux向け注意: デフォルトでは、拡張機能は
libstdc++を動的にリンクするため、ターゲットシステムはビルドに使用されたものと同等以上の新しいバージョンを提供する必要があります。幅広い互換性のために、ビルドする拡張機能とその依存関係を、サポートを意図する最も古いディストリビューションと互換性のあるツールチェーンとシステムライブラリに対してビルドしてください。あるいは、libstdc++を静的にリンクし、リンカバージョン スクリプトでシンボルを非表示にしてください。
完全な例を試して、拡張機能の記述についてさらに学ぶためにgodot-cppドキュメントを確認してください。フィードバックがある場合や問題が発生した場合は、Conan GitHubリポジトリでお知らせください。
ハッピーゲーム開発を!
この記事はAI支援を受けて作成され、人間によってレビューされました。