自定义C++模块

模块(Modules)

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

Modules are located in the modules/ subdirectory of the build system. By default, dozens of modules are enabled, such as GDScript (which, yes, is not part of the base engine), the Mono runtime, a regular expressions module, and others. As many new modules as desired can be created and combined. The SCons build system will take care of it transparently.

可以做什么?

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

  • 将外部库绑定到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;
}

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

register_types.h
register_types.cpp

重要

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

These files should contain the following:

/* 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 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

最后是模块的配置文件,这是一个简单的python脚本,必须命名为 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个。

使用模块

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

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

The output will be 60.

参见

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

警告

如果要从正在运行的项目(而不仅仅是从编辑器)访问模块,则还必须重新编译计划使用的每个导出模板,然后在每个导出预设中指定自定义模板的路径。 否则,由于未在导出模板中编译模块,因此在运行项目时会出现错误。 有关更多信息,请参见:编译`Compiling <toc-devel-compiling>`页面。

从外部编译模块

编译一个模块需要将模块的源代码直接移到引擎的 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 的任何路径都将在内部转换为绝对路径,以区分自定义模块和内置模块,这意味着像生成模块文档这样的事情可能会依赖于你机器上的特定路径结构。

改善开发的构建系统

到目前为止,我们定义了一个干净简单的SCsub,它允许我们将新模块的源文件添加为Godot二进制文件的一部分。

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

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()

# 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. ".x11.tools.64") but without the final ".so".
shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
env.Append(LIBS=[shared_lib_shim])

Once compiled, we should end up with a bin directory containing both the godot* binary and our libsummator*.so. However given the .so is not in a standard directory (like /usr/lib), we have to help our binary find it during runtime with the LD_LIBRARY_PATH environment variable:

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

注解

You have to export the environment variable otherwise you won't be able to play your project from within the editor.

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

# 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)

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

Finally, you can even speed up the build further by explicitly specifying your shared module as target in the SCons command:

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

编写自定义文档

编写文档看起来可能是一项无聊的任务,但仍然强烈建议您为新创建的模块编写文档,以便使用这个模块的其他人从中受益。更不用说,您一年后可能与无法区分它与其他人写的代码,所以对未来的您自己好一点吧!

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

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

  2. Now, we need to edit config.py, add the following snippet:

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

The get_doc_path() function is used by the build system to determine the location of the docs. In this case, they will be located in the modules/summator/doc_classes directory. If you don't define this, the doc path for your module will fall back to the main doc/classes directory.

The get_doc_classes() method is necessary for the build system to know which registered classes belong to the module. You need to list all of your classes here. The classes that you don't list will end up in the main doc/classes directory.

小技巧

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

user@host:~/godot$ git status

Example output:

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
    ...
  1. Now we can generate the documentation:

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

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

运行命令:

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

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

编译以下文件:ref:doc_updating_the_class_reference 并重新编译引擎。

Once the compilation process is finished, the docs will become accessible within the engine's built-in documentation system.

In order to keep documentation up-to-date, all you'll have to do is simply modify one of the XML files and recompile the engine from now on.

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

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

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

添加自定义编辑器图标

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

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

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

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

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

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

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

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

总结

记得:

  • 对于继承使用 GDCLASS 宏,因此Godot可以封装它

  • 使用 _bind_methods 将您的函数绑定到脚本,并允许它们充当信号的回调。

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

  • 如果从 Node (或任何派生的节点类型,例如Sprite)继承,则新类将显示在编辑器的“添加节点”对话框的继承树中。

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

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