自定义C++模块

模块(Modules)

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

模块位于构建系统的 modules/ 子目录中。默认情况下,存在许多不同的模块,例如GDScript(是,它不是基本引擎的一部分)、Mono运行时、正则表达式模块等。 可以创建和组合任意数量的新模块,SCons构建系统将透明地处理该模块。

可以做什么?

尽管我们建议使用脚本编写游戏的大部分代码(因为这能够节省大量的时间),但使用 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

具有以下内容:

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

这提供了使用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")
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

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

注解

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.

使用模块

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

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.

警告

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.

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/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.
}

改善开发的构建系统

到目前为止,我们定义了一个干净简单的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()
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'])

编译完成后,在 bin 目录下可以找到 godot* 可执行文件和 我们的模块库 libsummator*.so。但是,鉴于 .so 文件不在标准目录(如 /usr/lib)中,我们必须使用 LD_LIBRARY_PATH 环境变量帮助二进制文件在运行时找到它:

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

注意:请注意,您必须 export 该环境变量,否则将无法在编辑器中启动项目。

最重要的是,能够选择将我们的模块编译为共享库(用于开发)还是作为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 时构建为共享库。

最后,您甚至可以通过在scons命令中将共享模块显式指定为目标来进一步加快构建速度:

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

编写自定义文档

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

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

  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>
    

这会将引擎API参考以XML格式转储到给定的 <path> 中。请注意,您需要配置 PATH 以找到Godot的可执行文件,并确保您具有写访问权。否则您可能会遇到类似于以下错误:

ERROR: Can't write doc file: docs/doc/classes/@GDScript.xml
   At: editor/doc/doc_data.cpp:956
  1. godot/doc/classes/ClassName.xml 获取生成的doc文件
  2. 将此文件复制到 doc_classes,可以选择对其进行编辑,然后编译引擎。

构建系统将从 doc_classes 目录中获取文档文件,并将其与基本类型合并。编译过程完成后,即可在引擎的内置文档系统中访问文档。

为了使文档保持最新,从现在开始您所要做的就是,每当简单地修改其中一个 ClassName.xml 文件,就重新编译引擎。

添加自定义编辑器图标

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

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

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

  1. 在名为 icons 的模块的根目录中创建一个新目录。这是引擎查找模块的编辑器图标的默认路径。
  2. 将新创建的 svg 图标(已优化或未优化)移动到该文件夹中。
  3. 重新编译引擎并运行编辑器。现在,相应的图标将出现在编辑器的界面中合适的位置中。

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

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

总结

记得:

  • 对于继承使用 GDCLASS 宏,因此Godot可以封装它
  • 使用 _bind_methods 将您的函数绑定到脚本,并允许它们充当信号的回调。

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

  • 如果从 class_Node (或任何派生的节点类型,例如Sprite)继承,则新类将显示在编辑器的“添加节点”对话框的继承树中。
  • 如果您从 class_Resource 继承,则它将出现在资源列表中,并且所有暴露的属性在保存/加载时都可以序列化。
  • 通过同样的逻辑,您可以扩展编辑器,以及引擎中几乎所有领域。