godotengine/godot-cpp
1
0
Fork 0
mirror of https://github.com/godotengine/godot-cpp.git synced 2026-09-03 23:39:46 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update README for versioning and compatibility changes in v10

Browse Source
This commit is contained in:
David Snopek
2026-01-15 09:13:45 -06:00
parent b895ed9f9c
commit 6e47919ff8
1 changed files with 40 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
README.md
View File

@@ -1,23 +1,9 @@
# godot-cpp # godot-cpp
> [!WARNING] > [!NOTE]
> >
> This repository's `master` branch is only usable with > For GDNative (Godot 3.x), switch to the [`3.x`](https://github.com/godotengine/godot-cpp/tree/3.x)
> [GDExtension](https://godotengine.org/article/introducing-gd-extensions) > or the [`3.6`](https://github.com/godotengine/godot-cpp/tree/3.6) branch.
> from Godot's `master` branch.
>
> For users of stable branches, switch to the branch matching your target Godot version:
> - [`4.5`](https://github.com/godotengine/godot-cpp/tree/4.5)
> - [`4.4`](https://github.com/godotengine/godot-cpp/tree/4.4)
> - [`4.3`](https://github.com/godotengine/godot-cpp/tree/4.3)
> - [`4.2`](https://github.com/godotengine/godot-cpp/tree/4.2)
> - [`4.1`](https://github.com/godotengine/godot-cpp/tree/4.1)
> - [`4.0`](https://github.com/godotengine/godot-cpp/tree/4.0)
>
> 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`](https://github.com/godotengine/godot-cpp/tree/3.x)
> or the [`3.5`](https://github.com/godotengine/godot-cpp/tree/3.5) branch.
This repository contains the *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API. This repository contains the *C++ bindings* for the [**Godot Engine**](https://github.com/godotengine/godot)'s GDExtensions API.
@@ -29,36 +15,41 @@ This repository contains the *C++ bindings* for the [**Godot Engine**](https://
## Versioning ## Versioning
This repositories follows the same branch versioning as the main [Godot Engine > [!WARNING]
repository](https://github.com/godotengine/godot): >
> 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)
- `master` tracks the current GDExtension development branch for the next Godot Starting with version 10.x, godot-cpp is versioned independently from Godot. The godot-cpp version you
4.x minor release. choose has no bearing on which Godot versions it is compatible with.
- `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: Until we have a stable release branch, you can use the `master` branch, or choose any of the previous
[**Tags**](https://github.com/godotengine/godot-cpp/tags). version branches and tags for your project.
**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 ## Compatibility
GDExtensions targeting an earlier version of Godot should work in later minor versions, GDExtensions targeting an earlier version of Godot should work in later minor versions,
but not vice-versa. For example, a GDExtension targeting Godot 4.2 should work just fine but not vice-versa. For example, a GDExtension targeting Godot 4.3 should work just fine
in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2. in Godot 4.4, but one targeting Godot 4.4 won't work in Godot 4.3.
There is one exception to this: extensions targeting Godot 4.0 will _not_ work with You can specify which version you are targeting with the `api_version` option:
Godot 4.1 and later.
See [Updating your GDExtension for 4.1](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.1.html#updating-your-gdextension-for-godot-4-1). ```
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 ## Contributing
@@ -69,16 +60,8 @@ wish to help out, please visit the [godot-cpp section of the Contributing docs](
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). 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).
Getting started with GDExtensions is a bit similar to what it was for 3.x but also a bit different. Building your extension will create a shared library. To use this in your Godot project you'll need a `.gdextension`
file, for example:
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](test/project/example.gdextension) used in the test project:
```ini ```ini
[configuration] [configuration]
@@ -97,8 +80,10 @@ linux.release.x86_64 = "res://bin/libgdexample.linux.release.x86_64.so"
# Repeat for other architectures to support arm64, rv64, etc. # Repeat for other architectures to support arm64, rv64, etc.
``` ```
The `entry_symbol` is the name of the function that initializes See the [example.gdextension](https://github.com/godotengine/godot-cpp-template/blob/main/demo/bin/example.gdextension)
your library. It should be similar to following layout: 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 ```cpp
extern "C" { extern "C" {
@@ -117,7 +102,7 @@ GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddre
} }
``` ```
The `initialize_example_module()` should register the classes in ClassDB, very like a Godot module would do. The `initialize_example_module()` should register the classes in ClassDB, similar to a Godot module:
```cpp ```cpp
using namespace godot; using namespace godot;
@@ -129,7 +114,8 @@ void initialize_example_module(ModuleInitializationLevel p_level) {
} }
``` ```
Any node and resource you register will be available in the corresponding `Create...` dialog. Any class will be available to scripting as well. 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 ## Examples and templates