DOCSEARCHbyAlgolia
Submit Docs

godot-cpp

repository·master·Indexed 25 days ago

https://github.com/godotengine/godot-cpp

C++ bindings for the Godot Engine's GDExtension API, enabling the development of high-performance engine extensions. Includes C header files, API JSON definitions, and guidance on targeting specific Godot API versions, configuring .gdextension files, implementing entry points, and registering classes in the Godot ClassDB.

Tokens
1.3K
Snippets
5
Records
7
Agent score
33%

What's inside godot-cpp

  2. Sync GDExtension header and API with a custom Godot build

    master

    If you are using a modified version of Godot or a specific commit that is not covered by the current repository version, you can manually generate the required extension_api.json and gdextension_interface.json files.

    1. Compile Godot Engine at your desired version/commit, or download the official release executable.
    2. Run the executable with the specific flags to dump the API definitions.
    godot --dump-extension-api --dump-gdextension-interface-json

  3. Set the target Godot API version

    master

    When building godot-cpp, you can specify which Godot version your GDExtension targets. GDExtensions targeting an earlier version of Godot should work in later minor versions, but not vice-versa.

    You can specify the version using the api_version SCons option, or by providing a custom extension_api.json file generated from your specific Godot version.

    # Target a specific Godot version
scons api_version=4.3

# Target using a custom API JSON file generated by your Godot version
godot --dump-extension-api
scons custom_api_file=extension_api.json

  5. Configure a .gdextension file

    master

    To use your compiled shared library in a Godot project, you must create a .gdextension configuration file. This file maps platform-specific library paths to the engine. The entry_symbol must match the name of your C-style initialization function.

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

  6. Implement the GDExtension entry point

    master

    Your library must export a C function (using extern "C") that serves as the entry point. This function uses godot::GDExtensionBinding::InitObject to initialize the binding, register initialization/termination callbacks, and set the minimum initialization level.

    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();
}
}

  7. Register classes in the Godot ClassDB

    master

    During the initialization phase, you must register your C++ classes so they are available to Godot's engine and scripting systems. Use the GDREGISTER_CLASS macro within your initialization function, ensuring you check for the correct ModuleInitializationLevel.

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