Builder API to register classes, functions, properties, signals

[Bromeon]

Functionality that is currently available through proc-macros should ideally be exposed in a programmatic builder API, too.

Some challenges:

• The proc-macros combined with the plugin system detect very fine-grained customization, e.g. every single method in GodotExt.
  • This would have to be manually annotated in a builder, possibly using static type information (generic arguments).
• Some of the traits and functions generated by proc-macros are internal.
  • The builder API could be more high-level and stable.
• Functions are rather verbose to register through builders, with generic-tuples. Think about ways to provide a simple interface.
  • In GDNative, this was done via Method trait, which is very flexible and general, but required full implementation for every single type. This might serve as a basis, with more higher-level concretizations.

[Bromeon]

While this feature is still far away (definitely not this year), here are already some ideas of how proc-macro APIs could map to the builder API. The philosophy is to keep the mapping somewhat intuitive, reusing names where possible and avoid too much magic.

For example, given:

#[derive(GodotClass)]
#[class(base=Node2D)]
struct MyClass {
    #[base]
    base: Base<Node2D>,

    #[onready]
    late_init: OnReady<PackedInt32Array>,
    
    #[export]
    integer: i32,
}

#[godot_api]
impl MyClass {
    #[func]
    fn regular() -> Gd<Other> {...}

    #[func(gd_self)]
    fn do_sth(this: Gd<Self>, arg: i32) {...}
}

#[godot_api]
impl INode2D for MyClass {
    fn init(base: Base<Node2D>) -> Self {...}
    fn ready(&mut self); {...}
    fn to_string() -> GString {...}
}

With builders and zero proc-macros, it could look something like:

struct MyClass {
    base: Base<Node2D>,
    late_init: OnReady<PackedInt32Array>,
    integer: i32,
}

impl MyClass {
    fn regular() -> Gd<Other> {...}
    fn do_sth(this: Gd<Self>, arg: i32) {...}
}

// NEW: explicit GodotClass 
impl GodotClass for MyClass {
    // base, memory etc
}

impl INode2D for MyClass {
    // NEW:
    fn register(b: &mut ClassBuilder<MyClass>) {
        // Fields
        b.export_var("integer").get(Self::get_integer).set(Self::set_integer);
        b.base(Self::get_base); // returns &mut Base
        b.onready(Self::get_late_init); // returns &mut OnReady
        
        // Different kinds of methods, e.g. static/instance/Gd<Self>
        b.func("regular").method(Self::regular);
        b.func("do_sth").method_gd_self(Self::do_sth);
        
        // Special methods (we need to tell which ones are overridden, compiler can't detect it)
        b.interface() // requires INode2D bound
         .overrides(IMethod::Init | IMethod::Ready | IMethod::ToString);
    }

    fn init(base: Base<Node2D>) -> Self {...}
    fn ready(&mut self); {...}
    fn to_string() -> GString {...}
}

// in a global registration hook:
fn register_classes(b: &mut LibraryBuilder) {
    b.add_class::<MyClass>();
    ...
}

[StatisMike]

This would be great! Additional problems like the inability to register methods coming from different trait impl wouldn't be a problem then - they could be just manually added in register().

[Bromeon]

Just for completeness, I'd also like to mention fully dynamic builder APIs.

Meaning, class methods are registered based on Callable and there would be no traits to fulfill. In essence, the whole builder API would be type-erased and lower-level, closely resembling the raw C APIs. Use case might be an editor plugin that doesn't expect each class to correspond to a Rust struct, but rather allows dynamic creation of different types and nodes -- via UI, config file or network. In other words, this would allow to add new classes and methods without writing new Rust code.

I don't think we should support this, at least not at the moment. But maybe we should also establish use cases for a typed builder API more clearly, to differentiate it better from features that the proc-macro API already provides.