Merge #941 #942

941: Simplify module setup around gdnative::globalscope + docs r=Bromeon a=Bromeon

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

942: Compatibility warning between godot-rust and Godot r=Bromeon a=Bromeon

Adds a warning on startup, if godot-rust is used with a Godot engine version that ships a partially incompatible GDNative API version.

Currently only a warning and not a hard error; we need to see how it goes.

Co-authored-by: Jan Haller <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [0.10.2] - unreleased
+
+Last maintenance release for Godot 3.4.
+
+# Added
+
+- `globalscope::load` method ([#940](https://github.com/godot-rust/godot-rust/pull/940), [#941](https://github.com/godot-rust/godot-rust/pull/941))
+- `Color` constructors from HTML string and integers ([#939](https://github.com/godot-rust/godot-rust/pull/939))
+- Version check to warn if Godot is not 3.4 ([#942](https://github.com/godot-rust/godot-rust/pull/942))
+
 ## [0.10.1] - 2022-09-03
 
 This is a backwards-compatible release; thus no removals or breaking changes.

examples/native-plugin/src/lib.rs

@@ -1,7 +1,7 @@
 // Rust GDNative implementation of this Godot tutorial:
 // https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html#a-custom-node
 
-use gdnative::api::{EditorPlugin, Resource, Script, Texture};
+use gdnative::api::{EditorPlugin, Script, Texture};
 use gdnative::prelude::*;
 
 #[derive(NativeClass)]
@@ -18,10 +18,8 @@ impl CustomNode {
     fn _enter_tree(&self, #[base] owner: TRef<EditorPlugin>) {
         // Initialization of the plugin goes here.
         // Add the new type with a name, a parent type, a script and an icon.
-        let script = unsafe { load::<Script>("res://my_button.gdns", "Script").unwrap() };
-        let texture = unsafe {
-            load::<Texture>("res://making_plugins-custom_node_icon.png", "Texture").unwrap()
-        };
+        let script = load::<Script>("res://my_button.gdns").unwrap();
+        let texture = load::<Texture>("res://making_plugins-custom_node_icon.png").unwrap();
         owner.add_custom_type("MyButton", "Button", script, texture);
     }
 
@@ -56,15 +54,6 @@ impl MyButton {
     }
 }
 
-unsafe fn load<T>(path: &str, hint: &str) -> Option<Ref<T, Shared>>
-where
-    T: GodotObject<Memory = RefCounted> + SubClass<Resource>,
-{
-    let resource = ResourceLoader::godot_singleton().load(path, hint, false)?;
-    let resource = resource.assume_safe().claim();
-    resource.cast::<T>()
-}
-
 fn init(handle: InitHandle) {
     handle.add_tool_class::<CustomNode>();
     handle.add_tool_class::<MyButton>();

examples/scene-create/src/lib.rs

@@ -105,11 +105,9 @@ fn init(handle: InitHandle) {
 }
 
 pub fn load_scene(path: &str) -> Option<Ref<PackedScene, ThreadLocal>> {
-    let scene = ResourceLoader::godot_singleton().load(path, "PackedScene", false)?;
-
+    let scene = load::<PackedScene>(path)?;
     let scene = unsafe { scene.assume_thread_local() };
-
-    scene.cast::<PackedScene>()
+    Some(scene)
 }
 
 /// Root here is needs to be the same type (or a parent type) of the node that you put in the child

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/core_types/color.rs

@@ -3,7 +3,8 @@ use crate::sys;
 use std::mem::transmute;
 
 use crate::core_types::GodotString;
-/// RGBA color with 32 bits floating point components.
+
+/// RGBA color with 32-bit floating point components.
 #[repr(C)]
 #[derive(Copy, Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -43,20 +44,22 @@ impl Color {
 
     /// Parses from a HTML color code, or `None` on parse error.
     ///
+    /// Note that unlike most other constructors, this has `ARGB` and not `RGBA` format.
+    /// In particular, `from_html("AB123456")` would correspond to `from_rgba_u32(0x123456AB)`.
+    ///
     /// ```
     /// use gdnative::prelude::Color;
     ///
-    /// // Each of the following creates the same color RGBA(178, 217, 10, 255).
     /// let c1 = Color::from_html("#9eb2d90a"); // ARGB format with "#".
     /// let c2 = Color::from_html("9eb2d90a");  // ARGB format.
     /// let c3 = Color::from_html("#b2d90a");   // RGB format with "#".
     /// let c4 = Color::from_html("b2d90a");    // RGB format.
     ///
-    /// let expected = Color::from_rgba_u8(178, 217, 10, 158);
+    /// let expected = Color::from_rgba_u8(0xb2, 0xd9, 0x0a, 0x9e);
     /// assert_eq!(c1, Some(expected));
     /// assert_eq!(c2, Some(expected));
     ///
-    /// let expected = Color::from_rgba_u8(178, 217, 10, 255);
+    /// let expected = Color::from_rgba_u8(0xb2, 0xd9, 0x0a, 0xff);
     /// assert_eq!(c3, Some(expected));
     /// assert_eq!(c4, Some(expected));
     /// ```
@@ -112,7 +115,8 @@ impl Color {
 
     /// Constructs a color from four integer channels, each in range 0-255.
     ///
-    /// This corresponds to the [GDScript method `Color8`](https://docs.godotengine.org/en/stable/classes/class_%40gdscript.html#class-gdscript-method-color8)
+    /// This corresponds to the
+    /// [GDScript method `Color8`](https://docs.godotengine.org/en/stable/classes/class_%40gdscript.html#class-gdscript-method-color8).
     #[inline]
     pub fn from_rgba_u8(r: u8, g: u8, b: u8, a: u8) -> Self {
         Self::from_rgba(

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-core/src/init/macros.rs

@@ -35,6 +35,24 @@ macro_rules! godot_nativescript_init {
                 return;
             }
 
+            // Compatibility warning if using in-house Godot version (not applicable for custom ones)
+            #[cfg(not(feature = "custom-godot"))]
+            {
+                let engine = gdnative::api::Engine::godot_singleton();
+                let info = engine.get_version_info();
+
+                if info.get("major").expect("major version") != Variant::new(3)
+                || info.get("minor").expect("minor version") != Variant::new(4) {
+                    let string = info.get("string").expect("version str").to::<String>().expect("version str type");
+                    gdnative::log::godot_warn!(
+                        "This godot-rust version is only compatible with Godot 3.4.x; detected version {}.\n\
+                        GDNative mismatches may lead to subtle bugs, undefined behavior or crashes at runtime.\n\
+                	    Apply the 'custom-godot' feature if you want to use current godot-rust with another Godot engine version.",
+                        string
+                    );
+                }
+            }
+
             let __result = ::std::panic::catch_unwind(|| {
                 $callback($crate::init::InitHandle::new(handle));
             });

gdnative/src/gdscript.rs

@@ -0,0 +1,63 @@
+//! 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>,
+{
+    let type_hint = T::class_name();
+    ResourceLoader::godot_singleton()
+        .load(path, type_hint, 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