Support every class-registration option that Godot offers

[lilizoey]

Edit bromeon: updated list according to latest developments.

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
• 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

Not necessary

• get_rid_func -- already available in regular class APIs
• 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

Not planned for now

• class_userdata
• 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

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.

[Bromeon]

I updated the list:

• validate_property_func has been implemented in Add "validate_property" virtual func #1030.

• get_rid was originally a C interface function, but has also been a regular virtual function since Godot 4.0. It has subsequently been removed from newer iterations in the C interface (Remove get_rid_func from GDExtensionClassCreationInfo4 godotengine/godot#96787). Either way, the function is available as IResource::get_rid().

---

The only missing part is now is_virtual. According to godotengine/godot#58972:

• Previous "virtual" classes (which can't be instantiated) are now correctly named "abstract" (GDREGISTER_ABSTRACT_CLASS).
• Added a new "virtual" category for classes, they can't be instantiated from the editor, but can be inherited from script and extensions (GDREGISTER_VIRTUAL_CLASS).

Edit: virtual/abstract-ness isn't exposed in GDExtension but can be seen in the registration C++ files (current commit godotengine/godot@6c9765d)

• https://github.com/godotengine/godot/blob/master/servers/register_server_types.cpp
• https://github.com/godotengine/godot/blob/master/core/register_core_types.cpp
• https://github.com/godotengine/godot/blob/master/scene/register_scene_types.cpp
• https://github.com/godotengine/godot/blob/master/editor/register_editor_types.cpp
• plus some for specific modules like OpenXR

So it looks like latest if/when we add Rust-Rust inheritance, we could benefit from registering "Godot virtual classes" (OOP abstract base classes). We would then need a way to disable init() and maybe other ways of construction -- although the instance would likely need to be stored somewhere as a base 🤔 so Base<MyClass> should still be possible...