GdExtension and class icons defined by macro attributes

Author: Paperback

godot-core/src/init/mod.rs

@@ -27,6 +27,22 @@ struct InitUserData {
     main_loop_callbacks: sys::GDExtensionMainLoopCallbacks,
 }
 
+#[derive(Copy, Clone, Default)]
+pub struct ExtensionConfig {
+    pub icon: Option<&'static str>,
+}
+
+impl ExtensionConfig {
+    pub const fn new() -> Self {
+        Self { icon: None }
+    }
+
+    pub const fn with_icon(mut self, icon: &'static str) -> Self {
+        self.icon = Some(icon);
+        self
+    }
+}
+
 #[cfg(since_api = "4.5")]
 unsafe extern "C" fn startup_func<E: ExtensionLibrary>() {
     E::on_stage_init(InitStage::MainLoop);
@@ -117,6 +133,11 @@ pub unsafe fn __gdext_load_library<E: ExtensionLibrary>(
     is_success.unwrap_or(0)
 }
 
+/// This contains metadata declared through [`#[gdextension]`](attr.gdextension.html)
+pub fn extension_config() -> ExtensionConfig {
+    crate::private::extension_config()
+}
+
 static LEVEL_SERVERS_CORE_LOADED: AtomicBool = AtomicBool::new(false);
 
 unsafe extern "C" fn ffi_initialize_layer<E: ExtensionLibrary>(
@@ -289,6 +310,18 @@ fn gdext_on_level_deinit(level: InitLevel) {
 /// Note that this only changes the name. You cannot provide your own function -- use the [`on_level_init()`][ExtensionLibrary::on_level_init]
 /// hook for custom startup logic.
 ///
+/// # Extension metadata
+/// Provide additional metadata directly on the attribute. For example, on Godot 4.4+ you can assign the icon shown in the editor's
+/// extension list like so:
+/// ```no_run
+/// # use godot::init::*;
+/// struct MyExtension;
+///
+/// #[gdextension(icon = "res://addons/my_extension/icon.svg")]
+/// unsafe impl ExtensionLibrary for MyExtension {}
+/// ```
+/// The values provided here are exposed via [`extension_config()`] for tooling and build scripts.
+///
 /// # Availability of Godot APIs during init and deinit
 // Init order: see also special_cases.rs > classify_codegen_level().
 /// Godot loads functionality gradually during its startup routines, and unloads it during shutdown. As a result, Godot classes are only

godot-core/src/private.rs

@@ -57,6 +57,7 @@ static ERROR_PRINT_LEVEL: atomic::AtomicU8 = atomic::AtomicU8::new(2);
 sys::plugin_registry!(pub __GODOT_PLUGIN_REGISTRY: ClassPlugin);
 #[cfg(all(since_api = "4.3", feature = "register-docs"))]
 sys::plugin_registry!(pub __GODOT_DOCS_REGISTRY: DocsPlugin);
+sys::plugin_registry!(pub __GODOT_EXTENSION_CONFIG_REGISTRY: crate::init::ExtensionConfig);
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Call error handling
@@ -151,6 +152,11 @@ pub(crate) fn iterate_plugins(mut visitor: impl FnMut(&ClassPlugin)) {
     sys::plugin_foreach!(__GODOT_PLUGIN_REGISTRY; visitor);
 }
 
+pub(crate) fn extension_config() -> crate::init::ExtensionConfig {
+    let guard = __GODOT_EXTENSION_CONFIG_REGISTRY.lock().unwrap();
+    guard.last().copied().unwrap_or_default()
+}
+
 #[cfg(all(since_api = "4.3", feature = "register-docs"))]
 pub(crate) fn iterate_docs_plugins(mut visitor: impl FnMut(&DocsPlugin)) {
     sys::plugin_foreach!(__GODOT_DOCS_REGISTRY; visitor);
@@ -186,6 +192,7 @@ pub trait You_forgot_the_attribute__godot_api {}
 
 pub struct ClassConfig {
     pub is_tool: bool,
+    pub icon: Option<&'static str>,
 }
 
 // ----------------------------------------------------------------------------------------------------------------------------------------------

godot-core/src/registry/class.rs

@@ -53,6 +53,14 @@ fn global_dyn_traits_by_typeid() -> GlobalGuard<'static, HashMap<any::TypeId, Ve
     lock_or_panic(&DYN_TRAITS_BY_TYPEID, "dyn traits")
 }
 
+#[cfg(since_api = "4.4")]
+fn global_icon_strings() -> GlobalGuard<'static, HashMap<ClassId, crate::builtin::GString>> {
+    static ICON_STRINGS_BY_NAME: Global<HashMap<ClassId, crate::builtin::GString>> =
+        Global::default();
+
+    lock_or_panic(&ICON_STRINGS_BY_NAME, "icon strings (by name)")
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 
 /// Represents a class which is currently loaded and retained in memory.
@@ -426,6 +434,7 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             is_instantiable,
             reference_fn,
             unreference_fn,
+            icon,
         }) => {
             c.parent_class_name = Some(base_class_name);
             c.default_virtual_fn = default_get_virtual_fn;
@@ -458,6 +467,26 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             .expect("duplicate: recreate_instance_func (def)");
 
             c.godot_params.is_exposed = sys::conv::bool_to_sys(!is_internal);
+            #[cfg(before_api = "4.4")]
+            let _ = icon; // mark used
+            #[cfg(since_api = "4.4")]
+            if let Some(icon_path) = icon {
+                // Convert to GString and store in global map to keep it alive for program lifetime
+                let icon_gstring = crate::builtin::GString::from(icon_path);
+
+                let mut icon_map = global_icon_strings();
+                icon_map.insert(c.class_name, icon_gstring);
+
+                // Get pointer after insertion, while lock is still held
+                // SAFETY: The GString is stored in a static HashMap, so the pointer remains valid
+                // even after the lock guard is dropped. We must retrieve the pointer while holding
+                // the lock to ensure the HashMap isn't being modified concurrently.
+                let icon_ptr = icon_map.get(&c.class_name).unwrap().string_sys()
+                    as sys::GDExtensionConstStringPtr;
+
+                // Set the pointer in godot_params
+                c.godot_params.icon_path = icon_ptr;
+            }
 
             #[cfg(before_api = "4.3")]
             let _ = is_tool; // mark used
@@ -559,6 +588,23 @@ fn register_class_raw(mut info: ClassRegistrationInfo) {
         info.godot_params.get_virtual_func = info.user_virtual_fn.or(info.default_virtual_fn);
     }
 
+    // If no class-level icon was set, use the extension-level icon as fallback (if available)
+    #[cfg(since_api = "4.4")]
+    if info.godot_params.icon_path.is_null() {
+        if let Some(extension_icon) = crate::init::extension_config().icon {
+            let icon_gstring = crate::builtin::GString::from(extension_icon);
+
+            // SAFETY: The GString is stored in a static HashMap, so the pointer remains valid
+            // even after the lock guard is dropped. We must retrieve the pointer while holding
+            // the lock to ensure the HashMap isn't being modified concurrently.
+            let mut icon_map = global_icon_strings();
+            let icon_ptr = icon_gstring.string_sys() as sys::GDExtensionConstStringPtr;
+            icon_map.insert(class_name, icon_gstring);
+
+            info.godot_params.icon_path = icon_ptr;
+        }
+    }
+
     // The explicit () type notifies us if Godot API ever adds a return type.
     let registration_failed = unsafe {
         // Try to register class...

godot-core/src/registry/plugin.rs

@@ -195,6 +195,9 @@ pub struct Struct {
 
     /// Whether the class has a default constructor.
     pub(crate) is_instantiable: bool,
+
+    /// Icon path from `#[class(icon = "path")]`.
+    pub(crate) icon: Option<&'static str>,
 }
 
 impl Struct {
@@ -214,6 +217,7 @@ impl Struct {
             is_editor_plugin: false,
             is_internal: false,
             is_instantiable: false,
+            icon: None,
             // While Godot doesn't do anything with these callbacks for non-RefCounted classes, we can avoid instantiating them in Rust.
             reference_fn: refcounted.then_some(callbacks::reference::<T>),
             unreference_fn: refcounted.then_some(callbacks::unreference::<T>),
@@ -252,6 +256,12 @@ impl Struct {
         self
     }
 
+    #[cfg(since_api = "4.4")]
+    pub fn with_icon(mut self, icon: &'static str) -> Self {
+        self.icon = Some(icon);
+        self
+    }
+
     pub fn with_editor_plugin(mut self) -> Self {
         self.is_editor_plugin = true;
         self

godot-macros/src/class/derive_godot_class.rs

@@ -103,6 +103,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         class_name,
         &struct_cfg.base_ty,
         struct_cfg.is_tool,
+        struct_cfg.icon.as_ref(),
         &fields.all_fields,
     );
 
@@ -146,6 +147,13 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         modifiers.push(quote! { with_tool })
     }
 
+    // Handle icon separately since it takes an argument (can't use the modifiers pattern)
+    let icon_modifier = if let Some(icon) = &struct_cfg.icon {
+        quote! { .with_icon(#icon) }
+    } else {
+        quote! {}
+    };
+
     // Declares a "funcs collection" struct that, for holds a constant for each #[func].
     // That constant maps the Rust name (constant ident) to the Godot registered name (string value).
     let funcs_collection_struct_name = format_funcs_collection_struct(class_name);
@@ -198,7 +206,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         #struct_docs_registration
         ::godot::sys::plugin_add!(#prv::__GODOT_PLUGIN_REGISTRY; #prv::ClassPlugin::new::<#class_name>(
             #prv::PluginItem::Struct(
-                #prv::Struct::new::<#class_name>()#(.#modifiers())*
+                #prv::Struct::new::<#class_name>()#(.#modifiers())*#icon_modifier
             )
         ));
 
@@ -303,6 +311,7 @@ struct ClassAttributes {
     is_tool: bool,
     is_internal: bool,
     rename: Option<Ident>,
+    icon: Option<TokenStream>,
     deprecations: Vec<TokenStream>,
 }
 
@@ -421,6 +430,7 @@ fn make_user_class_impl(
     class_name: &Ident,
     trait_base_class: &Ident,
     is_tool: bool,
+    icon: Option<&TokenStream>,
     all_fields: &[Field],
 ) -> (TokenStream, bool) {
     #[cfg(feature = "codegen-full")]
@@ -480,12 +490,19 @@ fn make_user_class_impl(
         None
     };
 
+    let icon = if let Some(expr) = icon {
+        quote! { Some(#expr) }
+    } else {
+        quote! { None }
+    };
+
     let user_class_impl = quote! {
         impl ::godot::obj::UserClass for #class_name {
             #[doc(hidden)]
             fn __config() -> ::godot::private::ClassConfig {
                 ::godot::private::ClassConfig {
                     is_tool: #is_tool,
+                    icon: #icon,
                 }
             }
 
@@ -510,6 +527,7 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
     let mut is_tool = false;
     let mut is_internal = false;
     let mut rename: Option<Ident> = None;
+    let mut icon: Option<TokenStream> = None;
     let mut deprecations = vec![];
 
     // #[class] attribute on struct
@@ -542,6 +560,10 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
         // #[class(rename = NewName)]
         rename = parser.handle_ident("rename")?;
 
+        // #[class(icon = "PATH")]
+        if let Some(expr) = parser.handle_expr("icon")? {
+            icon = Some(expr);
+        }
         // #[class(internal)]
         // Named "internal" following Godot terminology: https://github.com/godotengine/godot-cpp/blob/master/include/godot_cpp/core/class_db.hpp#L327
         if parser.handle_alone("internal")? {
@@ -583,6 +605,7 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
         is_tool,
         is_internal,
         rename,
+        icon,
         deprecations,
     })
 }

godot-macros/src/gdextension.rs

@@ -29,6 +29,7 @@ pub fn attribute_gdextension(item: venial::Item) -> ParseResult<TokenStream> {
     let mut parser = KvParser::parse_required(&drained_attributes, "gdextension", &impl_decl)?;
     let entry_point = parser.handle_ident("entry_point")?;
     let entry_symbol = parser.handle_ident("entry_symbol")?;
+    let icon = parser.handle_expr("icon")?;
     parser.finish()?;
 
     if entry_point.is_some() && entry_symbol.is_some() {
@@ -50,7 +51,20 @@ pub fn attribute_gdextension(item: venial::Item) -> ParseResult<TokenStream> {
 
     let impl_ty = &impl_decl.self_ty;
 
+    let mut modifiers = Vec::new();
+    if let Some(icon) = icon {
+        modifiers.push(quote! { with_icon(#icon) });
+    }
+
+    let extension_config_registration = quote! {
+        ::godot::sys::plugin_add!(
+            ::godot::private::__GODOT_EXTENSION_CONFIG_REGISTRY;
+            ::godot::init::ExtensionConfig::new()#( .#modifiers )*
+        );
+    };
+
     Ok(quote! {
+        #extension_config_registration
         #deprecation
         #impl_decl