diff --git a/README.md b/README.md index 55e322ab5..4381bf934 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,9 @@ # godot-cpp -> [!WARNING] -> -> This repository's `master` branch is only usable with -> [GDExtension](https://godotengine.org/article/introducing-gd-extensions) -> 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`). +> [!NOTE] > -> 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. +> 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. @@ -29,36 +15,41 @@ This repository contains the *C++ bindings* for the [**Godot Engine**](https:// ## Versioning -This repositories follows the same branch versioning as the main [Godot Engine -repository](https://github.com/godotengine/godot): - -- `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**](https://github.com/godotengine/godot-cpp/tags). +> [!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) -**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.** +Starting with version 10.x, godot-cpp is versioned independently from Godot. The godot-cpp version you +choose has no bearing on which Godot versions it is compatible with. -> 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. +Until we have a stable release branch, you can use the `master` branch, 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.2 should work just fine -in Godot 4.3, but one targeting Godot 4.3 won't work in Godot 4.2. +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: -There is one exception to this: extensions targeting Godot 4.0 will _not_ work with -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 @@ -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). -Getting started with GDExtensions is 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](test/project/example.gdextension) used in the test project: +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] @@ -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. ``` -The `entry_symbol` is the name of the function that initializes -your library. It should be similar to following layout: +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" { @@ -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 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