Grouping Exported Properties in the Editor

[gg-yb]

Motivation

For quality of life, it is sometimes advisable to group related properties in the editor. This is already possible with GDScript, and used extensively by the built-in node types in Godot.

Examples, and a first flawed attempt at introducing this to gdext can be seen in #214.

On Syntax

There are different proposals for syntax, each of which have their unique pros and cons. Some of these originate from the same issue in gdnative, godot-rust/gdnative#855.

Goals

1. Rust code should not be limited with regards to item organization, field ordering, field naming etc. as to not violate expectations of developers coming from a Rust background.
2. Type-safety must be upheld, illegal states must be unrepresentable.
3. Verbosity should be kept to the minimum extent required to make the feature intuitive, understandable, and surprise-less.

#[export_group]

This was originally proposed in #214, but fails to achieve the first goal, as field naming and field ordering are mandated by group membership.

#[derive(GodotClass)]
struct Foo {
    #[export_group(name = "My Things", prefix = "my_")]
    #[export(...)]
    my_x: i32,
    #[export(...)]
    my_y: i32,
}

Marker Fields

Originally proposed in godot-rust/gdnative#855 (comment), this has the same downside as the above, but with a different syntax.

Separate Structs Deriving ExportGroup

This would introduce a new derivable trait ExportGroup which would allow use as a property type. The exported fields of the struct deriving this trait would be available as grouped properties.

#[derive(ExportGroup)]
#[group(name="Offset", prefix="offset_")]
struct OffsetGroup {
    #[export]
    x: f32,
    #[export]
    y: f32,
}

#[derive(GodotClass)]
#[class(init, base=Node)]
struct MyNode {
    #[export(group)]
    offsets: OffsetGroup,
}

A question arising here is whether to allow overriding the name and prefix at the site of usage, which would enable uses such as

#[derive(ExportGroup)]
struct MyImportantType {
    #[export]
    a: i32,
    #[export]
    b: GodotString,
}

#[derive(GodotClass)]
struct Foo {
    #[export(group_name="Element 1", prefix="element_1_")]
    el1: MyImportantType,
    #[export(group_name="Element 2", prefix="element_2_")]
    el2: MyImportantType,
}

which enables structs to be re-used as custom (domain specific) property types which are reusable over many structs.

Use Marker Structs

Similar to the previous approach, but require fields to be kept on the struct deriving GodotClass.

#[derive(ExportGroup)]
#[group(name="Offset", prefix="offset_")]
struct OffsetGroup; // just a tag

#[derive(GodotClass)]
#[class(init, base=Node)]
struct MyNode {
    #[export(group = OffsetGroup)]
    offset_x: f32,
    #[export(group = OffsetGroup)]
    offset_y: f32,
}

Loses the reusability option of the previous approach, but more close to how the data would be laid out in GDScript.

String Based Groups

Like the previous approach, but instead of marker structs it uses string-based group identifiers which do not actually exist as Rust items.

#[derive(GodotClass)]
#[class(init, base=Node)]
#[group(name="Offset", prefix="offset_")]
struct MyNode {
    #[export(group = "Offset")]
    offset_x: f32,
    #[export(group = "Offset")]
    offset_y: f32,
}

Explicit Property Paths

I do not know much about gdnative, but this seems to be a way to achieve property groups there:

#[property(path = "foo/bar")]

creates a property available as bar in a group foo. This has the advantage of decoupling the notion of groups from Rust entirely, and making it purely aesthetic, but when reusability of domain-specific editor-editable types is a concern, this may actually be a downside.

[lilizoey]

Personally I'd prefer the structs deriving ExportGroup approach, if they could additionally be used for making non-grouped it would also give us a way to reuse exports between different classes that have the same exported variables but dont necessarily want to group them.

i think allowing you to override the name at the usage site would also be good.

[lilizoey]

Another thing to consider is subgroups. A group can have subgroups, but subgroups can't have subgroups.

[FlooferLand]

Not exactly sure if this would work syntactically, but I did subconciously end up trying this while i was trying to blindly figure out whenever export_group existed:

#[export_group("Settings")] {
    #[export] volume: f32,
    #[export] pitch: f32
}

I'm not sure whenever this could work inside a struct declaration (I seem to get syntax errors trying it out) but I have used this type of syntax before inside function bodies (i've used it with #[cfg()] to return different values based on what feature is enabled).

[fpdotmonkey]

What about doing it as a trait? The macro-based APIs could also be provided, but a trait-based API could be a little nicer for more complex applications. Here's a back-of-the-napkin design for what it could look like.

impl EditorRepr for MyClass {
    fn repr(&self, editor_stuff: EditorStuff) -> EditorStuff {
        editor_stuff
            .default(self.float) // do nothing fancy for .default()
            .group( // provide a label and a chain of parameters
                "Several things"
                |ed_stuff| {
                    ed_stuff
                        .different_repr(self.happiness)
                        .default(self.position)
                        .done()
                })
            .done()
    }
}

[lilizoey]

What about doing it as a trait?

I was thinking that it'd be nice if the Property trait could declare property groups as well as just properties somehow.

[Bromeon]

What about doing it as a trait? The macro-based APIs could also be provided, but a trait-based API could be a little nicer for more complex applications.

This is anyway planned as part of #4, but it would need the whole builder API infrastructure, which is not yet in place. Eventually the idea is that the proc-macro is just a frontend that uses the builders in the backend. Currently the development is quite usage-driven (building the proc-macro API first).

[Bromeon]

For a workaround, see also Discord.

[gg-yb]

For a workaround, see also Discord.

Hey, thanks for the information that there is a workaround!

Is it possible to copy-paste the relevant content into this GitHub thread if the content is in a form where it could easily be reproduced here? If so, that would be greatly appreciated as we cannot access Discord from within company networks and on company devices due to a network blocklist.

As a positive side-effect, that would also help searchability of the relevant topics here on the site :)

[Bromeon]

I don't want to copy the original picture without the author's consent, but to sum up:

You can emulate the workaround using dummy properties (whose value, here u32, is unused) and the usage_flags key of the #[var] attribute. The indentation is for illustration purposes.

// Properties outside a group.
#[export]
level_name: GString,


// First group.
#[var(usage_flags = [GROUP, EDITOR, READ_ONLY])
configurations: u32,

    #[export(file = "*.toml")]
    map_config_file: GString,

    #[export(file = "*.toml")]
    enemy_config_file: GString,


// Second group.
#[var(usage_flags = [GROUP, EDITOR, READ_ONLY])
world_parameters: u32,

    #[export]
    world_size: Vector2i,

    #[export]
    gravity: f32,

    #[export]
    particles: Option<Gd<GpuParticles2D>>,

It's worth noting that this relies on the order of fields being registered in the order of declaration, which isn't something we guarantee (while I don't plan on changing it, there may be reasons in the future). And probably some other implementation details... So use at your own risk 🙂

[Bromeon]

Out of curiosity, are you using godot-rust at work? Are you allowed to say more about it (can also be non-publicly)? ☺️

[Yarwin]

I'll try to implement it soon.

I would like to address two problems – one being bloated structs declaration (having 200+ lines blob that declares all the exposed vars, properties and rust fields is just silly and navigating around can get stupidly challenging) and another being, obviously, an export groups themselves.

In general I would go for API such as:

// allow to re-use export groups for composition etc
mod foreign {
// Everything is declared the same as in `#[derive(GodotClass)]`.
#[derive(ExportGroup)]
struct MyGroup {
      /// Ideally the docs should work.
      #[export]
      x: f32,
      /// same for `#[init(...)]`
      #[init(val = 4.0)]
      #[export]
      y: f32,
      // OnReady<...> and OnEditor<...> should behave the same.
      #[export]
      u: OnEditor<Gd<resource>>
      #[init(node = "Node")]
      #[export]
      y: OnReady<Gd<Node>>,
      z: f32,
}
}

#[derive(GodotClass)]
#[class(init, base=Node)]
struct MyNode {
    #[export]
    my_ungrouped_export: f32,

    // includes all properties&vars defined on MyGroup in MyNode, but doesn't define a group
    #[property_group]
    a: MyGroup,

    // includes all properties & vars defined on MyGroup in MyNode, doesn't create group and all the properties are exposed as `my_properties_{field_name}`
    #[property_group(prefix = "my_properties_")]
    b: MyGroup,

    // New export group. All fields are exposed as `my_group_field_name` in `group_name`. `export_group` seems mouthful 😶 – but `group` is too confusing and not descriptive enough IMO (`group` in `property_group` might refer to group name OR properties group name (prefix) – `export_group` is explicit)
    // also it is named `export_group` in gdscript which makes it easy to discover
    #[property_group(export_group = "group_name", prefix = "my_group_")]
    c: MyGroup,

    // We shouldn't allow to expose the group with the same fields/properties names twice – ideally it should raise compiling error with some sane error message.
    // #[property_group]
    // compile_error: MyGroup,

    #[export]
    some_ungrouped_export: f32,

    // similar to #[var(usage_flags = [GROUP, EDITOR, READ_ONLY]) my_group_name: u32. 
    // Doesn't require placeholder field – we can inform godot about given property directly 
    // If we want to have both, this attribute **must** be named the same as in `#[property_group]` attribute
    #[export_group("my_group_2")]
    #[export]
    some_field_in_my_group_2: f32,
    // Maybe? Has nice side effect of allowing us to "stack" various declarations which is neat.
    #[property_group(prefix="in_group_2_")]
    d: MyGroup,
}

Having both #[export_group("my_group")] and #[property_group(export_group = "my_group")] might be silly, but IMO it makes life a bit easier (easier to keep it consistent if we are re-using the same group across multiple class declarations, it is also easier to spot&refactor with regex and whatnot).

I might also try group instead of property_group (or properties_group) 🤔