Attention

You are reading the latest (unstable) version of this documentation, which may document features not available or compatible with Godot 3.x.

Checking the stable version of the documentation...

Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

Custom modules in C++¶

Modules¶

Godot allows extending the engine in a modular way. New modules can be created and then enabled/disabled. This allows for adding new engine functionality at every level without modifying the core, which can be split for use and reuse in different modules.

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.

What for?¶

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:

Binding an external library to Godot (like PhysX, FMOD, etc).
Optimize critical parts of a game.
Adding new functionality to the engine and/or editor.
Porting an existing game to Godot.
Write a whole, new game in C++ because you can't live without C++.

Creating a new module¶

Before creating a module, make sure to download the source code of Godot and compile it.

To create a new module, the first step is creating a directory inside modules/. If you want to maintain the module separately, you can checkout a different VCS into modules and use it.

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

And then the cpp file.

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