From 658287759ba69a14dc67366fba1a230186a668c3 Mon Sep 17 00:00:00 2001 From: David Snopek Date: Thu, 12 Dec 2024 16:47:22 -0600 Subject: [PATCH] Improve "Version Compatibility" section in "What is GDExtension" --- .../gdextension/what_is_gdextension.rst | 36 +++++++++++-------- 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/tutorials/scripting/gdextension/what_is_gdextension.rst b/tutorials/scripting/gdextension/what_is_gdextension.rst index 9a90fea5696..cdcb789b2d3 100644 --- a/tutorials/scripting/gdextension/what_is_gdextension.rst +++ b/tutorials/scripting/gdextension/what_is_gdextension.rst @@ -24,15 +24,8 @@ you should choose depends on your needs. .. warning:: - Our long-term goal is that GDExtensions targeting an earlier version of - Godot will 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. - - However, GDExtension is currently *experimental*, which means that we may + GDExtension is currently *experimental*, which means that we may break compatibility in order to fix major bugs or include critical features. - For example, GDExtensions created for Godot 4.0 aren't compatible with Godot - 4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`). Advantages of GDExtension ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -111,13 +104,26 @@ The bindings below are developed and maintained by the community: Version compatibility --------------------- -GDExtension add-ons compiled for a given Godot version are only guaranteed to work -with the same minor release series. For example, a GDExtension add-on compiled for -Godot 4.0 will only work with Godot 4.0, 4.0.1, 4.0.2. In addition, GDExtension is -not compatible with Godot 3.x. +Usually, GDExtensions targeting an earlier version of Godot will 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. + +For this reason, when creating GDExtensions, you may want to target the lowest version of +Godot that has the features you need, *not* the most recent version of Godot. This can +save you from needing to create multiple builds for different versions of Godot. -GDExtension add-ons are also only compatible with engine builds that use the +However, GDExtension is currently *experimental*, which means that we may +break compatibility in order to fix major bugs or include critical features. +For example, GDExtensions created for Godot 4.0 aren't compatible with Godot +4.1 (see :ref:`updating_your_gdextension_for_godot_4_1`). + +GDExtensions are also only compatible with engine builds that use the same level of floating-point precision the extension was compiled for. This means that if you use an engine build with double-precision floats, the extension must -also be compiled for double-precision floats. See -:ref:`doc_large_world_coordinates` for details. +also be compiled for double-precision floats and use an ``extension_api.json`` +file generated by your custom engine build. See :ref:`doc_large_world_coordinates` +for details. + +Generally speaking, if you build a custom version of Godot, you should generate an +``extension_api.json`` from it for your GDExtensions, because it may have some differences +from official Godot builds.