Add a way to specify compatible Godot versions for editor plugins

[Calinou]

Describe the project you are working on:

The Godot editor 🙂

Describe the problem or limitation you are having in your project:

If you create an editor plugin, there is currently no built-in way to display an error or warning message if the plugin is being used with an incompatible Godot version. This can be done in the main plugin script using a version check and push_error() or push_warning(), but it has to be implemented manually by the plugin author.

Describe the feature / enhancement and how it helps to overcome the problem or limitation:

Add a godot_version field to plugin.cfg. This field would take the form of a semanatic versioning range.

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams:

Here are some example values for the godot_version field:

• ^3.2.1: compatible with 3.2.1, 3.2.2, 3.3, … but not 3.2 or 4.0
• 3.2.x: compatible with 3.2, 3.2.1, 3.2.2… but not 3.3 or 4.0
• *: compatible with any version. Since this is too permissive (there's no plugin that can work with all Godot versions), this should probably not be allowed 🙂
  • Some package managers like Cargo have taken a similar stance and forbid using * ranges.

For the purposes of version comparison, "zero" patch releases such as Godot 3.2 will be treated as 3.2.0 by the semantic versioning comparator.

This Godot version field should be specifiable using the plugin creation dialog as well. By default, it would default to the current Godot version with a caret prepended. For example, when using Godot 3.2.3, the default value would be ^3.2.3. If the plugin is known to work with earlier patches, this version field can be edited manually by the plugin author.

If this enhancement will not be used often, can it be worked around with a few lines of script?:

No, as this is core editor functionality.

Is there a reason why this should be core and not an add-on in the asset library?:

This is about improving the installation experience for editor plugins.

[Xrayez]

• *: compatible with any version. Since this is too permissive (there's no plugin that can work with all Godot versions), this should probably not be allowed 🙂

3.2 and 4.0 cross-compatibility may work out for simple plugins where GDScript syntax, underlying methods and types may not differ that much. I'm also not sure if it's possible to distribute separate versions of a script for each Godot major version without introducing parse errors.

I say this because I used to have a plugin which worked in 2.1↔3.2, but likely not a situation with 3.2↔4.0 (except for earlier 4.0 dev versions where GDScript 2.0 was not merged yet).

Perhaps there should be a way annotate script Godot versions as well, mainly for class_name scripts which reside under addons such as addons/my_plugin/global_class.gd.

That said, scripts themselves could specify in what GDScript version they were written as well:

@gdscript_version 2.0
class_name CustomNode extends Node

Again, would be mainly useful for preventing the script to be parsed in the first place in different Godot versions. If I recall correctly, GDScript does have internal version specifiers for script bytecode, the same could be applied to source code.

Alas, there's no annotations support in GDScript 1.0, so this kind of scheme would only work for Godot 4+ versions.

Of course everything above is probably far-fetched anyway, just food for thought. 😛

[jonbonazza]

This Godot version field should be specifiable using the plugin creation dialog as well

Does this dialogue exist already?

[Calinou]

@jonbonazza Yes, see Making plugins in the documentation.

[me2beats]

What if a script needs

• Godot 3+ (3, 4 etc)?
• Godot 3 and 4 but not 5?

[Calinou]

@me2beats It's very unlikely for a plugin to be compatible with several major Godot versions, as breaking changes are always introduced between such releases.

Note that by plugin, I'm only referring to editor plugins, not generic add-ons like art assets. This has no relation to the "Godot version" field in the asset library.

[Calinou]

Godot 4 update: GDExtensions have their own Godot version compatibility field in their manifests, although they don't use semver ranges.