Support every class-registration option that Godot offers

[lilizoey]

To register a class with godot we use the GDExtensionClassCreationInfo struct, which has two versions depending on the godot version:

pub struct GDExtensionClassCreationInfo2 {
    pub is_virtual: GDExtensionBool,
    pub is_abstract: GDExtensionBool,
    pub is_exposed: GDExtensionBool, // only in 2
    pub set_func: GDExtensionClassSet,
    pub get_func: GDExtensionClassGet,
    pub get_property_list_func: GDExtensionClassGetPropertyList,
    pub free_property_list_func: GDExtensionClassFreePropertyList,
    pub property_can_revert_func: GDExtensionClassPropertyCanRevert,
    pub property_get_revert_func: GDExtensionClassPropertyGetRevert,
    pub validate_property_func: GDExtensionClassValidateProperty, // only in 2
    pub notification_func: GDExtensionClassNotification2, // different type in 2
    pub to_string_func: GDExtensionClassToString,
    pub reference_func: GDExtensionClassReference,
    pub unreference_func: GDExtensionClassUnreference,
    pub create_instance_func: GDExtensionClassCreateInstance,
    pub free_instance_func: GDExtensionClassFreeInstance,
    pub recreate_instance_func: GDExtensionClassRecreateInstance,
    pub get_virtual_func: GDExtensionClassGetVirtual,
    pub get_virtual_call_data_func: GDExtensionClassGetVirtualCallData, // only in 2
    pub call_virtual_with_data_func: GDExtensionClassCallVirtualWithData, // only in 2
    pub get_rid_func: GDExtensionClassGetRID,
    pub class_userdata: *mut ::std::os::raw::c_void,
}

Each corresponding to something configurable about class registration.

Current state of user-available registration options:

• is_virtual ¹
• is_abstract we might need to set this to true for classes that cant be instantiated ¹
• is_exposed
• set_func
• get_func
• get_property_list_func (Add get_property_list #707)
• free_property_list_func
• property_can_revert_func
• property_get_revert_func
• validate_property_func
• notification_func through on_notification in interface
• to_string_func through to_string in interface
• reference_func is used to update the refcount, but the user cannot add custom logic to this
• unreference_func is used to update the refcount, but the user cannot add custom logic to this
• create_instance_func based on init function in interface
• recreate_instance_func based on init function in interface
• get_virtual_func generated from virtual method implementations
• get_virtual_call_data_func mutually exclusive with get_virtual_func, will not implement without a use-case
• call_virtual_with_data_func must be implemented along with above
• get_rid_func
• class_userdata

The planned builder-api would likely want the ability to set/override these options as desired.

Footnotes

1. See this pr for information about what virtual vs abstract classes mean in godot ↩ ↩²

[Bromeon]

Thanks for listing all these functions, very useful! 👍

Two things to keep in mind:

1. The GDExtension API and user-facing bindings operate at different levels of abstraction -- not every functionality of the lower level should be 1:1 exposed as a public feature.
2. Everything that we implement now via proc-macro will need to be (at least partially) rewritten, once we have the builder API. So we should be careful to not create too much technical debt, especially in cases where there is no current demand for a feature.

Maybe handy: direct link to Godot's gdextension_interface.h on master.

[Bromeon]

Recent updates:

• Add get_property_list, property_can_revert and property_get_revert virtual methods #621 (in progress)
• Add get and set as virtual methods #567
• #[class(no_init)] to explicitly disable constructor #593 -> is_abstract

I would exclude the following from the list -- let's only implement them if we have strong demand with concrete use cases.

• get_virtual_call_data_func -- this is an alternative to get_virtual_func for languages like Go, no need right now
• call_virtual_with_data_func -- same
• class_userdata -- should remain reserved for gdext implementation. Metadata can always be added by the user as associated functions/constants.
• reference_func -- too low-level.
• unreference_func -- same.

Furthermore, is_virtual should probably not be set manually, but in conjunction with abstract classes (if that's implemented).

[Bromeon]

Let's make a concrete plan on what to support for which use cases, and then start working on them. Otherwise this becomes another eternal issue. If we don't have a use case right now, we can always open new issues once one comes up, but we shouldn't track all parameters pre-emptively just in case.

The only remaining one where I see immediate usefulness is get_rid_func. This one behaves like a regular virtual function and should be part of the interface trait for every Resource derived class. Note that this is being deprecated in favor of actual virtual functions in godotengine/godot#96787; not sure if we want to add it for compat in older Godot versions.

Also ticked off a few that have been implemented in the meantime.

[lilizoey]

i think validate_property_func would also be useful, it can be used to override properties defined by a superclass.