Simplify module setup around gdnative::globalscope + docs

Changes:
* Add load() to prelude
* Rename internal module gdscript -> globalscope
* Module documentation for globalscope now visible again (moved from gdnative_core::globalscope)
* Smaller doc tweaks

Author: Bromeon

gdnative-bindings/src/utils.rs

@@ -7,7 +7,9 @@ use gdnative_core::object::{SubClass, TInstance, TRef};
 use super::generated::{Engine, Node, SceneTree};
 
 /// Convenience method  to obtain a reference to an "auto-load" node, that is a child of the root
-/// node. Returns `None` if the node does not exist or is not of the correct type.
+/// node.
+///
+/// Returns `None` if the node does not exist or is not of the correct type.
 ///
 /// # Safety
 ///

gdnative-core/src/globalscope.rs

@@ -1,24 +1,3 @@
-//! Port of selected GDScript built-in functions.
-//!
-//! This module contains _some_ of the functions available in the [@GDScript] documentation.
-//!
-//! Reasons why a GDScript function may _not_ be ported to Rust include:
-//! * they are in the Rust standard library (`abs`, `sin`, `floor`, `assert`, ...)
-//! * they are already part of a godot-rust API
-//!   * `print` -> [`godot_print!`][crate::log::godot_print!]
-//!   * `instance_from_id` -> [`GodotObject::from_instance_id()`][crate::object::GodotObject::from_instance_id]
-//!   * ...
-//! * they have a private implementation, i.e. a Rust port would have different semantics
-//!   * `randi`, `randf` etc. -- users should use `rand` crate
-//!   * `str2var`, `bytes2var`, `hash` etc -- to be verified
-//!
-//! This above list is not a definitive inclusion/exclusion criterion, just a rough guideline.
-//!
-//! Other noteworthy special cases:
-//! * GDScript `fmod` corresponds to Rust's `%` operator on `f32` (also known as the `Rem` trait).
-//!
-//! [@GDScript]: https://docs.godotengine.org/en/stable/classes/[email protected]
-
 use std::f32::consts::TAU;
 use std::ops::Rem;
 use std::ops::{Range, RangeInclusive};

gdnative/src/gdscript.rs

@@ -0,0 +1,62 @@
+//! Port of selected GDScript built-in functions.
+//!
+//! This module contains _some_ of the functions available in the [@GDScript] documentation.
+//!
+//! Reasons why a GDScript function may _not_ be ported to Rust include:
+//! * they are in the Rust standard library (`abs`, `sin`, `floor`, `assert`, ...)
+//! * they are already part of a godot-rust API
+//!   * `print` -> [`godot_print!`][crate::log::godot_print!]
+//!   * `instance_from_id` -> [`GodotObject::from_instance_id()`][crate::object::GodotObject::from_instance_id]
+//!   * ...
+//! * they have a private implementation, i.e. a Rust port would have different semantics
+//!   * `randi`, `randf` etc. -- users should use `rand` crate
+//!   * `str2var`, `bytes2var`, `hash` etc -- to be verified
+//!
+//! This above list is not a definitive inclusion/exclusion criterion, just a rough guideline.
+//!
+//! Other noteworthy special cases:
+//! * GDScript `fmod` corresponds to Rust's `%` operator on `f32` (also known as the `Rem` trait).
+//!
+//! [@GDScript]: https://docs.godotengine.org/en/stable/classes/[email protected]
+
+use crate::api::{Resource, ResourceLoader};
+use crate::object::{memory::RefCounted, GodotObject, Ref, SubClass};
+
+#[doc(inline)]
+pub use gdnative_core::globalscope::*;
+
+/// 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.
+///
+/// If the resource cannot be loaded, or is not of type `T` or inherited, this method returns `None`.
+///
+/// This method is a simplified version of [`ResourceLoader::load()`][crate::api::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",
+/// 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.
+///
+/// # Example:
+/// Loads a scene called `Main` located in the `path/to` subdirectory of the Godot project and caches it in a variable.
+/// The resource is directly stored with type `PackedScene`.
+///
+/// ```no_run
+/// use gdnative::prelude::*;
+///
+/// let scene = load::<PackedScene>("res://path/to/Main.tscn").unwrap();
+/// ```
+// TODO generalize parameter to `impl Into<NodePath>` once MSRV >= 1.63
+#[inline]
+pub fn load<T>(path: &str) -> Option<Ref<T>>
+where
+    T: SubClass<Resource> + GodotObject<Memory = RefCounted>,
+{
+    ResourceLoader::godot_singleton()
+        .load(path, "", false)
+        .and_then(|res| res.cast::<T>())
+}

gdnative/src/globalscope.rs

@@ -83,12 +83,7 @@
 #[doc(inline)]
 pub use gdnative_core::{core_types, export, init, log, object, profiler};
 
-mod gdscript; // new methods from `@GDscript`, so far only `load`
-pub mod globalscope {
-    pub use crate::gdscript::*;
-    #[doc(inline)]
-    pub use gdnative_core::globalscope::*;
-}
+pub mod globalscope;
 
 // Implementation details (e.g. used by macros).
 // However, do not re-export macros (on crate level), thus no wildcard

gdnative/src/lib.rs

@@ -34,6 +34,8 @@ pub mod user_data {
         Aether, ArcData, LocalCellData, MutexData, RwLockData,
     };
 }
+#[doc(inline)]
+pub use crate::globalscope::load;
 
 // Deprecated symbols. Keep them only in prelude, as all the other paths have changed anyway.
 // This way, old symbol names are still discoverable and users who used prelude won't have (as many) breaking changes.