Merge pull request #759 from lilizoey/fix/upcast-ref-wrong

Add an engine class bound to `upcast_ref`/`upcast_mut`

Author: Bromeon

godot-core/src/obj/gd.rs

@@ -295,12 +295,29 @@ impl<T: GodotClass> Gd<T> {
     ///     println!("Node name: {}", node.upcast_ref().get_name());
     /// }
     /// ```
+    ///
+    /// Note that this cannot be used to get a reference to Rust classes, for that you should use [`Gd::bind()`]. For instance this
+    /// will fail:
+    /// ```compile_fail
+    /// # use godot::prelude::*;
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct SomeClass {}
+    ///
+    /// #[godot_api]
+    /// impl INode for SomeClass {
+    ///     fn ready(&mut self) {
+    ///         let other = SomeClass::new_alloc();
+    ///         let _ = other.upcast_ref::<SomeClass>();
+    ///     }
+    /// }
+    /// ```
     pub fn upcast_ref<Base>(&self) -> &Base
     where
-        Base: GodotClass,
+        Base: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
         T: Inherits<Base>,
     {
-        // SAFETY: valid upcast enforced by Inherits bound.
+        // SAFETY: `Base` is guaranteed to be an engine base class of `T` because of the generic bounds.
         unsafe { self.raw.as_upcast_ref::<Base>() }
     }
 
@@ -317,12 +334,29 @@ impl<T: GodotClass> Gd<T> {
     ///     node.upcast_mut().set_name(name.into());
     /// }
     /// ```
+    ///
+    /// Note that this cannot be used to get a mutable reference to Rust classes, for that you should use [`Gd::bind_mut()`]. For instance this
+    /// will fail:
+    /// ```compile_fail
+    /// # use godot::prelude::*;
+    /// #[derive(GodotClass)]
+    /// #[class(init, base = Node)]
+    /// struct SomeClass {}
+    ///
+    /// #[godot_api]
+    /// impl INode for SomeClass {
+    ///     fn ready(&mut self) {
+    ///         let mut other = SomeClass::new_alloc();
+    ///         let _ = other.upcast_mut::<SomeClass>();
+    ///     }
+    /// }
+    /// ```
     pub fn upcast_mut<Base>(&mut self) -> &mut Base
     where
-        Base: GodotClass,
+        Base: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
         T: Inherits<Base>,
     {
-        // SAFETY: valid upcast enforced by Inherits bound.
+        // SAFETY: `Base` is guaranteed to be an engine base class of `T` because of the generic bounds.
         unsafe { self.raw.as_upcast_mut::<Base>() }
     }
 

godot-core/src/obj/raw.rs

@@ -218,7 +218,8 @@ impl<T: GodotClass> RawGd<T> {
     /// If this `RawGd` is null. In Debug mode, sanity checks (valid upcast, ID comparisons) can also lead to panics.
     ///
     /// # Safety
-    /// It's the caller's responsibility to ensure `Base` is actually a base class of `T`.
+    /// - `Base` must actually be a base class of `T`.
+    /// - `Base` must be an engine class.
     ///
     /// This is not done via bounds because that would infect all APIs with `Inherits<T>` and leads to cycles in `Deref`.
     /// Bounds should be added on user-facing safe APIs.
@@ -254,7 +255,8 @@ impl<T: GodotClass> RawGd<T> {
     /// If this `RawGd` is null. In Debug mode, sanity checks (valid upcast, ID comparisons) can also lead to panics.
     ///
     /// # Safety
-    /// It's the caller's responsibility to ensure `Base` is actually a base class of `T`.
+    /// - `Base` must actually be a base class of `T`.
+    /// - `Base` must be an engine class.
     ///
     /// This is not done via bounds because that would infect all APIs with `Inherits<T>` and leads to cycles in `Deref`.
     /// Bounds should be added on user-facing safe APIs.