C++のカスタムモジュール

モジュール

Godotでは、モジュール方式でエンジンを拡張できます。新しいモジュールを作成してから、有効/無効にすることができます。これにより、コアを変更せずにすべてのレベルで新しいエンジン機能を追加できます。コアは別のモジュールで使用および再利用するために分割できます。

モジュールは、ビルド システムの modules/ サブディレクトリにあります。デフォルトでは、GDScript(これは基本エンジンの一部ではない)、Mono ランタイム、正規表現モジュールなど、多くの異なるモジュールが存在します。必要に応じて多くの新しいモジュールを作成して組み合わせることができ、SConsビルドシステムが透過的に使用します。

何のために?

While it's recommended that most of a game be written in scripting (as it is an enormous time saver), it's perfectly possible to use C++ instead. Adding C++ modules can be useful in the following scenarios:

  • 外部ライブラリをGodot にバインドする(PhysX、FMODなど)。
  • ゲームの重要な部分を最適化します。
  • エンジンまたはエディタに新しい機能を追加します。
  • 既存のゲームを移植します。
  • C++なしでは生きていけないので、C++で新しいゲームを書きましょう。

新しいモジュールの作成

モジュールを作成する前に、Godot のソースコードをダウンロードし、コンパイルに成功してください。このドキュメントにはチュートリアルがあります。

新しいモジュールを作成するには、最初のステップは modules/ 内にディレクトリを作成することです。モジュールを個別に保守する場合は、別のVCSをモジュールにチェックアウトして使用できます。

例のモジュールは「summator」と呼ばれ、Godot ソースツリー内に配置されます( C:\godot は Godot ソースが配置されている場所を指します):

C:\godot> cd modules
C:\godot\modules> mkdir summator
C:\godot\modules> cd summator
C:\godot\modules\summator>

内部では、単純なsummatorクラスを作成します:

/* summator.h */

#ifndef SUMMATOR_H
#define SUMMATOR_H

#include "core/reference.h"

class Summator : public Reference {
    GDCLASS(Summator, Reference);

    int count;

protected:
    static void _bind_methods();

public:
    void add(int p_value);
    void reset();
    int get_total() const;

    Summator();
};

#endif // SUMMATOR_H

それからcppファイル。

/* summator.cpp */

#include "summator.h"

void Summator::add(int p_value) {
    count += p_value;
}

void Summator::reset() {
    count = 0;
}

int Summator::get_total() const {
    return count;
}

void Summator::_bind_methods() {
    ClassDB::bind_method(D_METHOD("add", "value"), &Summator::add);
    ClassDB::bind_method(D_METHOD("reset"), &Summator::reset);
    ClassDB::bind_method(D_METHOD("get_total"), &Summator::get_total);
}

Summator::Summator() {
    count = 0;
}

次に、新しいクラスを何らかの方法で登録する必要があるので、さらに2つのファイルを作成する必要があります:

register_types.h
register_types.cpp

次の内容を使用します:

/* register_types.h */

void register_summator_types();
void unregister_summator_types();
/* yes, the word in the middle must be the same as the module folder name */
/* register_types.cpp */

#include "register_types.h"

#include "core/class_db.h"
#include "summator.h"

void register_summator_types() {
    ClassDB::register_class<Summator>();
}

void unregister_summator_types() {
   // Nothing to do here in this example.
}

次に、ビルドシステムがこのモジュールをコンパイルできるように SCsub ファイルを作成する必要があります:

# SCsub

Import('env')

env.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build

複数のソースを使用して、各ファイルをPython文字列リストに個別に追加することもできます:

src_list = ["summator.cpp", "other.cpp", "etc.cpp"]
env.add_source_files(env.modules_sources, src_list)

This allows for powerful possibilities using Python to construct the file list using loops and logic statements. Look at some of the other modules that ship with Godot by default for examples.

コンパイラが見るインクルードディレクトリを追加するには、環境のパスに追加します:

env.Append(CPPPATH=["mylib/include"]) # this is a relative path
env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path

モジュールのビルド時にカスタムコンパイラフラグを追加する場合は、最初に env のクローンを作成する必要があるので、これらのフラグはGodotビルド全体に追加されません(エラーが発生する可能性があります)。カスタムフラグを使用した SCsub の例:

# SCsub

Import('env')

module_env = env.Clone()
module_env.add_source_files(env.modules_sources, "*.cpp")
module_env.Append(CCFLAGS=['-O2']) # Flags for C and C++ code
module_env.Append(CXXFLAGS=['-std=c++11']) # Flags for C++ code only

最後に、モジュールの構成ファイルは、 config.py という名前を付けなければならない単純なPythonスクリプトです:

# config.py

def can_build(env, platform):
    return True

def configure(env):
    pass

The module is asked if it's OK to build for the specific platform (in this case, True means it will build for every platform).

以上です。あまり複雑でなければいいのですが。モジュールは次のようになります:

godot/modules/summator/config.py
godot/modules/summator/summator.h
godot/modules/summator/summator.cpp
godot/modules/summator/register_types.h
godot/modules/summator/register_types.cpp
godot/modules/summator/SCsub

その後、それを圧縮し、他の人とモジュールを共有することができます。すべてのプラットフォーム (前のセクションの手順)を構築する場合は、モジュールが含まれます。

注釈

There is a parameter limit of 5 in C++ modules for things such as subclasses. This can be raised to 13 by including the header file core/method_bind_ext.gen.inc.

モジュールの使用

You can now use your newly created module from any script:

var s = Summator.new()
s.add(10)
s.add(20)
s.add(30)
print(s.get_total())
s.reset()

出力は 60 になります。

参考

The previous Summator example is great for small, custom modules, but what if you want to use a larger, external library? Refer to Binding to external libraries for details about binding to external libraries.

警告

If your module is meant to be accessed from the running project (not just from the editor), you must also recompile every export template you plan to use, then specify the path to the custom template in each export preset. Otherwise, you'll get errors when running the project as the module isn't compiled in the export template. See the Compiling pages for more information.

開発のためのビルドシステムの改善

ここまでは、Godotバイナリの一部として新しいモジュールのソースを追加できるクリーンでシンプルなSCsubを定義しました。

この静的なアプローチは、すべてのモジュールを1つのバイナリにしたい場合に、ゲームのリリースバージョンを構築したいときに適しています。

However the trade-off is every single change means a full recompilation of the game. Even if SCons is able to detect and recompile only the file that have changed, finding such files and eventually linking the final binary is a long and costly part.

このようなコストを回避するソリューションは、ゲームのバイナリを起動するときに動的に読み込まれる共有ライブラリとして独自のモジュールを構築することです。

# SCsub

Import('env')

sources = [
    "register_types.cpp",
    "summator.cpp"
]

# First, create a custom env for the shared library.
module_env = env.Clone()
module_env.Append(CCFLAGS=['-fPIC'])  # Needed to compile shared library
# We don't want godot's dependencies to be injected into our shared library.
module_env['LIBS'] = []

# Now define the shared library. Note that by default it would be built
# into the module's folder, however it's better to output it into `bin`
# next to the Godot binary.
shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)

# Finally notify the main env it has our shared lirary as a new dependency.
# To do so, SCons wants the name of the lib with it custom suffixes
# (e.g. ".x11.tools.64") but without the final ".so".
# We pass this along with the directory of our library to the main env.
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim])
env.Append(LIBPATH=['#bin'])

コンパイルしたら、 godot* バイナリと libsummator* .so の両方を含む bin ディレクトリになります。 ただし、「.so」が標準ディレクトリ( /usr/lib など)にない場合、 LD_LIBRARY_PATH 環境変数を使用して、実行時にバイナリを見つける必要があります:

user@host:~/godot$ export LD_LIBRARY_PATH=`pwd`/bin/
user@host:~/godot$ ./bin/godot*

note: Pay attention you have to export the environ variable otherwise you won't be able to play your project from within the editor.

On top of that, it would be nice to be able to select whether to compile our module as shared library (for development) or as a part of the Godot binary (for release). To do that we can define a custom flag to be passed to SCons using the ARGUMENT command:

# SCsub

Import('env')

sources = [
    "register_types.cpp",
    "summator.cpp"
]

module_env = env.Clone()
module_env.Append(CCFLAGS=['-O2'])
module_env.Append(CXXFLAGS=['-std=c++11'])

if ARGUMENTS.get('summator_shared', 'no') == 'yes':
    # Shared lib compilation
    module_env.Append(CCFLAGS=['-fPIC'])
    module_env['LIBS'] = []
    shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
    shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
    env.Append(LIBS=[shared_lib_shim])
    env.Append(LIBPATH=['#bin'])
else:
    # Static compilation
    module_env.add_source_files(env.modules_sources, sources)

Now by default scons command will build our module as part of Godot's binary and as a shared library when passing summator_shared=yes.

最後に、共有モジュールを scons コマンドのターゲットとして明示的に指定することで、ビルドをさらに高速化することもできます:

user@host:~/godot$ scons summator_shared=yes platform=x11 bin/libsummator.x11.tools.64.so

カスタムドキュメントの作成

ドキュメントを書くのは退屈な作業のように思えるかもしれませんが、ユーザーが役立てやすくするために、新しく作成したモジュールを文書化することを強くお勧めします。1年前に書いたコードは、他の人が書いたコードと区別がつかないかもしれないので、将来の自分に親切にしてください!

モジュールのカスタムドキュメントをセットアップするには、いくつかの手順があります:

  1. モジュールのルートに新しいディレクトリを作成します。ディレクトリ名は何でもかまいませんが、このセクションでは doc_classes という名前を使用します。

  2. 次のコードスニペットを config.py に追加します:

    def get_doc_classes():
        return [
            "ClassName",
        ]
    
    def get_doc_path():
        return "doc_classes"
    

get_doc_classes() メソッドは、モジュールに複数のクラスが含まれている可能性があるため、モジュールのどのドキュメントクラスをマージする必要があるかをビルドシステムが知るために必要です。 ClassName をドキュメントを作成するクラスの名前に置き換えます。複数のクラスのドキュメントが必要な場合は、追加します。

get_doc_path() メソッドは、ドキュメントの場所を決定するためにビルド システムで使用されます。この例では、 doc_classes ディレクトリに配置されます。

  1. コマンドの実行:

    godot --doctool <path>
    

これは、指定された <path> へのエンジンAPIリファレンスをXML形式でダンプします。 Godotの実行可能ファイルを見つけるために PATH を設定し、書き込みアクセス権があることを確認する必要があることに注意してください。 そうでない場合は、次のようなエラーが発生する可能性があります:

ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
   At: editor/doc/doc_data.cpp:956
  1. godot/doc/classes/ClassName.xml から生成されたドキュメントファイルを取得します
  2. このファイルを doc_classes にコピーし、オプションで編集してからエンジンをコンパイルします。

ビルドシステムは、 doc_classes ディレクトリからドキュメントファイルをフェッチし、基本型とマージします。コンパイルプロセスが完了すると、ドキュメントはエンジンの組み込みドキュメントシステム内でアクセスできるようになります。

ドキュメントを最新の状態に保つために必要なことは、単に ClassName.xml ファイルの1つを変更し、エンジンを再コンパイルすることだけです。

カスタムエディタアイコンの追加

Similarly to how you can write self-contained documentation within a module, you can also create your own custom icons for classes to appear in the editor.

For the actual process of creating editor icons to be integrated within the engine, please refer to エディタアイコン first.

Once you've created your icon(s), proceed with the following steps:

  1. Make a new directory in the root of the module named icons. This is the default path for the engine to look for module's editor icons.
  2. Move your newly created svg icons (optimized or not) into that folder.
  3. Recompile the engine and run the editor. Now the icon(s) will appear in editor's interface where appropriate.

If you'd like to store your icons somewhere else within your module, add the following code snippet to config.py to override the default path:

def get_icons_path():
    return "path/to/icons"

まとめ

Remember to:

  • 継承に GDCLASS マクロを使用するので、Godotはそれをラップできます
  • 関数をスクリプトにバインドし、シグナルのコールバックとして機能できるようにするには、 _bind_methods を使用します。

But this is not all, depending what you do, you will be greeted with some (hopefully positive) surprises.

  • class_Node (またはSpriteなどの派生ノードタイプ) から継承すると、新しいクラスがエディタに表示され、「ノードの追加」ダイアログボックスの継承ツリーに表示されます。
  • class_Resourceから継承すると、リソース リストに表示され、公開されているすべてのプロパティは、保存/読み込み時にシリアル化できます。
  • この同じロジックによって、エディタとエンジンのほぼすべての領域を拡張できます。