Godot compatibility guidelines

[Bromeon]

Due to Godot developing at such a fast pace and GDExtension C API constantly breaking, people keep running into version mismatching issues. Typically, this manifests as UB and crashes at runtime.

Examples:

• Does not work on Godot 4 beta 5 (but does with beta4) #25
• Editor crashes while loading gdextension #26
• cargo build error use godot::engine::{file_access, os}; no file_access in engine  #39
• Everything is successful unless version number screws up #47
• The examples does not run properly #51
• Error when building the repo #106

---

This could be addressed in multiple, partly orthogonal ways:

1. Write down general guidelines w.r.t. which Godot and which godot-rust version to use. For example, link to nightly builds.

2. Keep a compatibility map with a few explicit version matches. A simple approach might be Git tags like godot-beta-17 in the repo. Ideally, this would be CI-tested, although that's quite a bit of effort to automate.

3. Maintain a repo for Godot artifacts of certain versions (e.g. nightly builds or beta releases). We could still not mix&match due to C header having a direct influence on Rust code, but it may facilitate fetching correct versions of Godot input artifacts, such as:

   • C API: gdextension_interface.h
   • JSON API: extension_api.json
   • XML documentation
   • meta information (version, is it nightly/beta/etc, maybe build config)

4. Output a warning if a mismatching Godot version is detected, or an error in severe cases.

[ttencate]

A separate crate for Godot artifacts (option 3), plus cargo version ranges might be a nice solution. So we could say in Cargo.toml for example:

[dependencies]
godot-api = ">= 4.0.0-beta.15, <= 4.0.0-beta.17"

We can parse this out with a build script or a proc-macro, and bake it into the library as a startup check. If it's being run with an incompatible Godot version, just panic and give up.

(Note that I added a dot in beta.15 so that ranges work properly.)

[mareksubocz]

What versions of Godot are currently supported?

[Bromeon]

What versions of Godot are currently supported?

Godot 4.0 and 4.0.1, as well as developer/nightly builds starting from 4.0