Add user singletons.

Allow to register user-defined engine singletons via #[class(singleton)]`.

Author: Yarwin

godot-core/src/obj/traits.rs

@@ -685,6 +685,38 @@ pub trait Singleton: GodotClass {
     fn singleton() -> Gd<Self>;
 }
 
+/// Trait for user-defined singleton classes in Godot.
+///
+/// There should be only one instance of each singleton class in the engine, accessible through [`singleton()`][Singleton::singleton].
+// For now exists mostly as a marker trait and a way to provide blanket implementation for `Singleton` trait.
+pub trait UserSingleton:
+    GodotClass + Bounds<Declarer = bounds::DeclUser, Memory = bounds::MemManual>
+{
+}
+
+impl<T> Singleton for T
+where
+    T: UserSingleton + Inherits<crate::classes::Object>,
+{
+    fn singleton() -> Gd<T> {
+        // Note: with safeguards enabled `singleton_unchecked` will panic if Singleton can't be retrieved.
+        #[cfg(not(safeguards_strict))]
+        {
+            // SAFETY: The caller must ensure that `class_name` corresponds to the actual class name of type `T`.
+            // This is always true for proc-macro derived user singletons.
+            unsafe {
+                crate::classes::singleton_unchecked(&<T as GodotClass>::class_id().to_string_name())
+            }
+        }
+        #[cfg(safeguards_strict)]
+        {
+            crate::classes::Engine::singleton()
+                .get_singleton(&<T as GodotClass>::class_id().to_string_name())
+                .unwrap_or_else(|| panic!("Singleton {} not found. User singleton must be registered under its class name.", T::class_id())).cast()
+        }
+    }
+}
+
 impl<T> NewAlloc for T
 where
     T: cap::GodotDefault + Bounds<Memory = bounds::MemManual>,
@@ -705,6 +737,7 @@ pub mod cap {
     use super::*;
     use crate::builtin::{StringName, Variant};
     use crate::meta::PropertyInfo;
+    use crate::obj::{Base, Bounds, Gd};
     use crate::storage::{IntoVirtualMethodReceiver, VirtualMethodReceiver};
 
     /// Trait for all classes that are default-constructible from the Godot engine.
@@ -740,7 +773,7 @@ pub mod cap {
             // 1. Separate trait `GodotUserDefault` for user classes, which then proliferates through all APIs and makes abstraction harder.
             // 2. Repeatedly implementing __godot_default() that forwards to something like Gd::default_user_instance(). Possible, but this
             //    will make the step toward builder APIs more difficult, as users would need to re-implement this as well.
-            sys::strict_assert_eq!(
+            debug_assert_eq!(
                 std::any::TypeId::of::<<Self as Bounds>::Declarer>(),
                 std::any::TypeId::of::<bounds::DeclUser>(),
                 "__godot_default() called on engine class; must be overridden for engine classes"

godot-core/src/registry/class.rs

@@ -61,6 +61,7 @@ fn global_dyn_traits_by_typeid() -> GlobalGuard<'static, HashMap<any::TypeId, Ve
 pub struct LoadedClass {
     name: ClassId,
     is_editor_plugin: bool,
+    unregister_singleton_fn: Option<fn()>,
 }
 
 /// Represents a class which is currently loaded and retained in memory -- including metadata.
@@ -93,6 +94,8 @@ struct ClassRegistrationInfo {
     user_register_fn: Option<ErasedRegisterFn>,
     default_virtual_fn: Option<GodotGetVirtual>, // Optional (set if there is at least one OnReady field)
     user_virtual_fn: Option<GodotGetVirtual>, // Optional (set if there is a `#[godot_api] impl I*`)
+    register_singleton_fn: Option<fn()>,
+    unregister_singleton_fn: Option<fn()>,
 
     /// Godot low-level class creation parameters.
     godot_params: GodotCreationInfo,
@@ -180,6 +183,8 @@ pub(crate) fn register_class<
         is_editor_plugin: false,
         dynify_fns_by_trait: HashMap::new(),
         component_already_filled: Default::default(), // [false; N]
+        register_singleton_fn: None,
+        unregister_singleton_fn: None,
     });
 }
 
@@ -215,10 +220,15 @@ pub fn auto_register_classes(init_level: InitLevel) {
     // but it is much slower and doesn't guarantee that all the dependent classes will be already loaded in most cases.
     register_classes_and_dyn_traits(&mut map, init_level);
 
+    // Workaround for Godot before 4.4.1:
     // Editor plugins should be added to the editor AFTER all the classes has been registered.
     // Adding EditorPlugin to the Editor before registering all the classes it depends on might result in crash.
     let mut editor_plugins: Vec<ClassId> = Vec::new();
 
+    // User Singletons must be initialized only after all the other classes
+    // (on which they might depend on in form of properties and whatnot).
+    let mut singletons: Vec<fn()> = Vec::new();
+
     // Actually register all the classes.
     for info in map.into_values() {
         #[cfg(feature = "debug-log")]
@@ -228,14 +238,22 @@ pub fn auto_register_classes(init_level: InitLevel) {
             editor_plugins.push(info.class_name);
         }
 
+        if let Some(register_singleton_fn) = info.register_singleton_fn {
+            singletons.push(register_singleton_fn)
+        }
+
         register_class_raw(info);
 
         out!("Class {class_name} loaded.");
     }
 
-    // Will imminently add given class to the editor.
+    for register_singleton_fn in singletons {
+        register_singleton_fn()
+    }
+
+    // Will imminently add given class to the editor in Godot before 4.4.1.
     // It is expected and beneficial behaviour while we load library for the first time
-    // but (for now) might lead to some issues during hot reload.
+    // but might lead to some issues during hot reload.
     // See also: (https://github.com/godot-rust/gdext/issues/1132)
     for editor_plugin_class_name in editor_plugins {
         unsafe { interface_fn!(editor_add_plugin)(editor_plugin_class_name.string_sys()) };
@@ -259,6 +277,7 @@ fn register_classes_and_dyn_traits(
         let loaded_class = LoadedClass {
             name: class_name,
             is_editor_plugin: info.is_editor_plugin,
+            unregister_singleton_fn: info.unregister_singleton_fn,
         };
         let metadata = ClassMetadata {};
 
@@ -420,6 +439,8 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             register_properties_fn,
             free_fn,
             default_get_virtual_fn,
+            unregister_singleton_fn,
+            register_singleton_fn,
             is_tool,
             is_editor_plugin,
             is_internal,
@@ -431,6 +452,8 @@ fn fill_class_info(item: PluginItem, c: &mut ClassRegistrationInfo) {
             c.default_virtual_fn = default_get_virtual_fn;
             c.register_properties_fn = Some(register_properties_fn);
             c.is_editor_plugin = is_editor_plugin;
+            c.register_singleton_fn = register_singleton_fn;
+            c.unregister_singleton_fn = unregister_singleton_fn;
 
             // Classes marked #[class(no_init)] are translated to "abstract" in Godot. This disables their default constructor.
             // "Abstract" is a misnomer -- it's not an abstract base class, but rather a "utility/static class" (although it can have instance
@@ -632,6 +655,12 @@ fn unregister_class_raw(class: LoadedClass) {
         out!("> Editor plugin removed");
     }
 
+    // Similarly to EditorPlugin – given instance is being freed and will not be recreated
+    // during hot reload (a new, independent one will be created instead).
+    if let Some(unregister_singleton_fn) = class.unregister_singleton_fn {
+        unregister_singleton_fn();
+    }
+
     #[allow(clippy::let_unit_value)]
     let _: () = unsafe {
         interface_fn!(classdb_unregister_extension_class)(
@@ -670,6 +699,8 @@ fn default_registration_info(class_name: ClassId) -> ClassRegistrationInfo {
         user_register_fn: None,
         default_virtual_fn: None,
         user_virtual_fn: None,
+        register_singleton_fn: None,
+        unregister_singleton_fn: None,
         godot_params: default_creation_info(),
         init_level: InitLevel::Scene,
         is_editor_plugin: false,

godot-core/src/registry/plugin.rs

@@ -10,7 +10,10 @@ use std::{any, fmt};
 
 use crate::init::InitLevel;
 use crate::meta::ClassId;
-use crate::obj::{bounds, cap, Bounds, DynGd, Gd, GodotClass, Inherits, UserClass};
+use crate::obj::{
+    bounds, cap, Bounds, DynGd, Gd, GodotClass, Inherits, NewAlloc, Singleton, UserClass,
+    UserSingleton,
+};
 use crate::registry::callbacks;
 use crate::registry::class::GodotGetVirtual;
 use crate::{classes, sys};
@@ -180,6 +183,12 @@ pub struct Struct {
         instance: sys::GDExtensionClassInstancePtr,
     ),
 
+    /// `#[class(singleton)]`
+    pub(crate) register_singleton_fn: Option<fn()>,
+
+    /// `#[class(singleton)]`
+    pub(crate) unregister_singleton_fn: Option<fn()>,
+
     /// Calls `__before_ready()`, if there is at least one `OnReady` field. Used if there is no `#[godot_api] impl` block
     /// overriding ready.
     pub(crate) default_get_virtual_fn: Option<GodotGetVirtual>,
@@ -209,6 +218,8 @@ impl Struct {
                 raw: callbacks::register_user_properties::<T>,
             },
             free_fn: callbacks::free::<T>,
+            register_singleton_fn: None,
+            unregister_singleton_fn: None,
             default_get_virtual_fn: None,
             is_tool: false,
             is_editor_plugin: false,
@@ -257,6 +268,28 @@ impl Struct {
         self
     }
 
+    pub fn with_singleton<T>(mut self) -> Self
+    where
+        T: UserSingleton
+            + Bounds<Memory = bounds::MemManual, Declarer = bounds::DeclUser>
+            + NewAlloc
+            + Inherits<classes::Object>,
+    {
+        self.register_singleton_fn = Some(|| {
+            crate::classes::Engine::singleton()
+                .register_singleton(&T::class_id().to_string_name(), &T::new_alloc());
+        });
+
+        self.unregister_singleton_fn = Some(|| {
+            let singleton = T::singleton();
+            crate::classes::Engine::singleton()
+                .unregister_singleton(&T::class_id().to_string_name());
+            singleton.free();
+        });
+
+        self
+    }
+
     pub fn with_internal(mut self) -> Self {
         self.is_internal = true;
         self

godot-macros/src/class/derive_godot_class.rs

@@ -78,25 +78,13 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
 
     let godot_exports_impl = make_property_impl(class_name, &fields);
 
-    let godot_withbase_impl = if let Some(Field { name, ty, .. }) = &fields.base_field {
-        // Apply the span of the field's type so that errors show up on the field's type.
-        quote_spanned! { ty.span()=>
-            impl ::godot::obj::WithBaseField for #class_name {
-                fn to_gd(&self) -> ::godot::obj::Gd<#class_name> {
-                    // By not referencing the base field directly here we ensure that the user only gets one error when the base
-                    // field's type is wrong.
-                    let base = <#class_name as ::godot::obj::WithBaseField>::base_field(self);
-
-                    base.__constructed_gd().cast()
-                }
+    let godot_withbase_impl = make_with_base_impl(&fields.base_field, class_name);
 
-                fn base_field(&self) -> &::godot::obj::Base<<#class_name as ::godot::obj::GodotClass>::Base> {
-                    &self.#name
-                }
-            }
-        }
+    let (user_singleton_impl, init_level_impl) = if struct_cfg.is_singleton {
+        modifiers.push(quote! { with_singleton::<#class_name> });
+        make_singleton_impl(class_name)
     } else {
-        TokenStream::new()
+        (TokenStream::new(), TokenStream::new())
     };
 
     let (user_class_impl, has_default_virtual) = make_user_class_impl(
@@ -164,6 +152,8 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         impl ::godot::obj::GodotClass for #class_name {
             type Base = #base_class;
 
+            #init_level_impl
+
             // Code duplicated in godot-codegen.
             fn class_id() -> ::godot::meta::ClassId {
                 use ::godot::meta::ClassId;
@@ -194,6 +184,7 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
         #deny_manual_init_macro
         #( #deprecations )*
         #( #errors )*
+        #user_singleton_impl
 
         #struct_docs_registration
         ::godot::sys::plugin_add!(#prv::__GODOT_PLUGIN_REGISTRY; #prv::ClassPlugin::new::<#class_name>(
@@ -206,6 +197,43 @@ pub fn derive_godot_class(item: venial::Item) -> ParseResult<TokenStream> {
     })
 }
 
+fn make_with_base_impl(base_field: &Option<Field>, class_name: &Ident) -> TokenStream {
+    if let Some(Field { name, ty, .. }) = base_field {
+        // Apply the span of the field's type so that errors show up on the field's type.
+        quote_spanned! { ty.span()=>
+            impl ::godot::obj::WithBaseField for #class_name {
+                fn to_gd(&self) -> ::godot::obj::Gd<#class_name> {
+                    // By not referencing the base field directly here we ensure that the user only gets one error when the base
+                    // field's type is wrong.
+                    let base = <#class_name as ::godot::obj::WithBaseField>::base_field(self);
+
+                    base.__constructed_gd().cast()
+                }
+
+                fn base_field(&self) -> &::godot::obj::Base<<#class_name as ::godot::obj::GodotClass>::Base> {
+                    &self.#name
+                }
+            }
+        }
+    } else {
+        TokenStream::new()
+    }
+}
+
+/// Generates registration for user singleton and proper INIT_LEVEL declaration.
+///
+/// Before Godot4.4 built-in Engine singleton – required for registration – wasn't available before `InitLevel::Scene`.
+fn make_singleton_impl(class_name: &Ident) -> (TokenStream, TokenStream) {
+    (
+        quote! {
+            impl ::godot::obj::UserSingleton for #class_name {}
+        },
+        quote! {
+            const INIT_LEVEL: ::godot::init::InitLevel = ::godot::init::InitLevel::Scene;
+        },
+    )
+}
+
 /// Generates code for a decl-macro, which takes any item and prepends it with the visibility marker of the class.
 ///
 /// Used to access the visibility of the class in other proc-macros like `#[godot_api]`.
@@ -301,6 +329,7 @@ struct ClassAttributes {
     base_ty: Ident,
     init_strategy: InitStrategy,
     is_tool: bool,
+    is_singleton: bool,
     is_internal: bool,
     rename: Option<Ident>,
     deprecations: Vec<TokenStream>,
@@ -508,6 +537,7 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
     let mut base_ty = ident("RefCounted");
     let mut init_strategy = InitStrategy::UserDefined;
     let mut is_tool = false;
+    let mut is_singleton = false;
     let mut is_internal = false;
     let mut rename: Option<Ident> = None;
     let mut deprecations = vec![];
@@ -531,6 +561,11 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
             is_tool = true;
         }
 
+        // #[class(singleton)]
+        if parser.handle_alone("singleton")? {
+            is_singleton = true;
+        }
+
         // Removed #[class(editor_plugin)]
         if let Some(key) = parser.handle_alone_with_span("editor_plugin")? {
             return bail!(
@@ -581,6 +616,7 @@ fn parse_struct_attributes(class: &venial::Struct) -> ParseResult<ClassAttribute
         base_ty,
         init_strategy,
         is_tool,
+        is_singleton,
         is_internal,
         rename,
         deprecations,

godot-macros/src/lib.rs

@@ -481,6 +481,26 @@ use crate::util::{bail, ident, KvParser};
 /// Even though this class is a `Node` and it has an init function, it still won't show up in the editor as a node you can add to a scene
 /// because we have added a `hidden` key to the class. This will also prevent it from showing up in documentation.
 ///
+/// ## User Engine Singletons
+///
+/// Non-refcounted classes can be registered as an engine singleton with `#[class(singleton)]`.
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// #[derive(GodotClass)]
+/// #[class(init, singleton, base=Object)]
+/// struct MySingleton {
+///     my_field: i32,
+/// }
+///
+/// // Can be accessed as any other engine singleton.
+/// let val = MySingleton::singleton().bind().my_field;
+/// ```
+///
+/// Engine Singletons always run in the editor (similarly to `#[class(tool)]`) and will never be represented by a placeholder instances.
+///
+/// GDScript will be prohibited from creating new instances of said class.
+///
 /// # Further field customization
 ///
 /// ## Fine-grained inference hints
@@ -554,6 +574,7 @@ use crate::util::{bail, ident, KvParser};
     alias = "base",
     alias = "init",
     alias = "no_init",
+    alias = "singleton",
     alias = "var",
     alias = "export",
     alias = "tool",