GDScript: Add @export_custom annotation

[vnen]

Allows setting any arbitrary hint and hint string. Useful for more complex hints or potential future hints not available as a dedicated annotation.

Closes #61325
Supersedes #65935

Relates to #82122

Production edit: added relates to #82122

[dalexeev]

Looks good. But, it seems to me that {substitutions} in Godot are more common than %SUBSTITUTIONS%. The property hint syntax does not use either % or {}.

[vnen]

I'll leave this on hold for now since it won't be merged for 4.0. I'm open to suggestions about the substitution syntax and what values are needed.

[nathanfranke]

I do prefer {type_value} or {TYPE_VALUE}, but I'm more curious about example values for each substitution and how they might be used in the hint string.

[vnen]

At first I was thinking on some array hints that require the element type on the hint string. But later I reconsidered as that might not really come from the variable type (unless there's a substitution for the element type).

I'll probably remove the substitutions once I revisit this. This also comes because IINM the % formatting operator is not reduced at compile time and thus cannot be used in annotations, so maybe solving that is a better option.

[ajreckof]

Just discovered this PR and felt stupid. As this was possible in 3.x and not in 4.x i thought it was a choice to reduce what was possible to do with exports. So I had made my own solution that i have been maintaining. I cleaned it a bit and published it here.
The major difference between what i did and this PR is that instead of a new export annotation i added a complementary annotation that is added between any export annotation and its variable and that enables the user to modify the type hint and the hint string.

For reference I was using it to create Inspector plugins as it is easy to set up an inspector plugin with it and it makes really clear code on the script side

[dalexeev]

Postponed to 4.3 due to feature freeze.

[vnen]

I rebased this and removed the template substitutions. If they're needed we can find a good way to add them later.

[YuriSizov]

Should we allow specifying usage as well? Everything else from property's metadata can be defined by other means (name, type, class), but usage cannot.

[vnen]

I guess it does make sense to specify the usage too.

[akien-mga]

I think it's a nice addition. I also support the idea to allow specifying the usage flags.

[dalexeev]

Note that users may accidentally remove PROPERTY_USAGE_SCRIPT_VARIABLE, PROPERTY_USAGE_NIL_IS_VARIANT, PROPERTY_USAGE_CLASS_IS_ENUM, and other flags. Of course, users can already do this in _get_property_list() for "virtual" properties or in _validate_property() for existing variables. But the question arises: should annotation flags be added to existing ones (|=) or should they overwrite the initial ones (=)?

[YuriSizov]

@dalexeev I think they should behave exactly as properties added dynamically with _get_property_list. I would not want any hidden behavior. As far as footguns go, this is not a severe problem and it can be explained in the docs for the annotation.

[YuriSizov]

@vnen Do you plan to work on this soon? 🙃

[vnen]

Added the usage flags.

[akien-mga]

Looks good to me. Needs a rebase.

[vnen]

Updated to apply the suggestions and fix conflicts.

[akien-mga]

Thanks!

[caimantilla]

Is there any reason not to allow overriding class_name? It doesn't have a ton of use cases, but there are some, eg. PROPERTY_USAGE_ARRAY (though since the script has to be a tool for that regardless, I guess that _validate_property takes care of this...?)

[dalexeev]

For the same reason as type. We do have a few exceptions when class_name is used due to the small number of fields in the PropertyInfo structure, but in most cases you should not overwrite type and class_name.