127 lines
4.8 KiB
Markdown
127 lines
4.8 KiB
Markdown
# godot-cpp
|
|
|
|
> [!NOTE]
|
|
>
|
|
> For GDNative (Godot 3.x), switch to the [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
|
|
> or the [`3.6`](https://github.com/godotengine/godot-cpp/tree/3.6) branch.
|
|
|
|
This repository contains the *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API.
|
|
|
|
- [**Versioning**](#versioning)
|
|
- [**Compatibility**](#compatibility)
|
|
- [**Contributing**](#contributing)
|
|
- [**Getting started**](#getting-started)
|
|
- [**Examples and templates**](#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`](https://github.com/godotengine/godot-cpp/tree/4.5)
|
|
> - [`godot-4.5-stable`](https://github.com/godotengine/godot-cpp/tree/godot-4.5-stable)
|
|
> - [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
|
|
|
|
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 (including 4.6).
|
|
|
|
Until we have a stable release branch, you can use the `master` branch (v10), 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](https://contributing.godotengine.org/en/latest/other/godot-cpp.html).
|
|
|
|
## 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](https://docs.godotengine.org/en/latest/engine_details/development/compiling/index.html).
|
|
|
|
Building your extension will create a shared library. To use this in your Godot project you'll need a `.gdextension`
|
|
file, for example:
|
|
|
|
```ini
|
|
[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](https://github.com/godotengine/godot-cpp-template/blob/main/demo/bin/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:
|
|
|
|
```cpp
|
|
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:
|
|
|
|
```cpp
|
|
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](https://github.com/godotengine/godot-cpp-template) project for a
|
|
generic reusable template.
|
|
|
|
Or checkout the code for the [Summator example](https://github.com/paddy-exe/GDExtensionSummator)
|
|
as shown in the [official documentation](https://docs.godotengine.org/en/latest/tutorials/scripting/cpp/gdextension_cpp_example.html).
|