godotengine/godot-cpp

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

Starting with version 10.x, godot-cpp is versioned independently from Godot. Using the api_version parameter (see below), godot-cpp v10 can target Godot 4.3 or later.

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

Extension authors can provide a default target API version by passing it to godot-cpp's SConstruct, for example:

env = SConscript("godot-cpp/SConstruct", {"api_version": "4.7"})

This is highly recommended! It allows the extension author to ensure that their extension is built with a version that provides all the necessary features by default.

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.