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++ 模块

模块

Godot 允许通过模块化的方式对引擎进行扩展. 你可以创建新的模块, 然后启用/禁用它. 这允许在每个级别添加新的引擎功能, 而无需修改内核, 可以将其拆分以供在不同模块中使用和重用.

模块位于构建系统的 modules/ 子目录下. 默认情况下, 有几十个模块被启用, 如GDScript(是的, 它不是基础引擎的一部分), Mono运行时, 正则表达式模块和其他. 可以根据需要创建和组合尽可能多的新模块.SCons构建系统将清晰地处理它.

可以做什么？

尽管我们建议使用脚本编写游戏的大部分代码(因为这能够节省大量的时间), 但使用 C++ 进行开发也是完全可行的. 在以下情况下, 添加C ++模块可能会很有用:

• 将外部库绑定到 Godot（例如 PhysX、FMOD 等）。

• 优化游戏的核心部分。

• 为引擎和/或编辑器添加新功能。

• Porting an existing game to Godot.

• 使用 C++ 编写整个新游戏，因为你离不开 C++。

创建新模块

创建模块之前，请先下载 Godot 源代码并编译。

要创建一个新模块, 首先我们要在 modules/ 文件夹下创建一个新目录. 如果要单独维护模块, 则可以在版本控制系统(VCS)检出到模块中并使用它.

The example module will be called "summator" (godot/modules/summator). Inside we will create a summator class:

/* summator.h */

#ifndef SUMMATOR_H
#define SUMMATOR_H

#include "core/object/ref_counted.h"

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

    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;
}

然后, 需要以某种方式注册新类, 因此需要再创建两个文件:

register_types.h
register_types.cpp

重要

这些文件必须在您的模块的顶层文件夹中( SCsub 和 config.py 文件旁边), 这样模块才能被正确注册.

这些文件应包含以下内容:

/* register_types.h */

#include "modules/register_module_types.h"

void initialize_summator_module(ModuleInitializationLevel p_level);
void uninitialize_summator_module(ModuleInitializationLevel p_level);
/* yes, the word in the middle must be the same as the module folder name */

/* register_types.cpp */

#include "register_types.h"

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

void initialize_summator_module(ModuleInitializationLevel p_level) {
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
            return;
    }
    ClassDB::register_class<Summator>();
}

void uninitialize_summator_module(ModuleInitializationLevel p_level) {
    if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
            return;
    }
   // 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)

使用循环和逻辑语句, 这使得使用Python来构建文件列表有了强大的可行性. 请看Godot默认的一些模块的例子.

要添加供编译器查看的包含目录, 可以将其追加到环境的路径中:

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")
# Append CCFLAGS flags for both C and C++ code.
module_env.Append(CCFLAGS=['-O2'])
# If you need to, you can:
# - Append CFLAGS for C code only.
# - Append CXXFLAGS for C++ code only.

And finally, the configuration file for the module, this is a Python script that must be named config.py:

# config.py

def can_build(env, platform):
    return True

def configure(env):
    pass

询问模块是否可以针对特定平台进行构建(在这种情况下, True 表示它将针对每个平台进行构建).

就是这样. 希望它不太复杂！ 你的模块应如下所示:

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

然后, 你可以压缩它并与其他所有人分享该模块. 当针对每个平台进行构建时(上一节中的说明), 你的模块将包括在内.

备注

对于子类之类的东西,C ++模块中的参数限制为5. 通过包含头文件 core/method_bind_ext.gen.inc, 可以将其增加到13个.

使用模块

现在, 您可以通过任何脚本使用新创建的模块:

GDScript

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

输出将是 60 .

参见

前面的Summator例子对于小型的自定义模块来说是很好的, 但是如果你想使用一个更大的外部库呢？请参考 绑定到外部库, 了解有关绑定外部库的细节.

警告

如果要从正在运行的项目（而不仅仅是从编辑器）访问模块，则还必须重新编译计划使用的每个导出模板，然后在每个导出预设中指定自定义模板的路径。否则，由于未在导出模板中编译模块，因此在运行项目时会出现错误。更多信息见编译页面。

从外部编译模块

编译一个模块需要将模块的源代码直接移到引擎的 modules/ 目录下. 虽然这是最直接的编译模块的方法, 但是有几个原因说明为什么这样做不实用:

1. 每次编译引擎时, 不管有没有模块, 都必须手动复制模块源码, 或者在编译过程中使用类似 module_summator_enabled=no 的编译选项, 采取额外的步骤手动禁用模块. 创建符号链接也是一种解决方案, 但你可能还需要克服操作系统的限制, 比如如果通过脚本来做, 需要符号链接的权限.

2. 根据你是否需要使用引擎的源代码, 直接添加到 modules/ 的模块文件会改变工作树, 以至于使用VCS(比如 git )被证明是很麻烦的, 因为你需要通过过滤变化来确保只提交与引擎相关的代码.

所以, 如果你觉得需要自定义模块的独立结构, 把 "summator" 模块移到引擎的父目录下:

mkdir ../modules
mv modules/summator ../modules

通过提供 custom_modules 构建选项来编译我们的引擎, 该选项接受一个以逗号分隔的包含自定义C++模块的目录路径列表, 类似于下面:

scons custom_modules=../modules

构建系统将检测到 ./modules 目录下的所有模块并进行相应的编译, 包括 "summator" 模块.

警告

传递给 custom_modules 的任何路径都将在内部转换为绝对路径, 以区分自定义模块和内置模块, 这意味着像生成模块文档这样的事情可能会依赖于你机器上的特定路径结构.

参见

构建系统介绍 - 自定义模块构建选项.

Customizing module types initialization

Modules can interact with other built-in engine classes during runtime and even affect the way core types are initialized. So far, we've been using register_summator_types as a way to bring in module classes to be available within the engine.

A crude order of the engine setup can be summarized as a list of the following type registration methods:

preregister_module_types();
preregister_server_types();
register_core_singletons();
register_server_types();
register_scene_types();
EditorNode::register_editor_types();
register_platform_apis();
register_module_types();
initialize_physics();
initialize_navigation_server();
register_server_singletons();
register_driver_types();
ScriptServer::init_languages();

Our Summator class is initialized during the register_module_types() call. Imagine that we need to satisfy some common module run-time dependency (like singletons), or allow us to override existing engine method callbacks before they can be assigned by the engine itself. In that case, we want to ensure that our module classes are registered before any other built-in type.

This is where we can define an optional preregister_summator_types() method which will be called before anything else during the preregister_module_types() engine setup stage.

We now need to add this method to register_types header and source files:

/* register_types.h */

#define MODULE_SUMMATOR_HAS_PREREGISTER
void preregister_summator_types();

void register_summator_types();
void unregister_summator_types();

备注

Unlike other register methods, we have to explicitly define MODULE_SUMMATOR_HAS_PREREGISTER to let the build system know what relevant method calls to include at compile time. The module's name has to be converted to uppercase as well.

/* register_types.cpp */

#include "register_types.h"

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

void preregister_summator_types() {
    // Called before any other core types are registered.
    // Nothing to do here in this example.
}

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

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

改善开发的构建系统

警告

This shared library support is not designed to support distributing a module to other users without recompiling the engine. For that purpose, use a GDExtension instead.

到目前为止，我们定义了一个干净的 SCsub，让我们能够将新模块的源文件添加为 Godot 二进制文件的一部分。

那么当我们要构建游戏的发行版，并希望将所有模块都放在一个二进制文件中时，这种静态方法就很好。

然而，代价是每一个变化都意味着游戏的全面重新编译。即使 SCons 能够检测并重新编译已经改变的文件，找到这些文件并最终链接到最终的二进制文件会花费很长时间。

避免这种成本的解决方案是将我们自己的模块构建为共享库, 该库在启动游戏二进制文件时将动态加载.

# SCsub

Import('env')

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

# First, create a custom env for the shared library.
module_env = env.Clone()

# Position-independent code is required for a shared library.
module_env.Append(CCFLAGS=['-fPIC'])

# Don't inject Godot's dependencies into our shared library.
module_env['LIBS'] = []

# Define the shared library. By default, it would be built in 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 build environment it now has our shared library
# as a new dependency.

# LIBPATH and LIBS need to be set on the real "env" (not the clone)
# to link the specified libraries to the Godot executable.

env.Append(LIBPATH=['#bin'])

# SCons wants the name of the library with it custom suffixes
# (e.g. ".linuxbsd.tools.64") but without the final ".so".
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim])

一旦编译完成, 我们应该有一个 bin 目录, 其中包含 godot* 可执行文件和 libsummator*.so . 然而, 鉴于.so不在一个标准的目录中(如 /usr/lib ), 我们必须在运行时用 LD_LIBRARY_PATH 环境变量帮助可执行文件找到它:

export LD_LIBRARY_PATH="$PWD/bin/"
./bin/godot*

备注

你必须 export 这个环境变量，否则你将无法从编辑器中运行你的项目。

最重要的是，能够选择将我们的模块编译为共享库（用于开发）还是作为 Godot 二进制文件的一部分（用于发布）将是一件很不错的事情。为此，我们可以使用 ARGUMENT 命令定义要传递给 SCons 的自定义标志：

# SCsub

Import('env')

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

module_env = env.Clone()
module_env.Append(CCFLAGS=['-O2'])

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)

现在默认情况下, scons 命令会将我们的模块构建为Godot二进制文件的一部分, 并在传递 summator_shared=yes 时构建为共享库.

最后, 你甚至可以通过在SCons命令中明确指定你的共享模块为目标来进一步加快构建速度:

scons summator_shared=yes platform=linuxbsd bin/libsummator.linuxbsd.tools.64.so

编写自定义文档

Writing documentation may seem like a boring task, but it is highly recommended to document your newly created module to make it easier for users to benefit from it. Not to mention that the code you've written one year ago may become indistinguishable from the code that was written by someone else, so be kind to your future self!

为了设置模块的自定义文档, 有几个步骤:

1. 在模块的根目录中创建一个新目录. 目录名称可以是任何名称, 但是在本节中, 我们将使用 doc_classes 名称.

2. 现在, 我们需要编辑 config.py , 添加以下片段:

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

构建系统使用 get_doc_path() 函数来确定文档的位置. 在这种情况下, 它们将位于 modules/summator/doc_classes 目录下. 如果你不定义这个, 你的模块的文档路径将退回到主 doc/classes 目录.

get_doc_classes() 方法对于构建系统知道哪些注册的类属于该模块是必要的. 你需要在这里列出你所有的类. 你没有列出的类最终将出现主 doc/classes 目录中.

小技巧

你可以用 Git 来检查是否漏掉了一些类，用 git status 检查未跟踪的文件。例如：

user@host:~/godot$ git status

输出示例：

Untracked files:
    (use "git add <file>..." to include in what will be committed)

    doc/classes/MyClass2D.xml
    doc/classes/MyClass4D.xml
    doc/classes/MyClass5D.xml
    doc/classes/MyClass6D.xml
    ...

3. 现在我们可以生成文档:

我们可以通过运行Godot的doctool, 即 godot -doctool <path> , 它将以XML格式转储引擎API引用到给定的 <path> .

在我们的例子中, 将把它指向克隆的版本库的根目录. 你可以把它指向另一个文件夹, 然后复制需要的文件.

运行命令:

user@host:~/godot$ ./bin/<godot_binary> --doctool .

现在, 如果进入 godot/modules/summator/doc_classes 文件夹, 会看到它包含一个在 get_doc_classes 函数中引用的 Summator.xml 文件, 或者其他类.

Edit the file(s) following Class reference primer and recompile the engine.

一旦编译过程完成, 这些文档将可以在引擎的内置文档系统中访问.

为了保持文档的更新, 你所要做的就是简单地修改其中一个XML文件, 然后从现在开始重新编译引擎.

如果你改变了模块的API, 可以重新提取文档, 它们会包含你之前添加的东西. 当然如果你把它指向 godot 文件夹, 请确保不会因为在新的文档上提取旧引擎构建的旧文档而损失工作.

请注意, 如果你对提供的 <path> 没有写访问权限, 可能会遇到类似下面的错误:

ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
   At: editor/doc/doc_data.cpp:956

Writing custom unit tests

It's possible to write self-contained unit tests as part of a C++ module. If you are not familiar with the unit testing process in Godot yet, please refer to Unit testing.

The procedure is the following:

1. Create a new directory named tests/ under your module's root:

cd modules/summator
mkdir tests
cd tests

2. Create a new test suite: test_summator.h. The header must be prefixed with test_ so that the build system can collect it and include it as part of the tests/test_main.cpp where the tests are run.

3. Write some test cases. Here's an example:

// test_summator.h
#ifndef TEST_SUMMATOR_H
#define TEST_SUMMATOR_H

#include "tests/test_macros.h"

#include "modules/summator/summator.h"

namespace TestSummator {

TEST_CASE("[Modules][Summator] Adding numbers") {
    Ref<Summator> s = memnew(Summator);
    CHECK(s->get_total() == 0);

    s->add(10);
    CHECK(s->get_total() == 10);

    s->add(20);
    CHECK(s->get_total() == 30);

    s->add(30);
    CHECK(s->get_total() == 60);

    s->reset();
    CHECK(s->get_total() == 0);
}

} // namespace TestSummator

#endif // TEST_SUMMATOR_H

4. Compile the engine with scons tests=yes, and run the tests with the following command:

./bin/<godot_binary> --test --source-file="*test_summator*" --success

You should see the passing assertions now.

添加自定义编辑器图标

与如何在模块中编写独立的文档类似, 您也可以为类创建自己的自定义图标, 以使其出现在编辑器中.

有关创建要集成到引擎中的编辑器图标的实际过程, 首先请参考 编辑器图标.

创建图标后, 请执行以下步骤:

1. 在名为 icons 的模块的根目录中创建一个新目录. 这是引擎查找模块的编辑器图标的默认路径.

2. 将新创建的 svg 图标(已优化或未优化)移动到该文件夹中.

3. 重新编译引擎并运行编辑器. 现在, 相应的图标将出现在编辑器的界面中合适的位置中.

如果您想将图标存储在模块内的其他位置, 请将以下代码段添加到 config.py 以覆盖默认路径:

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

总结

记得:

• Use GDCLASS macro for inheritance, so Godot can wrap it.

• Use _bind_methods to bind your functions to scripting, and to allow them to work as callbacks for signals.

• Avoid multiple inheritance for classes exposed to Godot, as GDCLASS doesn't support this. You can still use multiple inheritance in your own classes as long as they're not exposed to Godot's scripting API.

但这还不是全部, 取决于您做什么, 您会得到一些(希望是积极的)惊喜.

• If you inherit from Node (or any derived node type, such as Sprite2D), your new class will appear in the editor, in the inheritance tree in the "Add Node" dialog.

• 如果你从 Resource 继承, 则它将出现在资源列表中, 并且所有暴露的属性在保存/加载时都可以序列化.

• 通过同样的逻辑, 你可以扩展编辑器, 以及引擎中几乎所有领域.