godot-cpp

Note

For GDNative (Godot 3.x), switch to the 3.x or the 3.6 branch.

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

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

Versioning

Warning

The master branch of godot-cpp (version 10.x) is currently in Beta. You may prefer to choose a previous version to build on top of instead:

• 4.5
• godot-4.5-stable
• 3.x

Starting with version 10.x, godot-cpp is versioned independently from Godot. The godot-cpp version you choose has no bearing on which Godot versions it is compatible with.

Until we have a stable release branch, you can use the master branch, or choose any of the previous version branches and tags for your project.

Compatibility

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

You can specify which version you are targeting with the api_version option:

scons api_version=4.3

... or by providing a custom extension_api.json generated by the Godot version you are targeting:

godot --dump-extension-api
scons custom_api_file=extension_api.json

If you don't provide api_version or custom_api_file, then, by default, godot-cpp will target the latest stable Godot version that it's aware of.

Contributing

We greatly appreciate help in maintaining and extending this project. If you wish to help out, please visit the godot-cpp section of the Contributing docs.

Getting started

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

Building your extension will create a shared library. To use this in your Godot project you'll need a .gdextension file, for example:

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

See the example.gdextension used in the template project for a complete example.

The entry_symbol is the name of the function that initializes your library, for example:

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, similar to a Godot module:

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 godot-cpp-template project for a generic reusable template.

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