Exporting bit flags section confusing

[nanodeath]

Your Godot version:

v4.2.1.stable.mono.official [b09f793f5]

Issue description:

I have a C# enum and I'm trying to enable using it as a bitset, where some Node script can have 0 or more values of this enum set. I'm aiming to avoid having to fiddle around with ints if possible.

The first point of confusion comes from the first code snippet, which contains this at the end:

[Export]
public SpellElements MySpellElements { get; set; }

This...doesn't appear to work or do anything. SpellElements isn't defined as a type anywhere else in the document.

Secondly, with this block:

// Set any of the given flags from the editor.
[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

it's unclear how this variable's declaration is connected with the enum created earlier. Probably because...it's not! Right? The flags in this type are duplicated by the enum and happen to be in the same order, which is required for it to "work".

Lastly, there's no explanation of how to use the flags. The section feels a bit incomplete, kind of "and then what?" I believe I need to use bit manipulation here? Something like ((MyEnum)SpellElements).HasFlag(MyEnum.Fire)? I'm not even sure I can cast an int to an enum, I'm just kinda guessing.

There's also this in the same section:

[Export(PropertyHint.Layers2DPhysics)]
public uint Layers2DPhysics { get; set; }

which doesn't seem relevant to bit flags, even if they're technically implemented as bit flags.

URL to the documentation page:

https://docs.godotengine.org/en/stable/tutorials/scripting/c_sharp/c_sharp_exports.html#exporting-bit-flags

If you know how to fix the issue you are reporting please
consider opening a pull request. We provide a tutorial on
using git here: https://docs.godotengine.org/en/stable/community/contributing/pr_workflow.html,
writing documentation at https://docs.godotengine.org/en/stable/community/contributing/docs_writing_guidelines.html
and contributing to the class reference here: https://docs.godotengine.org/en/stable/community/contributing/updating_the_class_reference.html

[raulsntos]

The first point of confusion comes from the first code snippet, which contains this at the end:

[Export]
public SpellElements MySpellElements { get; set; }

This...doesn't appear to work or do anything. SpellElements isn't defined as a type anywhere else in the document.

You are right, the SpellElements definition is supposed to be MyEnum but unfortunately it has the wrong name. This is meant to show that any enum type that has the [Flags] attribute will be represented as bit flags in the inspector when exported.

Secondly, with this block:

// Set any of the given flags from the editor.
[Export(PropertyHint.Flags, "Fire,Water,Earth,Wind")]
public int SpellElements { get; set; } = 0;

it's unclear how this variable's declaration is connected with the enum created earlier. Probably because...it's not! Right? > The flags in this type are duplicated by the enum and happen to be in the same order, which is required for it to "work".

That's correct, this is just meant to show a different way of exporting bit flags. Instead of using an enum, you can also use int. When using int you have to specify a bit more information in the [Export] attribute, and this example shows how to do that.

Lastly, there's no explanation of how to use the flags. The section feels a bit incomplete, kind of "and then what?" I believe I need to use bit manipulation here? Something like ((MyEnum)SpellElements).HasFlag(MyEnum.Fire)? I'm not even sure I can cast an int to an enum, I'm just kinda guessing.

Using C# enums is kind of out of scope for this documentation which is only meant to explain how to export types so they show in the inspector. The Godot C# documentation expects the user has basic C# knowledge, but we do try to link to the Microsoft documentation when relevant so maybe we could do that here.

To answer your questions:

• Flag enums can be manipulated using bitwise operators (e.g.: ~, &, |) and the Enum.HasFlag method.
• Enums in C# are just a group of integer constants (the underlying type for enums is int by default but can also be any other integer type, such as long). Therefore any enum can be converted from/to the underlying type.
• You are free to use enum types or integer types for the type of the exported property, and then manipulate them however you prefer.

[nanodeath]

expects the user has basic C# knowledge

haha, oof. That's fair, but it wouldn't hurt to make it just a little more user-friendly, right? I'd be fine with linking to official docs if they'd cover this topic sufficiently -- this page in particular looks pretty solid.

I'm coming from a Java background where we can just use an EnumSet to represent bitflags, so I'm still wrangling with C#'s lack of an equivalent.