Merge pull request #683 from godot-rust/qol/engine-extensions

Replace `NodeExt` + `PackedSceneExt` traits with `impl` blocks, extending classes directly

Author: Bromeon

.github/workflows/full-ci.yml

@@ -109,7 +109,7 @@ jobs:
         # Note: Windows uses '--target x86_64-pc-windows-msvc' by default as Cargo argument.
         include:
           - name: macos
-            os: macos-11
+            os: macos-latest # arm64
 
           - name: windows
             os: windows-latest

godot-codegen/src/generator/classes.rs

@@ -89,7 +89,8 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         None => (quote! { crate::obj::NoBase }, None),
     };
 
-    let (constructor, godot_default_impl) = make_constructor_and_default(class, ctx);
+    let (constructor, construct_doc, godot_default_impl) = make_constructor_and_default(class, ctx);
+    let construct_doc = construct_doc.replace("Self", &class_name.rust_ty.to_string());
     let api_level = class.api_level;
     let init_level = api_level.to_init_level();
 
@@ -164,6 +165,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
             use super::*;
 
             #[doc = #class_doc]
+            #[doc = #construct_doc]
             #[derive(Debug)]
             #[repr(C)]
             pub struct #class_name {
@@ -296,13 +298,16 @@ fn make_class_module_file(classes_and_modules: Vec<GeneratedClassModule>) -> Tok
     }
 }
 
-fn make_constructor_and_default(class: &Class, ctx: &Context) -> (TokenStream, TokenStream) {
+fn make_constructor_and_default(
+    class: &Class,
+    ctx: &Context,
+) -> (TokenStream, &'static str, TokenStream) {
     let godot_class_name = &class.name().godot_ty;
     let godot_class_stringname = make_string_name(godot_class_name);
     // Note: this could use class_name() but is not yet done due to upcoming lazy-load refactoring.
     //let class_name_obj = quote! { <Self as crate::obj::GodotClass>::class_name() };
 
-    let (constructor, has_godot_default_impl);
+    let (constructor, construct_doc, has_godot_default_impl);
     if ctx.is_singleton(godot_class_name) {
         // Note: we cannot return &'static mut Self, as this would be very easy to mutably alias.
         // &'static Self would be possible, but we would lose the whole mutability information (even if that is best-effort and
@@ -318,15 +323,28 @@ fn make_constructor_and_default(class: &Class, ctx: &Context) -> (TokenStream, T
                 }
             }
         };
+        construct_doc = "# Singleton\n\n\
+            This class is a singleton. You can get the one instance using [`Self::singleton()`][Self::singleton].";
         has_godot_default_impl = false;
     } else if !class.is_instantiable {
-        // Abstract base classes or non-singleton classes without constructor
+        // Abstract base classes or non-singleton classes without constructor.
         constructor = TokenStream::new();
+        construct_doc = "# Not instantiable\n\nThis class cannot be constructed. Obtain `Gd<Self>` instances via Godot APIs.";
         has_godot_default_impl = false;
     } else {
         // Manually managed classes (Object, Node, ...) as well as ref-counted ones (RefCounted, Resource, ...).
         // The constructors are provided as associated methods in NewGd::new_gd() and NewAlloc::new_alloc().
         constructor = TokenStream::new();
+
+        if class.is_refcounted {
+            construct_doc = "# Construction\n\n\
+                This class is reference-counted. You can create a new instance using [`Self::new_gd()`][crate::obj::NewGd::new_gd]."
+        } else {
+            construct_doc = "# Construction\n\n\
+                This class is manually managed. You can create a new instance using [`Self::new_alloc()`][crate::obj::NewAlloc::new_alloc].\n\n\
+                Do not forget to call [`free()`][crate::obj::Gd::free] or hand over ownership to Godot."
+        }
+
         has_godot_default_impl = true;
     }
 
@@ -343,7 +361,7 @@ fn make_constructor_and_default(class: &Class, ctx: &Context) -> (TokenStream, T
         TokenStream::new()
     };
 
-    (constructor, godot_default_impl)
+    (constructor, construct_doc, godot_default_impl)
 }
 
 fn make_deref_impl(class_name: &TyName, base_ty: &TokenStream) -> TokenStream {

godot-codegen/src/special_cases/special_cases.rs

@@ -40,6 +40,11 @@ pub fn is_class_method_deleted(class_name: &TyName, method: &JsonClassMethod, ct
         // Already covered by manual APIs
         //| ("Object", "to_string")
         | ("Object", "get_instance_id")
+        
+        // Removed because it is a worse version of Node::get_node_or_null(): it _seems_ like it's fallible due to Option<T> return type,
+        // however Godot will emit an error message if the node is absent. In the future with non-null types, this may be re-introduced.
+        // Alternatively, both get_node/get_node_or_null could become generic and use the get_node_as/try_get_node_as impl (removing those).
+        | ("Node", "get_node")
 
         // Removed in https://github.com/godotengine/godot/pull/88418, but they cannot reasonably be used before, either.
         | ("GDExtension", "open_library")

godot-core/src/engine/io/resources.rs

@@ -8,11 +8,11 @@
 use crate::builtin::GString;
 use crate::engine::global::Error as GodotError;
 use crate::gen::classes::{Resource, ResourceLoader, ResourceSaver};
-use crate::obj::{Gd, GodotClass, Inherits};
+use crate::obj::{Gd, Inherits};
 
 use super::IoError;
 
-/// Loads a resource from the filesystem located at `path`, panicking on error.
+/// ⚠️ Loads a resource from the filesystem located at `path`, panicking on error.
 ///
 /// See [`try_load`] for more information.
 ///
@@ -29,24 +29,24 @@ use super::IoError;
 #[inline]
 pub fn load<T>(path: impl Into<GString>) -> Gd<T>
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     let path = path.into();
     load_impl(&path).unwrap_or_else(|err| panic!("failed: {err}"))
 }
 
 /// Loads a resource from the filesystem located at `path`.
 ///
-/// The resource is loaded on the method call (unless it's referenced already elsewhere, e.g. in another script or in the scene),
-/// which might cause slight delay, especially when loading scenes.
+/// The resource is loaded during the method call, unless it is already referenced elsewhere, e.g. in another script or in the scene.
+/// This might cause slight delay, especially when loading scenes.
 ///
 /// This function can fail if resource can't be loaded by [`ResourceLoader`] or if the subsequent cast into `T` fails.
 ///
 /// This method is a simplified version of [`ResourceLoader::load()`][crate::engine::ResourceLoader::load],
 /// which can be used for more advanced scenarios.
 ///
-/// # Note:
-/// Resource paths can be obtained by right-clicking on a resource in the Godot editor (_FileSystem_ dock) and choosing "Copy Path",
+/// # Note
+/// Resource paths can be obtained by right-clicking on a resource in the Godot editor (_FileSystem_ dock) and choosing _Copy Path_,
 /// or by dragging the file from the _FileSystem_ dock into the script.
 ///
 /// The path must be absolute (typically starting with `res://`), a local path will fail.
@@ -67,12 +67,12 @@ where
 #[inline]
 pub fn try_load<T>(path: impl Into<GString>) -> Result<Gd<T>, IoError>
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     load_impl(&path.into())
 }
 
-/// Saves a [`Resource`]-inheriting [`GodotClass`] `obj` into file located at `path`.
+/// ⚠️ Saves a [`Resource`]-inheriting object into the file located at `path`.
 ///
 /// See [`try_save`] for more information.
 ///
@@ -84,20 +84,20 @@ where
 /// use godot::prelude::*;
 /// use godot::engine::save;
 ///
-/// save(Resource::new_gd(), "res://base_resource.tres")
+/// save(Resource::new_gd(), "res://BaseResource.tres")
 /// ```
 /// use godot::
 #[inline]
 pub fn save<T>(obj: Gd<T>, path: impl Into<GString>)
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     let path = path.into();
     save_impl(obj, &path)
         .unwrap_or_else(|err| panic!("failed to save resource at path '{}': {}", &path, err));
 }
 
-/// Saves a [Resource]-inheriting [GodotClass] `obj` into file located at `path`.
+/// Saves a [`Resource`]-inheriting object into the file located at `path`.
 ///
 /// This function can fail if [`ResourceSaver`] can't save the resource to file, as it is a simplified version of
 /// [`ResourceSaver::save()`][crate::engine::ResourceSaver::save]. The underlying method can be used for more advances scenarios.
@@ -127,7 +127,7 @@ where
 #[inline]
 pub fn try_save<T>(obj: Gd<T>, path: impl Into<GString>) -> Result<(), IoError>
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     save_impl(obj, &path.into())
 }
@@ -139,7 +139,7 @@ where
 // Note that more optimizations than that likely make no sense, as loading is quite expensive
 fn load_impl<T>(path: &GString) -> Result<Gd<T>, IoError>
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     // TODO unclone GString
     match ResourceLoader::singleton()
@@ -163,7 +163,7 @@ where
 
 fn save_impl<T>(obj: Gd<T>, path: &GString) -> Result<(), IoError>
 where
-    T: GodotClass + Inherits<Resource>,
+    T: Inherits<Resource>,
 {
     // TODO unclone GString
     let res = ResourceSaver::singleton()

godot-core/src/engine/manual_extensions.rs

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) godot-rust; Bromeon and contributors.
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+use crate::builtin::NodePath;
+use crate::engine::{Node, PackedScene};
+use crate::obj::{Gd, Inherits};
+
+/// Manual extensions for the `Node` class.
+impl Node {
+    /// ⚠️ Retrieves the node at path `path`, panicking if not found or bad type.
+    ///
+    /// # Panics
+    /// If the node is not found, or if it does not have type `T` or inherited.
+    pub fn get_node_as<T>(&self, path: impl Into<NodePath>) -> Gd<T>
+    where
+        T: Inherits<Node>,
+    {
+        let path = path.into();
+        let copy = path.clone(); // TODO avoid copy
+
+        self.try_get_node_as(path).unwrap_or_else(|| {
+            panic!(
+                "There is no node of type {ty} at path `{copy}`",
+                ty = T::class_name()
+            )
+        })
+    }
+
+    /// Retrieves the node at path `path` (fallible).
+    ///
+    /// If the node is not found, or if it does not have type `T` or inherited,
+    /// `None` will be returned.
+    pub fn try_get_node_as<T>(&self, path: impl Into<NodePath>) -> Option<Gd<T>>
+    where
+        T: Inherits<Node>,
+    {
+        let path = path.into();
+
+        // TODO differentiate errors (not found, bad type) with Result
+        self.get_node_or_null(path)
+            .and_then(|node| node.try_cast::<T>().ok())
+    }
+}
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Manual extensions for the `PackedScene` class.
+impl PackedScene {
+    /// ⚠️ Instantiates the scene as type `T`, panicking if not found or bad type.
+    ///
+    /// # Panics
+    /// If the scene is not type `T` or inherited.
+    pub fn instantiate_as<T>(&self) -> Gd<T>
+    where
+        T: Inherits<Node>,
+    {
+        self.try_instantiate_as::<T>()
+            .unwrap_or_else(|| panic!("Failed to instantiate {to}", to = T::class_name()))
+    }
+
+    /// Instantiates the scene as type `T` (fallible).
+    ///
+    /// If the scene is not type `T` or inherited.
+    pub fn try_instantiate_as<T>(&self) -> Option<Gd<T>>
+    where
+        T: Inherits<Node>,
+    {
+        self.instantiate().and_then(|gd| gd.try_cast::<T>().ok())
+    }
+}