Add API to fetch autoloads by name

Author: Bromeon

godot-core/src/tools/autoload.rs

@@ -0,0 +1,99 @@
+/*
+ * 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::classes::{Engine, Node, SceneTree};
+use crate::meta::error::ConvertError;
+use crate::obj::{Gd, Inherits, Singleton};
+
+/// Retrieves an autoload by its name.
+///
+/// See [Godot docs] for an explanation of the autoload concept. Godot sometimes uses the term "autoload" interchangeably with "singleton";
+/// we strictly refer to the former to separate from [`Singleton`][crate::obj::Singleton] objects.
+///
+/// [Godot docs]: https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html
+///
+/// # Panics
+/// This is a convenience function that calls [`try_get_named_autoload()`]. Panics if that fails, e.g. not found or wrong type.
+///
+/// # Example
+/// ```no_run
+/// use godot::prelude::*;
+/// use godot::tools::get_named_autoload;
+///
+/// #[derive(GodotClass)]
+/// #[class(init, base=Node)]
+/// struct GlobalStats {
+///     base: Base<Node>,
+/// }
+///
+/// // Assuming "Statistics" is registered as an autoload in `project.godot`,
+/// // this returns the one instance of type Gd<GlobalStats>.
+/// let stats = get_named_autoload::<GlobalStats>("Statistics");
+/// ```
+pub fn get_named_autoload<T>(autoload_name: &str) -> Gd<T>
+where
+    T: Inherits<Node>,
+{
+    try_get_named_autoload::<T>(autoload_name)
+        .unwrap_or_else(|err| panic!("Failed to get autoload `{autoload_name}`: {err}"))
+}
+
+/// Retrieves an autoload by name (fallible).
+///
+/// Autoloads are accessed via the `/root/{name}` path in the scene tree. The name is the one you used to register the autoload in
+/// `project.godot`. By convention, it often corresponds to the class name, but does not have to.
+///
+/// See also [`get_named_autoload()`] for simpler function expecting the class name and non-fallible invocation.
+///
+/// This function returns `Err` if:
+/// - No autoload is registered under `name`.
+/// - The autoload cannot be cast to type `T`.
+/// - There is an error fetching the scene tree.
+///
+/// # Example
+/// ```no_run
+/// use godot::prelude::*;
+/// use godot::tools::try_get_named_autoload;
+///
+/// #[derive(GodotClass)]
+/// #[class(init, base=Node)]
+/// struct GlobalStats {
+///     base: Base<Node>,
+/// }
+///
+/// let result = try_get_named_autoload::<GlobalStats>("Statistics");
+/// match result {
+///     Ok(autoload) => { /* Use the Gd<GlobalStats>. */ }
+///     Err(err) => eprintln!("Failed to get autoload: {err}"),
+/// }
+/// ```
+pub fn try_get_named_autoload<T>(autoload_name: &str) -> Result<Gd<T>, ConvertError>
+where
+    T: Inherits<Node>,
+{
+    let main_loop = Engine::singleton()
+        .get_main_loop()
+        .ok_or_else(|| ConvertError::new("main loop not available"))?;
+
+    let scene_tree = main_loop
+        .try_cast::<SceneTree>()
+        .map_err(|_| ConvertError::new("main loop is not a SceneTree"))?;
+
+    let autoload_path = NodePath::from(&format!("/root/{autoload_name}"));
+
+    let root = scene_tree
+        .get_root()
+        .ok_or_else(|| ConvertError::new("scene tree root not available"))?;
+
+    root.try_get_node_as::<T>(&autoload_path).ok_or_else(|| {
+        let class = T::class_id();
+        ConvertError::new(format!(
+            "autoload `{autoload_name}` not found or has wrong type (expected {class})",
+        ))
+    })
+}

godot-core/src/tools/mod.rs

@@ -10,10 +10,12 @@
 //! Contains functionality that extends existing Godot classes and functions, to make them more versatile
 //! or better integrated with Rust.
 
+mod autoload;
 mod gfile;
 mod save_load;
 mod translate;
 
+pub use autoload::*;
 pub use gfile::*;
 pub use save_load::*;
 pub use translate::*;

itest/godot/SpecialTests.gd

@@ -57,3 +57,14 @@ func test_collision_object_2d_input_event():
 
 	window.queue_free()
 
+func test_autoload():
+	var fetched = Engine.get_main_loop().get_root().get_node_or_null("/root/MyAutoload")
+	assert_that(fetched != null, "MyAutoload should be loaded")
+
+	var by_class: AutoloadClass = fetched
+	assert_eq(by_class.verify_works(), 787, "Autoload typed by class")
+
+	# Autoload in GDScript can be referenced by class name or autoload name, however autoload as a type is only available in Godot 4.3+.
+	# See https://github.com/godot-rust/gdext/pull/1381#issuecomment-3446111511.
+	# var by_name: MyAutoload = fetched
+	# assert_eq(by_name.verify_works(), 787, "Autoload typed by name")

itest/godot/TestRunner.tscn

@@ -1,6 +1,6 @@
 [gd_scene load_steps=2 format=3 uid="uid://dgcj68l8n6wpb"]
 
-[ext_resource type="Script" path="res://TestRunner.gd" id="1_wdbrf"]
+[ext_resource type="Script" uid="uid://dcsm6ho05dipr" path="res://TestRunner.gd" id="1_wdbrf"]
 
 [node name="TestRunner" type="Node"]
 script = ExtResource("1_wdbrf")

itest/godot/gdscript_tests/AutoloadScene.tscn

@@ -0,0 +1,3 @@
+[gd_scene format=3 uid="uid://csf04mj3dj8bn"]
+
+[node name="AutoloadNode" type="AutoloadClass"]

itest/godot/project.godot

@@ -15,6 +15,10 @@ run/main_scene="res://TestRunner.tscn"
 config/features=PackedStringArray("4.2")
 run/flush_stdout_on_print=true
 
+[autoload]
+
+MyAutoload="*res://gdscript_tests/AutoloadScene.tscn"
+
 [debug]
 
 gdscript/warnings/shadowed_variable=0

itest/rust/src/engine_tests/autoload_test.rs

@@ -0,0 +1,67 @@
+/*
+ * 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 godot::classes::Node;
+use godot::prelude::*;
+use godot::tools::{get_named_autoload, try_get_named_autoload};
+
+use crate::framework::itest;
+
+#[derive(GodotClass)]
+#[class(init, base=Node)]
+struct AutoloadClass {
+    base: Base<Node>,
+    #[var]
+    property: i32,
+}
+
+#[godot_api]
+impl AutoloadClass {
+    #[func]
+    fn verify_works(&self) -> i32 {
+        787
+    }
+}
+
+#[itest]
+fn autoload_get() {
+    let mut autoload = get_named_autoload::<AutoloadClass>("MyAutoload");
+    {
+        let mut guard = autoload.bind_mut();
+        assert_eq!(guard.verify_works(), 787);
+        assert_eq!(guard.property, 0, "still has default value");
+
+        guard.property = 42;
+    }
+
+    // Fetch same autoload anew.
+    let autoload2 = get_named_autoload::<AutoloadClass>("MyAutoload");
+    assert_eq!(autoload2.bind().property, 42);
+
+    // Reset for other tests.
+    autoload.bind_mut().property = 0;
+}
+
+#[itest]
+fn autoload_try_get_named() {
+    let autoload = try_get_named_autoload::<AutoloadClass>("MyAutoload").expect("fetch autoload");
+
+    assert_eq!(autoload.bind().verify_works(), 787);
+    assert_eq!(autoload.bind().property, 0, "still has default value");
+}
+
+#[itest]
+fn autoload_try_get_named_inexistent() {
+    let result = try_get_named_autoload::<AutoloadClass>("InexistentAutoload");
+    result.expect_err("non-existent autoload");
+}
+
+#[itest]
+fn autoload_try_get_named_bad_type() {
+    let result = try_get_named_autoload::<Node2D>("MyAutoload");
+    result.expect_err("autoload of incompatible node type");
+}

itest/rust/src/engine_tests/mod.rs

@@ -6,6 +6,7 @@
  */
 
 mod async_test;
+mod autoload_test;
 mod codegen_enums_test;
 mod codegen_test;
 mod engine_enum_test;