@tool Annotation Should Work on Individual Functions

[hmturnbull]

I've often wanted to give my nodes configuration warnings via _get_configuration_warning(), but the way it works currently means I never do; I'm too scared I'll write a function and forget to add the is_editor_hint() check and cause damage to my scenes when the function runs (say, if the function contains queue_free() or something).

(note that it's sometimes useful to have a whole script work in the editor, and a @tool annotation used at the top of a script before the extends keyword should retain its current functionality. I just think the all-or-nothing approach to @tool scripts renders the _get_configuration_warning() method more trouble than its worth.)

I don't really see any benefit to being unable to easily grant @tool functionality to individual functions--particularly as a function like _get_configuration_warning() is only applicable in the editor, and making an entire script run in the editor for just one function is so dangerous. As it is, it's just not worth the risk.

I'm not sure how similar it is in implementation, but take the fact that the @export annotation causes immediate feedback in the editor (specifically by adding a field to the Inspector), and moreover that it doesn't cause every single variable in the script to become an @export variable. This functionality would lead one to reasonably ask why @tool doesn't work in an analogous manner.

In my opinion, the @tool annotation as applied to functions should probably be at least somewhat similar to how we use annotations for variables:

@tool func _get_configuration_warnings():
    var warnings = []

    if title == "":
        warnings.append("Please set `title` to a non-empty value.")

    if description.length() >= 100:
        warnings.append("`description` should be less than 100 characters long.")
    
    return warnings

P.S.

I know there have been similar proposals in the past, but all of them appear to have been written back when @tool was a keyword (tool) instead of an annotation.

Alternatively, if giving @tool different functionality if used before extends is a problem, then maybe a different annotation like @editor func would work better.

[AThousandShips]

Can you please link those other proposals so we can more easily take part of the arguments made there? Simply mentioning it but not the arguments made there feels kinda disingenuous (and they're not easy to find)

[hmturnbull]

[#729]
[#6767]
[#8735]
[#5165]

I didn't put the links in initially was because those proposals used the outdated Godot 3 syntax and I didn't want to confuse people.

"Disingenuous"? Seems a bit overdramatic and rude, as all I'm suggesting is that having to make an entire script more error-prone just to have a warning in the editor makes Godot harder to use.

Some of these other references had developers suggesting this might be possible, and I'm just pursuing that. This is open source, so let's all be respectful here, and not assume the worst in people.

[AThousandShips]

I am just saying that when the literal topic has already been discussed and you mention it but not pointing to it it comes across as that, I'm not assuming anything, I'm sorry it didn't come across the way I intended it, I'm sorry for causing offense, all I was meaning was that you weren't providing the full picture

All I meant was that I was confused over the choice, that's all

[hmturnbull]

Thank you. I will try to include all relevant details in future.

[Zireael07]

You start with 'Agreed' but there is nothing to agree/disagree with yet?

[hmturnbull]

Thanks for catching that. It was originally a comment.

[AThousandShips]

Now this would require rebuilding the entire way this works in GDScript, and would require a separate mechanism there, as I don't know if this is possible in C#, further it'd cause confusion among users, people already get confused over attempting to call functions on non-tool scripts as it is, I don't believe it's worth it for all those issues

[hmturnbull]

I'm still unclear on how this change would cause more confusion than having functions that have no use unless you use an annotation that forces you to add duplicate code to almost all your functions. You might be correct that implementing it may be very challenging.

What about my suggestion above of making a new annotation that would do this:

If giving @tool different functionality if used before extends is a problem, then maybe a different annotation like @editor func would work better.

[dalexeev]

See also: conditional compilation.

• Conditional GDScript parsing godot#6340
• 'version' keyword in GDScript for conditional compilation at build time godot#26649
• GDScript → Add conditional compilation directives #4023
• Preprocess scripts on export to take constant feature tags into account #4234

I made a plugin: dalexeev/gdscript-preprocessor.