Add @global annotation for enums

[dalexeev]

Add the ability to give inner classes and enums global names (as aliases to local names).

extends RefCounted
class_name ItemDB

@global("ItemInfo")
class Info extends RefCounted:
    # ...

@global("ItemID")
enum ID {
    SWORD,
    SHIELD,
    # ...
}

# Or:
# @global enum ItemID {
#     SWORD,
#     SHIELD,
#     ...
# }

For example, you can use ItemID.SWORD instead of ItemDB.ID.SWORD and ItemInfo instead of ItemDB.Info.

Alternatives:

1.1. Don't use inner classes. I almost always do this, but for "structs" inner classes are fine. This part is just for completeness.
1.2. Don't use named enums (then it will be ItemDB.SWORD). However, you won't be able to use an enum as a type.

2. Add a using analog that allows you to import a class/enum into a script with a short name (also namespaces are planned in future versions as far as I know). use ItemDB.ID as ItemID or something similar. However, this will require repeating this line in every script that uses this class/enum.

In 3.x you can use const MyEnum = OtherClass.MyEnum. In 4.0 this doesn't work properly, but I'm not sure if it should.

---

I only suggest inner classes and enums as they are used as types (plus reducing the number of enum components from 3 to 2 in places of use). However, @global can also be used with static functions and constants, as they are stateless. This would allow, for example, to remove the Util. prefix:

extends RefCounted
#class_name Util # This line is no longer needed

@global("INT64_MAX") # If the name is the same, you can just use @global
const INT64_MAX = (1 << 63) - 1

# ...

@global("equal")
static func equal(a, b) -> bool:
    return typeof(a) == typeof(b) and a == b

# ...

[willnationsdev]

If an inner class were flagged as @global, would you expect it to behave like a global script class? That is, would it...

1. be instantiable from the CreateDialog (i.e. the "Add a Node" popup)
2. be visible as a global type in the ScriptServer and therefore accessible from other languages
3. be exportable as a resource type in the Inspector? (Allow exporting custom resources from/to GDScript, VisualScript, C#, and PluginScript. godot#48201)

Or would this be a global alias that is uniquely within the scope of the GDScript language?

+1 for also including static functions in this. I could also foresee eventually adding extension methods to GDScript using this in tandem with an @extension annotation and a static type hint on the first argument.

With all that said, I think it would be confusing and/or weird for inner classes to be something that could be recognized as a global script class by the engine, so I wouldn't do that. And I do like the idea of enums, constants, and static methods being things that can be globalized within GDScript, BUT rather than doing it on a case-by-case basis, I think it would be better to have a @global class annotation at the top of the file, similar to @tool, that marks the class as being used exclusively for the purpose of defining additions to the global namespace of the language. This makes it so the language parser has the option of skipping files that don't include that annotation when updating the global symbol table.

[dalexeev]

If an inner class were flagged as @global, would you expect it to behave like a global script class?

I think applying @global on inner class should work like class_name on script class. As far as I remember, there is a proposal to separate the class_name functionality so that the displaying of the class in the node/resource creation dialog can be controlled by a separate annotation.

With all that said, I think it would be confusing and/or weird for inner classes to be something that could be recognized as a global script class by the engine, so I wouldn't do that.

Inner classes are interesting because you can not use them at all, and everything will be fine. The absence of any inner class feature you can get around using a script class, so we need to remember that the argument "you can use a script class instead of an inner class" cannot be used in such matters. But there is a certain logic in your words, we should think about it if we go this way.

In any case, enums, constants, static functions (and potentially interfaces) do not have such a workaround, this proposal concerns them first of all.

BUT rather than doing it on a case-by-case basis, I think it would be better to have a @global class annotation at the top of the file, similar to @tool, that marks the class as being used exclusively for the purpose of defining additions to the global namespace of the language.

This will also work, but please note: 1. @global scripts should not have extends, it's just a set of global enums, constants, functions, etc.; 2. this option allows global variables; 3. static and non-static functions of @global scripts cannot use self; 4. probably it will be difficult to implement global signals. I'm not sure how much more complex your proposal is than mine, but your proposal has more potential.

[willnationsdev]

As far as I remember, there is a proposal to separate the class_name functionality so that the displaying of the class in the node/resource creation dialog can be controlled by a separate annotation.

Yes, that is #4493. And I can possibly understand globalizing inner classes within the GDScript language, but allowing those to be exposed to the editor and other scripting languages is probably not a realistic or practical option in terms of keeping the engine code clean unless we do a lot of refactoring (details below).

But there is a certain logic in your words, we should think about it if we go this way.

In particular, the ScriptServer binds typenames to specific files, and treats the class information represented by that Script file to be globally associated with that typename. If you change that 1-to-1 relationship, thereby allowing a single Script file to define multiple global script class types, then you'd need to refactor a ton of things in other parts of the engine, and I don't really see it as being a necessity, personally.

In any case, enums, constants, static functions (and potentially interfaces) do not have such a workaround, this proposal concerns them first of all.

Agreed. I think if it's just about adding to the global symbol table within GDScript, then it's totally fine to move forward with this proposal's concept.

@global scripts should not have extends, it's just a set of global enums, constants, functions, etc.

Yes, was thinking similarly. If an instance if never supposed to be created, then extends doesn't make sense. Also should produce a parse error if the user defines a local function or a variable (only constants, enums, static methods, and inner classes allowed).

this option allows global variables

Whether that can be supported, idk. I have a vague memory a long time ago of suggesting combining the static keyword with var to allow people to define Script-level, mutable "properties", but reduz had - at the time - said it wasn't an option due to issues with memory management or something like that. Like, some deeper structural issue was the reason that global variables weren't allowed but global constants and static methods were. I forget where it was mentioned, but perhaps it could be revisited in a later 4.x release. Don't think that should be our goal for right now (if I wanna try and squeeze in a PR for this before August 3rd). That should be its own separate proposal.

static and non-static functions of @global scripts cannot use self;

Yes. Another thought though: I wonder if we could hack the get_script() method in static method calls to actually be allowed and correctly return the current Script resource, now that we don't have to worry about circular dependency issues. Hmmmm.

probably it will be difficult to implement global signals. I'm not sure how much more complex your proposal is than mine, but your proposal has more potential.

Again, yeah, not really an option for now since maintaining signal connection information is handled on an instance-to-instance basis, i.e. it falls into the same "global state" problem that global variables have. Would need to be something that is kept as part of a dedicated proposal with global/static "Script"-based variables/signals.

[dalexeev]

@global can also be used with static functions and constants, as they are stateless.

This will not be true in the future as we want to add static variables (#6156). In this regard, it is worth rethinking this idea. Global functions and variables are a double-edged sword, but we will probably add this feature someday (the only question is how).

[asteinlein]

Any progress on this? Came across this after investigating Google's annoying AI Overview which explains this proposal as an actual current Godot feature. :(

[dalexeev]

Frankly, in retrospect, I feel like the solution proposed here is more of a patch. Especially considering how overcomplicated the GDScript loading/caching system is and how the "class is a resource" approach has problems.

*.gd files are classes, there is no way to declare an enum or function at the top level. But given that the traits proposal suggests a new *.gdt extension for traits and there is ongoing discussion of a potential "GDScript 3.0" based on GDExtension, maybe in the future we will get a new *.gds file format in which classes, enums, functions and other types of definitions can be used at the top level?

Currently, you can use const-preload to "import" a type into the current script:

# You can use constants that contain types as type aliases, including for type hints.
# The "import" doesn't work only for built-in `Variant` types, native enums, `Variant`, and `void`.
const MyNode = Node
const MyClass = SomeClass
const MyInnerClass = SomeClass.InnerClass
const MyEnum = SomeClass.SomeEnum

var a: MyNode
var b: MyClass
var c: MyInnerClass
var d: MyEnum