Class icons

- register via #[class(icon = EXPR)]
- requires api 4.4+, uses GDExtensionClassCreationInfo4.icon_path
- global_icon_strings(): GlobalGuard that stores icons by ClassId

Author: Paperback

godot-core/src/private.rs

@@ -186,6 +186,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

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,
     })
 }