Benutzerdefinierte Module in C++

Module

Godot ermöglicht den modularen Ausbau der Engine. Neue Module können erstellt und dann aktiviert bzw. deaktiviert werden. Dies ermöglicht das Hinzufügen neuer Enginefunktionen auf jeder Ebene ohne den Kern zu ändern, der zur Verwendung und Wiederverwendung in verschiedenen Modulen aufgeteilt werden kann.

Module befinden sich im Unterverzeichnis modules/ des Build-Systems. Standardmäßig sind Dutzende von Modulen aktiviert, z.B. GDScript (das ja nicht Teil der Basis-Engine ist), die Mono-Laufzeit, ein Modul für reguläre Ausdrücke und andere. Es können beliebig viele neue Module erstellt und kombiniert werden. Das SCons-Build-System kümmert sich transparent darum.

Wofür?

Es wird zwar empfohlen den größten Teil eines Spiels in Skripten zu schreiben (da dies eine enorme Zeitersparnis bedeutet), es ist jedoch durchaus möglich stattdessen C++ zu verwenden. Das Hinzufügen von C++ - Modulen kann in den folgenden Szenarien hilfreich sein:

  • Binden einer externen Bibliothek an Godot (wie PhysX, FMOD usw.).
  • Optimieren kritischer Teile eines Spiels.
  • Hinzufügen neuer Funktionen zur Engine oder zum Editor.
  • Portieren eines vorhandenen Spiels.
  • Schreiben eines ganz neuen Spiels in C++, weil Sie ohne C++ nicht leben können.

Neues Modul erstellen

Stellen Sie vor dem Erstellen eines Moduls sicher, dass Sie den Quellcode von Godot herunterladen und kompilieren. In der Dokumentation dazu finden Sie Anleitungen.

Um ein neues Modul zu erstellen müssen Sie zunächst ein Verzeichnis in modules/ erstellen. Wenn Sie das Modul separat warten möchten, können Sie ein anderes VCS in Module auschecken und verwenden.

Das Beispielmodul heißt "summator" und befindet sich im Godot-Quellbaum (C:\godot zeigt auf diese Godot-Quellen):

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

Im Inneren erstellen wir eine einfache Summator-Klasse:

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

Und dann die cpp Datei.

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

Dann muss die neue Klasse irgendwie registriert werden, sodass zwei weitere Dateien erstellt werden müssen:

register_types.h
register_types.cpp

Wichtig

These files must be in the top-level folder of your module (next to your SCsub and config.py files) for the module to be registered properly.

Diese Dateien sollten Folgendes enthalten:

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

Next, we need to create a SCsub file so the build system compiles this module:

# SCsub

Import('env')

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

Bei mehreren Quellen können Sie jede Datei auch einzeln zu einer Python-Zeichenfolgenliste hinzufügen:

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

Dies erlaubt leistungsstarke Möglichkeiten mit Python, die Dateiliste mithilfe von Schleifen und logischen Anweisungen zu erstellen. Schauen Sie sich einige Module an, die standardmäßig mit Godot geliefert werden.

Um Include-Verzeichnisse hinzuzufügen, die der Compiler anzeigen kann, können Sie sie an die Pfade der Umgebung anhängen:

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

If you want to add custom compiler flags when building your module, you need to clone env first, so it won't add those flags to whole Godot build (which can cause errors). Example SCsub with custom flags:

# 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

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

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

Und das ist es, hoffentlich war es nicht zu komplex. Ihr Modul sollte folgendermaßen aussehen:

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

Sie können es dann komprimieren und das Modul mit allen anderen teilen. Beim Erstellen für jede Plattform (Anweisungen in den vorherigen Abschnitten) wird Ihr Modul einbezogen.

Bemerkung

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.

Modul verwenden

Sie können Ihr neu erstelltes Modul jetzt in jedem Skript verwenden:

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

Die Ausgabe wird 60 sein.

Siehe auch

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

Warnung

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.

Ein Modul extern kompilieren

Compiling a module involves moving the module's sources directly under the engine's modules/ directory. While this is the most straightforward way to compile a module, there are a couple of reasons as to why this might not be a practical thing to do:

  1. Having to manually copy modules sources every time you want to compile the engine with or without the module, or taking additional steps needed to manually disable a module during compilation with a build option similar to module_summator_enabled=no. Creating symbolic links may also be a solution, but you may additionally need to overcome OS restrictions like needing the symbolic link privilege if doing this via script.
  2. Depending on whether you have to work with the engine's source code, the module files added directly to modules/ changes the working tree to the point where using a VCS (like git) proves to be cumbersome as you need to make sure that only the engine-related code is committed by filtering changes.

So if you feel like the independent structure of custom modules is needed, lets take our "summator" module and move it to the engine's parent directory:

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

Compile the engine with our module by providing custom_modules build option which accepts a comma-separated list of directory paths containing custom C++ modules, similar to the following:

scons custom_modules=../modules

The build system shall detect all modules under the ../modules directory and compile them accordingly, including our "summator" module.

Warnung

Any path passed to custom_modules will be converted to an absolute path internally as a way to distinguish between custom and built-in modules. It means that things like generating module documentation may rely on a specific path structure on your machine.

Verbesserung des Build-Systems für die Entwicklung

Bisher haben wir einen sauberen und einfachen SCsub definiert mit dem wir die Quellen unseres neuen Moduls als Teil der Godot-Binärdatei hinzufügen können.

Dieser statische Ansatz ist in Ordnung, wenn wir eine Release-Version unseres Spiels erstellen möchten, in der alle Module in einer einzigen Binärdatei sind.

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.

The solution to avoid such a cost is to build our own module as a shared library that will be dynamically loaded when starting our game's binary.

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

Bemerkung

You have to export the environment 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.

Schließlich können Sie den Build sogar noch weiter beschleunigen, indem Sie Ihr freigegebenes Modul im Befehl SCons explizit als Ziel angeben:

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

Benutzerdefinierte Dokumentation schreiben

Writing documentation may seem like a boring task, but it is highly recommended to document your newly created module in order 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!

Es gibt mehrere Schritte, um benutzerdefinierte Dokumente für das Modul einzurichten:

  1. Erstellen Sie ein neues Verzeichnis im Stammverzeichnis des Moduls. Der Verzeichnisname kann beliebig sein, aber wir werden in diesem Abschnitt den Namen doc_classes verwenden.

  2. Jetzt müssen wir config.py bearbeiten und das folgende Schnipsel hinzufügen:

    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.

Tipp

You can use Git to check if you have missed some of your classes by checking the untracked files with git status. For example:

user@host:~/godot$ git status

Beispielausgabe:

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. Jetzt können wir die Dokumentation erstellen:

We can do this via running Godot's doctool i.e. godot --doctool <path>, which will dump the engine API reference to the given <path> in XML format.

In our case we'll point it to the root of the cloned repository. You can point it to an another folder, and just copy over the files that you need.

Führen Sie den Befehl aus:

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

Now if you go to the godot/modules/summator/doc_classes folder, you will see that it contains a Summator.xml file, or any other classes, that you referenced in your get_doc_classes function.

Edit the file(s) following Beitrag zur Klassenreferenz and recompile the engine.

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.

If you change your module's API, you can also re-extract the docs, they will contain the things that you previously added. Of course if you point it to your godot folder, make sure you don't lose work by extracting older docs from an older engine build on top of the newer ones.

Note that if you don't have write access rights to your supplied <path>, you might encounter an error similar to the following:

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

Hinzufügen von benutzerdefinierten Editor-Symbolen

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 Editor Icons 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"

Zusammenfassend

Nicht vergessen:

  • 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.

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

  • If you inherit from Node (or any derived node type, such as Sprite), your new class will appear in the editor, in the inheritance tree in the "Add Node" dialog.
  • If you inherit from Resource, it will appear in the resource list, and all the exposed properties can be serialized when saved/loaded.
  • By this same logic, you can extend the Editor and almost any area of the engine.