Merge pull request #1254 from godot-rust/qol/upcast-bounds

Add bounds for future-proof `Gd` deref

Author: Bromeon

godot-core/src/obj/gd.rs

@@ -780,7 +780,14 @@ where
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Trait impls
 
-impl<T: GodotClass> Deref for Gd<T> {
+/// Dereferences to the nearest engine class, enabling direct calls to its `&self` methods.
+///
+/// For engine classes, returns `T` itself. For user classes, returns `T::Base` (the direct engine base class).
+/// The bound ensures that the target is always an engine-provided class.
+impl<T: GodotClass> Deref for Gd<T>
+where
+    GdDerefTarget<T>: Bounds<Declarer = bounds::DeclEngine>,
+{
     // Target is always an engine class:
     // * if T is an engine class => T
     // * if T is a user class => T::Base
@@ -791,7 +798,14 @@ impl<T: GodotClass> Deref for Gd<T> {
     }
 }
 
-impl<T: GodotClass> DerefMut for Gd<T> {
+/// Mutably dereferences to the nearest engine class, enabling direct calls to its `&mut self` methods.
+///
+/// For engine classes, returns `T` itself. For user classes, returns `T::Base` (the direct engine base class).
+/// The bound ensures that the target is always an engine-provided class.
+impl<T: GodotClass> DerefMut for Gd<T>
+where
+    GdDerefTarget<T>: Bounds<Declarer = bounds::DeclEngine>,
+{
     fn deref_mut(&mut self) -> &mut Self::Target {
         self.raw.as_target_mut()
     }

godot-core/src/obj/mod.rs

@@ -42,4 +42,9 @@ pub use bounds::private::Bounds;
 
 // Do not re-export rtti here.
 
+/// Resolves the type to which a `Gd<T>` dereferences.
+///
+/// This type alias abstracts over the two `Declarer` options for Godot objects:
+/// - [`bounds::DeclEngine`]: for all engine-provided classes, `DerefTarget<T>` is `T`.
+/// - [`bounds::DeclUser`]: for Rust-defined user classes, `DerefTarget<T>` is `T::Base`.
 type GdDerefTarget<T> = <<T as Bounds>::Declarer as bounds::Declarer>::DerefTarget<T>;

godot-core/src/obj/raw_gd.rs

@@ -261,7 +261,8 @@ impl<T: GodotClass> RawGd<T> {
     /// Bounds should be added on user-facing safe APIs.
     pub(super) unsafe fn as_upcast_ref<Base>(&self) -> &Base
     where
-        Base: GodotClass,
+        // DeclEngine needed for sound transmute; in case we add Rust-defined base classes.
+        Base: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
     {
         self.ensure_valid_upcast::<Base>();
 
@@ -299,7 +300,8 @@ impl<T: GodotClass> RawGd<T> {
     /// Bounds should be added on user-facing safe APIs.
     pub(super) unsafe fn as_upcast_mut<Base>(&mut self) -> &mut Base
     where
-        Base: GodotClass,
+        // DeclEngine needed for sound transmute; in case we add Rust-defined base classes.
+        Base: GodotClass + Bounds<Declarer = bounds::DeclEngine>,
     {
         self.ensure_valid_upcast::<Base>();
 
@@ -315,7 +317,10 @@ impl<T: GodotClass> RawGd<T> {
 
     /// # Panics
     /// If this `RawGd` is null.
-    pub(super) fn as_target(&self) -> &GdDerefTarget<T> {
+    pub(super) fn as_target(&self) -> &GdDerefTarget<T>
+    where
+        GdDerefTarget<T>: Bounds<Declarer = bounds::DeclEngine>,
+    {
         // SAFETY: There are two possible Declarer::DerefTarget types:
         // - T, if T is an engine class
         // - T::Base, if T is a user class
@@ -325,7 +330,10 @@ impl<T: GodotClass> RawGd<T> {
 
     /// # Panics
     /// If this `RawGd` is null.
-    pub(super) fn as_target_mut(&mut self) -> &mut GdDerefTarget<T> {
+    pub(super) fn as_target_mut(&mut self) -> &mut GdDerefTarget<T>
+    where
+        GdDerefTarget<T>: Bounds<Declarer = bounds::DeclEngine>,
+    {
         // SAFETY: See as_target().
         unsafe { self.as_upcast_mut::<GdDerefTarget<T>>() }
     }