C++ bindings for the Godot script API
 
 
 
 
 
 
Go to file
Rémi Verschelde b03e56922d
CMake: Remove hardcoded warnings list and forcing -Werror on library builds
The CMake buildsystem should be completely reviewed to properly match
what is done by SCons, instead of making its own arbitrary decisions on
how godot-cpp should be compiled.

Currently the SCons setup doesn't include warning options, so CMake
shouldn't either. Options similar to upstream Godot's SCons setup could
be added, and then replicated for CMake.

(cherry picked from commit 41517eacb1)
2023-12-12 13:47:21 +01:00
.github Bump mymindstorm/setup-emsdk from 12 to 13 2023-11-22 19:10:15 +00:00
cmake {cmake} Use STATIC and POSITION_INDEPENDENT_CODE 2023-02-07 10:24:25 -05:00
gdextension gdextension: Sync with upstream commit 46dc277917a93cbf601bbcf0d27d00f6feeec0d5 (4.2-stable) 2023-11-30 10:01:44 +01:00
include/godot_cpp [iOS] Fix initialisation/termination of multiple statically linked extensions. 2023-11-23 13:38:20 +02:00
misc Sync license copyright with upstream GH-70885 2023-01-10 16:15:31 +01:00
src Send NOTIFICATION_POSTINITIALIZE to extension classes 2023-11-29 12:00:43 -06:00
test CMake: Remove hardcoded warnings list and forcing -Werror on library builds 2023-12-12 13:47:21 +01:00
tools Merge pull request #1313 from DmitriySalnikov/visibility_hidden 2023-11-24 07:15:52 -06:00
.clang-format Add more static checks and move to separate file to match main repo 2022-10-09 01:46:28 -05:00
.gdignore Add .gdignore file to godot-cpp, for use as submodule in Godot projects 2022-12-22 16:01:03 +01:00
.gitattributes Getting this to compile on mac os x 2017-06-16 23:50:48 +10:00
.gitignore ignoring venv in .gitignore 2023-11-06 22:32:52 +01:00
.gitmodules Remove godot-headers submodule, copy files directly 2022-03-15 10:19:07 +01:00
CMakeLists.txt CMake: Remove hardcoded warnings list and forcing -Werror on library builds 2023-12-12 13:47:21 +01:00
LICENSE.md Sync license copyright with upstream GH-70885 2023-01-10 16:15:31 +01:00
Makefile Update Makefile after recent buildsystem changes 2022-10-06 14:34:29 +02:00
README.md Add 4.2 branch to README 2023-11-30 10:02:53 +01:00
SConstruct Merge pull request #1220 from adamscott/add-local-custom-support-redux 2023-09-21 15:06:30 -05:00
binding_generator.py Change bit field enums to use `uint64_t` as underlying type 2023-11-28 01:03:41 +01:00

README.md

godot-cpp

Warning

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

For users of stable branches, switch to the branch matching your target Godot version:

Or check out the Git tag matching your Godot version (e.g. godot-4.1.1-stable).

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

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

Versioning

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

  • master tracks the current GDExtension development branch for the next Godot 4.x minor release.
  • 3.x tracks the development of the GDNative plugin for the next 3.x minor release.
  • Other versioned branches (e.g. 4.0, 3.5) 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 Godot, we recommend using this repository as a Git submodule, checking out the specific tag matching your Godot version.

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

Compatibility

Warning: The GDExtension API is brand new in Godot 4.0, and is still considered in beta stage, despite Godot 4.0 itself being released.

This applies to both the GDExtension interface header, the API JSON, and this first-party godot-cpp extension.

Some compatibility breakage is to be expected as GDExtension and godot-cpp get more used, documented, and critical issues get resolved. See the Godot issue tracker and the godot-cpp issue tracker for a list of known issues, and be sure to provide feedback on issues and PRs which affect your use of this extension.

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 copy the files in misc/hooks into .git/hooks so formatting is done before your changes are submitted.

Getting started

It's a bit similar to what it was for 3.x but also a bit different. This new approach is much more akin to how core Godot 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 Godot 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 Godot module would do.

using namespace godot;
void initialize_example_module(ModuleInitializationLevel p_level) {
	if (p_level != MODULE_INITIALIZATION_LEVEL_SCENE) {
		return;
	}
	ClassDB::register_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.