redot-cpp

Warning

This repository's master branch is only usable with GDExtension from Redot's master branch.

This repository contains the C++ bindings for the Redot Engine's GDExtensions API.

• Versioning
• Compatibility
• Contributing
• Getting started
• Examples and templates

Versioning

This repositories follows the same branch versioning as the main Redot Engine repository:

• master tracks the current GDExtension development branch for the next Redot 4.x minor release.
• Other versioned branches (e.g. 4.3) track the latest stable release in the corresponding branch.

Stable releases are also tagged on this repository: Tags.

For any project built against a stable release of Redot, we recommend using this repository as a Git submodule, checking out the specific tag matching your Redot version.

As the master branch of Redot is constantly getting updated, if you are using redot-cpp against a more current version of Redot, see the instructions in the gdextension folder to update the relevant files.

Compatibility

GDExtensions targeting an earlier version of Redot or Godot should work in later minor versions, but not vice-versa. For example, a GDExtension targeting Godot 4.2 should work just fine in Redot/Godot 4.3, but one targeting Redot/Godot 4.3 won't work in Godot 4.2.

There is one exception to this: extensions targeting Godot 4.0 will not work with Godot 4.1 and later. See Updating your GDExtension for 4.1.

GDExtensions targeting any Redot version may not run on any Godot version.

Contributing

We greatly appreciate help in maintaining and extending this project. If you wish to help out, ensure you have an account on GitHub and create a "fork" of this repository. See Pull request workflow for instructions.

Please install clang-format and the pre-commit Python framework so formatting is done before your changes are submitted. See the code style guidelines for instructions.

Getting started

You need the same C++ pre-requisites installed that are required for the redot-engine repository. Follow the official build instructions for your target platform.

Getting started with GDExtensions is a bit similar to what it was for Godot 3.x but also a bit different.

This new approach is much more akin to how core Redot modules are structured.

Compiling this repository generates a static library to be linked with your shared lib, just like before.

To use the shared lib in your Redot project you'll need a .gdextension file, which replaces what was the .gdnlib before. See example.gdextension used in the test project:

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = "4.1"

[libraries]

macos.debug = "res://bin/libgdexample.macos.debug.framework"
macos.release = "res://bin/libgdexample.macos.release.framework"
windows.debug.x86_64 = "res://bin/libgdexample.windows.debug.x86_64.dll"
windows.release.x86_64 = "res://bin/libgdexample.windows.release.x86_64.dll"
linux.debug.x86_64 = "res://bin/libgdexample.linux.debug.x86_64.so"
linux.release.x86_64 = "res://bin/libgdexample.linux.release.x86_64.so"
# Repeat for other architectures to support arm64, rv64, etc.

The entry_symbol is the name of the function that initializes your library. It should be similar to following layout:

extern "C" {

// Initialization.

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
	godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

	init_obj.register_initializer(initialize_example_module);
	init_obj.register_terminator(uninitialize_example_module);
	init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

	return init_obj.init();
}
}

The initialize_example_module() should register the classes in ClassDB, very like a Redot module would do.

using namespace godot;
void initialize_example_module(ModuleInitializationLevel p_level) {
	if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
		return;
	}
	GDREGISTER_CLASS(Example);
}

Any node and resource you register will be available in the corresponding Create... dialog. Any class will be available to scripting as well.

Examples and templates

See the redot-cpp-template project for a generic reusable template.

Or checkout the code for the Summator example as shown in the official documentation.