Merge pull request #901 from godot-rust/qol/deprecate-instance-utilities

Deprecate instance utilities in `godot::global`

Author: Bromeon

godot-core/src/global/mod.rs

@@ -31,5 +31,30 @@ pub use crate::gen::central::global_enums::*;
 pub use crate::gen::utilities::*;
 
 // This is needed for generated classes to find symbols, even those that have been moved to crate::builtin.
+use crate::builtin::Variant;
 #[allow(unused_imports)] // micromanaging imports for generated code is not fun
 pub(crate) use crate::builtin::{Corner, EulerOrder, Side};
+use crate::obj::Gd;
+
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Deprecations
+
+// Reminder: remove #![allow(deprecated)] in utilities.test along with the below functions.
+
+#[deprecated = "Instance utilities in `godot::global` will be removed. Use methods on `Gd` and `InstanceId` instead.\n\
+    For detailed reasons, see https://github.com/godot-rust/gdext/pull/892."]
+pub fn instance_from_id(instance_id: i64) -> Option<Gd<crate::classes::Object>> {
+    crate::gen::utilities::instance_from_id(instance_id)
+}
+
+#[deprecated = "Instance utilities in `godot::global` will be removed. Use methods on `Gd` and `InstanceId` instead.\n\
+    For detailed reasons, see https://github.com/godot-rust/gdext/pull/892."]
+pub fn is_instance_valid(instance: Variant) -> bool {
+    crate::gen::utilities::is_instance_valid(instance)
+}
+
+#[deprecated = "Instance utilities in `godot::global` will be removed. Use methods on `Gd` and `InstanceId` instead.\n\
+    For detailed reasons, see https://github.com/godot-rust/gdext/pull/892."]
+pub fn is_instance_id_valid(instance_id: i64) -> bool {
+    crate::gen::utilities::is_instance_id_valid(instance_id)
+}

godot-core/src/obj/gd.rs

@@ -209,9 +209,12 @@ impl<T: GodotClass> Gd<T> {
 
     /// ⚠️ Looks up the given instance ID and returns the associated object.
     ///
+    /// Corresponds to Godot's global function `instance_from_id()`.
+    ///
     /// # Panics
     /// If no such instance ID is registered, or if the dynamic type of the object behind that instance ID
     /// is not compatible with `T`.
+    #[doc(alias = "instance_from_id")]
     pub fn from_instance_id(instance_id: InstanceId) -> Self {
         Self::try_from_instance_id(instance_id).unwrap_or_else(|err| {
             panic!(

godot-core/src/obj/instance_id.rs

@@ -58,6 +58,17 @@ impl InstanceId {
         self.to_u64() & (1u64 << 63) != 0
     }
 
+    /// Dynamically checks if the instance behind the ID exists.
+    ///
+    /// Rather slow, involves engine round-trip plus object DB lookup. If you need the object, use
+    /// [`Gd::from_instance_id()`][crate::obj::Gd::from_instance_id] instead.
+    ///
+    /// This corresponds to Godot's global function `is_instance_id_valid()`.
+    #[doc(alias = "is_instance_id_valid")]
+    pub fn lookup_validity(self) -> bool {
+        crate::gen::utilities::is_instance_id_valid(self.to_i64())
+    }
+
     // Private: see rationale above
     pub(crate) fn to_u64(self) -> u64 {
         self.value.get()

godot-core/src/obj/raw_gd.rs

@@ -19,7 +19,7 @@ use crate::obj::bounds::{Declarer, DynMemory as _};
 use crate::obj::rtti::ObjectRtti;
 use crate::obj::{bounds, Bounds, GdDerefTarget, GdMut, GdRef, GodotClass, InstanceId};
 use crate::storage::{InstanceCache, InstanceStorage, Storage};
-use crate::{classes, global, out};
+use crate::{classes, out};
 
 /// Low-level bindings for object pointers in Godot.
 ///
@@ -112,7 +112,7 @@ impl<T: GodotClass> RawGd<T> {
     pub(crate) fn is_instance_valid(&self) -> bool {
         self.cached_rtti
             .as_ref()
-            .map(|rtti| global::is_instance_id_valid(rtti.instance_id().to_i64()))
+            .map(|rtti| rtti.instance_id().lookup_validity())
             .unwrap_or(false)
     }
 

itest/rust/src/engine_tests/utilities_test.rs

@@ -5,6 +5,9 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+// TODO remove once instance_from_id() etc are removed.
+#![allow(deprecated)]
+
 use crate::framework::itest;
 
 use godot::builtin::{GString, Variant};

itest/rust/src/object_tests/object_test.rs

@@ -13,6 +13,7 @@ use godot::classes::{
     file_access, Area2D, Camera3D, Engine, FileAccess, IRefCounted, Node, Node3D, Object,
     RefCounted,
 };
+#[allow(deprecated)]
 use godot::global::instance_from_id;
 use godot::meta::{FromGodot, GodotType, ToGodot};
 use godot::obj::{Base, Gd, Inherits, InstanceId, NewAlloc, NewGd, RawGd};
@@ -171,6 +172,7 @@ fn object_instance_from_id() {
 
     let instance_id = node.instance_id();
 
+    #[allow(deprecated)]
     let gd_from_instance_id = instance_from_id(instance_id.to_i64())
         .expect("instance should be valid")
         .cast::<Node>();
@@ -182,6 +184,7 @@ fn object_instance_from_id() {
 
 #[itest]
 fn object_instance_from_invalid_id() {
+    #[allow(deprecated)]
     let gd_from_instance_id = instance_from_id(0);
 
     assert!(