Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions src/toolchain/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,37 +17,21 @@ The godot-rust library supports multiple stable Godot releases at a time.
When developing extension libraries (or just "extensions"), you need to consider which engine version you want to target.
There are two conceptually different versions:

- **API version** is the version of GDExtension against which godot-rust (and the code of your extension) is compiled.
- **Runtime version** is the version of Godot in which the library built with godot-rust is run.
- **API version** is the version of GDExtension against which your extension is **compiled**.
- **Runtime version** is the version of Godot in which the library built with godot-rust is **run**.

The two versions can be different, but there are certain constraints (see [below](#current-guarantees)).


### Philosophy

We take compatibility with the engine seriously, in an attempt to build an ecosystem of extensions that are interoperable with multiple
Godot versions. Nothing is more annoying than updating the engine and recompiling 10 plugins/extensions.

This is sometimes difficult, because:

- Godot may introduce subtle breaking changes of which we are not aware.
- Some changes that are non-breaking in C++ and GDScript are breaking in Rust (e.g. providing a default value for a previously required parameter).
- Using newer features needs to come with a fallback/polyfill for older Godot versions.

We run CI jobs against multiple Godot versions, to get a certain level of confidence that updates do not break compatibility.
Nevertheless, the number of possible combinations is large and only growing, so we may miss certain issues.
If you find incompatibilities or violations of the rules stated below, please let us know.
The two versions can be different, with the following rules:


### Current guarantees

Latest godot-rust requires at least **Godot 4.2**.

Starting from that version's official release, extensions can be loaded by any Godot version, as long as
_runtime version **>=** API version_.
Starting from that version's official release, extensions can be loaded by any Godot version, as long as _runtime version **>=** API version_.
In other words, you can run existing extensions in newer Godot versions without needing to change anything.

- You can run a `4.2` extension in Godot `4.2.1` or `4.3`.
- You cannot run a `4.3` extension in Godot `4.2.1`.
- You **can** run a `4.2` extension in Godot `4.2.1` or `4.3`.
- You **cannot** run a `4.3` extension in Godot `4.2.1`.

As long as the GDExtension API evolves in a backward-compatible manner -- which it has remarkably achieved since Godot 4.1 -- we will try our
best to keep up this guarantee. If you notice any discrepancies, please report them to us.
Expand All @@ -69,6 +53,22 @@ These won't receive any more updates however, not even for critical bugs.
| 0.1 | 4.0[^Godot-4-0] | March 2023 |


### Philosophy

We take compatibility with the engine seriously, in an attempt to build an ecosystem of extensions that are interoperable with multiple
Godot versions. Nothing is more annoying than updating the engine and recompiling 10 plugins/extensions.

This is sometimes difficult, because:

- Godot may introduce subtle breaking changes of which we are not aware.
- Some changes that are non-breaking in C++ and GDScript are breaking in Rust (e.g. providing a default value for a previously required parameter).
- Using newer features needs to come with a fallback/polyfill for older Godot versions.

We run CI jobs against multiple Godot versions, to get a certain level of confidence that updates do not break compatibility.
Nevertheless, the number of possible combinations is large and only growing, so we may miss certain issues.
If you find incompatibilities or violations of the rules stated below, please let us know.


### Out of scope

We do **not** invest effort in maintaining compatibility with:
Expand Down
Loading