Better document that builtins with the return type "flags" are BitFields, not enums, and document what BitFields actually are and how to use them in gdscript

[sleepingrainbow]

Your Godot version:
4.4.1

Issue description:
GlobalScope docs page (both online and in editor) is missing the PropertyUsageFlags entry for 4102 which is for script @export vars, which I was only able to figure out the flag for by print()ing an object's get_property_list()

I also discovered 135168, also not in the docs, which is less clear what it is, but from experimentation I think appears to be used for untyped non-exported script vars (static typed non-exported script vars show as 4096, which is listed in the docs but claims to be for all script vars)

edit: apparently these flags returned by get_property_list() are not enums at all like I'd assumed, but are actually bit fields, a data type that I have never seen before and isn't documented anywhere in gdscript

URL to the documentation page:
https://docs.godotengine.org/en/latest/classes/class_%40globalscope.html#enum-globalscope-propertyusageflags

[dalexeev]

4102 = 2 (PROPERTY_USAGE_STORAGE) + 4 (PROPERTY_USAGE_EDITOR) + 4096 (PROPERTY_USAGE_SCRIPT_VARIABLE)

135168 = 4096 (PROPERTY_USAGE_SCRIPT_VARIABLE) + 131072 (PROPERTY_USAGE_NIL_IS_VARIANT)

[sleepingrainbow]

4102 = 2 (PROPERTY_USAGE_STORAGE) + 4 (PROPERTY_USAGE_EDITOR) + 4096 (PROPERTY_USAGE_SCRIPT_VARIABLE)

135168 = 4096 (PROPERTY_USAGE_SCRIPT_VARIABLE) + 131072 (PROPERTY_USAGE_NIL_IS_VARIANT)

well then that's extremely unclear if that's how it works, I thought it was an enum with fixed values

[sleepingrainbow]

oops, didnt mean to close this, I clicked the wrong comment button, if that's how those enum values work, then that definitely should be documented

[bruvzg]

"Enum" is a set of fixed value constants.

"Flags" is a bit field (each of the constants is a single bit, and the value is an any combination of these bits).

[bruvzg]

GDScript reference has description for Enum, but not for BitField, so it should be updated.

[AThousandShips]

It's also explained where this is used, in Object.get_property_list, where it says it's a combination

[sleepingrainbow]

I see, if it adds all the flags together, wouldn't that make checking for one flag a lot harder though, like if I wanted to check if a property is a script variable, but the flag could come out 4096 , 4102, 135168, or any other combination, not even sure how you'd do the math to check for every combination, wouldn't an array of fixed flags make much more sense if they have to be able to have multiple?

[AThousandShips]

You would have literally hundreds of millions of values to store, checking individual bits is much much easier and you can easily make combinations, instead of finding exact valeus

How would you figure out the combination of five different flags?

[bruvzg]

wouldn't that make checking for one flag a lot harder though, like if I wanted to check if a property is a script variable
not even sure how you'd do the math to check for every combination

You can use bitwise operations to check, set and unset it.

if x & BIT: to check if BIT is set, x = x | BIT to set it, and x = x & ~BIT to unset it, see https://en.wikipedia.org/wiki/Bit_field#C_programming_language (it's for C/C++ but idea is the same in any language).

[sleepingrainbow]

I see, I see, its some archaic c++ engine core performance thing then i guess, well thanks for explaining, though I still think the docs on it could be clearer

• sincerely, a novice gdscript user who has never met BitFields

[dalexeev]

if I wanted to check if a property is a script variable, but the flag could come out 4096 , 4102, 135168, or any other combination

Use bitwise operations:

for property in get_property_list():
    if property.usage & PROPERTY_USAGE_SCRIPT_VARIABLE:
        prints(property.name, "is a script variable.")