Merge pull request #1083 from godot-rust/qol/onready-ctors

Add `OnReady::from_loaded()` + `#[init(load = "PATH")]`

Author: Bromeon

godot-core/src/obj/mod.rs

@@ -16,8 +16,8 @@ mod dyn_gd;
 mod gd;
 mod guards;
 mod instance_id;
-mod oneditor;
-mod onready;
+mod on_editor;
+mod on_ready;
 mod raw_gd;
 mod traits;
 
@@ -28,8 +28,8 @@ pub use dyn_gd::DynGd;
 pub use gd::*;
 pub use guards::{BaseMut, BaseRef, DynGdMut, DynGdRef, GdMut, GdRef};
 pub use instance_id::*;
-pub use oneditor::*;
-pub use onready::*;
+pub use on_editor::*;
+pub use on_ready::*;
 pub use raw_gd::*;
 pub use traits::*;
 

godot-core/src/obj/oneditor.rs godot-core/src/obj/on_editor.rs

@@ -10,63 +10,81 @@ use crate::registry::property::{BuiltinExport, Export, Var};
 
 /// Exported property that must be initialized in the editor (or associated code) before use.
 ///
-/// Allows to use `Gd<T>`, which by itself never holds null objects, as an `#[export]` that should not be null during runtime.
-/// As such, it can be used as a more ergonomic version of `Option<Gd<T>>` which _assumes_ initialization.
+/// Use this type whenever your Rust code cannot provide a value for a field, but expects one to be specified in the Godot editor.
+///
+/// If you need automatic initialization during `ready()`, e.g. for loading nodes or resources, use [`OnReady<Gd<T>>`](crate::obj::OnReady)
+/// instead. As a general "maybe initialized" type, `Option<Gd<T>>` is always available, even if more verbose.
+///
+///
+/// # What consitutes "initialized"?
+///
+/// Whether a value is considered initialized or not depends on `T`.
+///
+/// - For objects, a value is initialized if it is not null. Exported object propreties in Godot are nullable, but `Gd<T>` and `DynGd<T, D>` do
+///   not support nullability and can thus not directly be exported with `#[export]`. `OnEditor` can bridge this gap, by expecting users
+///   to set a non-null value, and panicking if they don't.
+/// - For built-in types, a value is initialized if it is different from a user-selected sentinel value (e.g. `-1`).
+///
+/// More on this below (see also table-of-contents sidebar).
+///
+/// # Initialization semantics
+///
+/// Panics during access (`Deref/DerefMut` impls) if uninitialized.
 ///
-/// Panics during access if uninitialized.
 /// When used inside a node class, `OnEditor` checks if a value has been set before `ready()` is run, and panics otherwise.
 /// This validation is performed for all `OnEditor` fields declared in a given `GodotClass`, regardless of whether they are `#[var]`, `#[export]`, or neither.
-/// Once initialized, it can be used almost as if it was a `T` value itself, due to `Deref`/`DerefMut` impls.
+/// Once initialized, `OnEditor` can be used almost as if it were a `T` value itself, due to `Deref`/`DerefMut` impls.
 ///
-/// `OnEditor<T>` should always be used as a property, preferably in tandem with an `#[export]` or `#[var]`.
-/// Initializing `OnEditor` values via code before the first use is supported but should be limited to use cases involving builder or factory patterns.
+/// `OnEditor<T>` should always be used as a struct field, preferably in tandem with an `#[export]` or `#[var]`.
+/// Initializing `OnEditor` values via code before the first use is supported, but should be limited to use cases involving builder or factory patterns.
 ///
-/// [`Option<Gd<T>>`](std::option) and [`OnReady<Gd<T>>`](crate::obj::onready::OnReady) should be used for any other late initialization logic.
 ///
-/// # Using `OnEditor<T>` with `Gd<T>` and `DynGd<T, D>`
+/// # Using `OnEditor` with classes
 ///
-/// ## Example - auto-generated init
+/// You can wrap class smart pointers `Gd<T>` and `DynGd<T, D>` inside `OnEditor`, to make them exportable.
+/// `Gd<T>` itself does not implement the `Export` trait.
 ///
-/// ```
-///  use godot::prelude::*;
+/// ## Example: automatic init
 ///
+/// This example uses the `Default` impl, which expects a non-null value to be provided.
+///
+/// ```
+/// # use godot::prelude::*;
 /// #[derive(GodotClass)]
 /// #[class(init, base = Node)]
-/// struct MyClass {
+/// struct ResourceHolder {
 ///     #[export]
 ///     editor_property: OnEditor<Gd<Resource>>,
 /// }
 ///
 /// #[godot_api]
-/// impl INode for MyClass {
+/// impl INode for ResourceHolder {
 ///     fn ready(&mut self) {
 ///         // Will always be valid and **must** be set via editor.
-///         // Additional check is being run before ready()
+///         // Additional check is being run before ready(),
 ///         // to ensure that given value can't be null.
 ///         let some_variant = self.editor_property.get_meta("SomeName");
 ///     }
 /// }
-///
 /// ```
 ///
-/// ## Example - user-generated init
+/// ## Example: user-defined init
 ///
-/// Uninitialized `OnEditor<Gd<T>>` and `OnEditor<DynGd<T, D>>` can be created with `OnEditor<...>::default()`.
+/// Uninitialized `OnEditor<Gd<T>>` and `OnEditor<DynGd<T, D>>` can be created with `OnEditor::default()`.
 ///
 /// ```
-///  use godot::prelude::*;
-///
+/// # use godot::prelude::*;
 /// #[derive(GodotClass)]
 /// #[class(base = Node)]
-/// struct MyClass {
+/// struct NodeHolder {
 ///     #[export]
 ///     required_node: OnEditor<Gd<Node>>,
 ///
 ///     base: Base<Node>
 /// }
 ///
 /// #[godot_api]
-/// impl INode for MyClass {
+/// impl INode for NodeHolder {
 ///     fn init(base: Base<Node>) -> Self {
 ///        Self {
 ///            base,
@@ -76,14 +94,13 @@ use crate::registry::property::{BuiltinExport, Export, Var};
 /// }
 ///```
 ///
-/// ## Example - factory pattern
+/// ## Example: factory pattern
 ///
 /// ```
-/// use godot::prelude::*;
-///
+/// # use godot::prelude::*;
 /// #[derive(GodotClass)]
 /// #[class(init, base = Node)]
-/// struct SomeClass {
+/// struct NodeHolder {
 ///     #[export]
 ///     required_node: OnEditor<Gd<Node>>,
 /// }
@@ -92,67 +109,70 @@ use crate::registry::property::{BuiltinExport, Export, Var};
 ///     mut this: Gd<Node>,
 ///     some_class_scene: Gd<PackedScene>,
 ///     some_node: Gd<Node>,
-/// ) -> Gd<SomeClass> {
-///     let mut my_node = some_class_scene.instantiate_as::<SomeClass>();
+/// ) -> Gd<NodeHolder> {
+///     let mut my_node = some_class_scene.instantiate_as::<NodeHolder>();
 ///
-///     // Would cause the panic:
+///     // Would cause a panic:
 ///     // this.add_child(&my_node);
 ///
-///     // Note: Remember that nodes are manually managed.
-///     // They will leak memory if not added to tree and/or pruned.
+///     // It's possible to initialize the value programmatically, although typically
+///     // it is set in the editor and stored in a .tscn file.
+///     // Note: nodes are manually managed and leak memory unless tree-attached or freed.
 ///     my_node.bind_mut().required_node.init(some_node);
 ///
-///     // Will not cause the panic.
+///     // Will not panic, since the node is initialized now.
 ///     this.add_child(&my_node);
 ///
 ///     my_node
 /// }
 /// ```
 ///
-/// # Using `OnEditor<T>` with other GodotTypes
+/// # Using `OnEditor` with built-in types
 ///
-/// `OnEditor<T>` can be used with other built-ins to provide extra validation logic and making sure that given properties has been set.
-/// Example usage might be checking if entities has been granted properly generated id.
+/// `OnEditor<T>` can be used with any `#[export]`-enabled builtins, to provide domain-specific validation logic.
+/// An example might be to check whether a game entity has been granted a non-zero ID.
 ///
-/// In such cases the value which will be deemed invalid **must** be specified with `#[init(sentinel = val)]`.
-/// Given `val` will be used to represent uninitialized `OnEditor<T>` in the Godot editor.
-/// Accessing uninitialized value will cause the panic.
+/// To detect whether a value has been set in the editor, `OnEditor<T>` uses a _sentinel value_. This is a special marker value for
+/// "uninitialized" and is selected by the user. For example, a sentinel value of `-1` or `0` might be used to represent an uninitialized `i32`.
 ///
-/// ## Example - using `OnEditor` with primitives
+/// There is deliberately no `Default` implementation for `OnEditor` with builtins, as the sentinel is highly domain-specific.
+///
+/// ## Example
 ///
 /// ```
-///  use godot::prelude::*;
+/// use godot::prelude::*;
 ///
 /// #[derive(GodotClass)]
 /// #[class(init, base = Node)]
-/// struct SomeClassThatCanBeInstantiatedInCode {
+/// struct IntHolder {
 ///     // Uninitialized value will be represented by `42` in the editor.
 ///     // Will cause panic if not set via the editor or code before use.
 ///     #[export]
 ///     #[init(sentinel = 42)]
 ///     some_primitive: OnEditor<i64>,
 /// }
 ///
-/// fn create_and_add(mut this: Gd<Node>, val: i64) -> Gd<SomeClassThatCanBeInstantiatedInCode> {
-///     let mut my_node = SomeClassThatCanBeInstantiatedInCode::new_alloc();
+/// fn create_and_add(mut this: Gd<Node>, val: i64) -> Gd<IntHolder> {
+///     let mut my_node = IntHolder::new_alloc();
 ///
-///     // Would cause the panic:
+///     // Would cause a panic:
 ///     // this.add_child(&my_node);
 ///
+///     // It's possible to initialize the value programmatically, although typically
+///     // it is set in the editor and stored in a .tscn file.
 ///     my_node.bind_mut().some_primitive.init(val);
 ///
-///     // Will not cause the panic.
+///     // Will not panic, since the node is initialized now.
 ///     this.add_child(&my_node);
 ///
 ///     my_node
 /// }
 /// ```
 ///
-/// # Using `OnEditor<T>` with `#[class(tool)]`
+/// # Using `OnEditor` with `#[class(tool)]`
 ///
 /// When used with `#[class(tool)]`, the before-ready checks are omitted.
-/// Otherwise, `OnEditor<T>` behaves the same — accessing an uninitialized value
-/// will cause a panic.
+/// Otherwise, `OnEditor<T>` behaves the same — accessing an uninitialized value will cause a panic.
 pub struct OnEditor<T> {
     inner: OnEditorState<T>,
 }

godot-core/src/obj/onready.rs godot-core/src/obj/on_ready.rs

@@ -5,10 +5,10 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use crate::builtin::NodePath;
-use crate::classes::Node;
+use crate::builtin::{GString, NodePath};
+use crate::classes::{Node, Resource};
 use crate::meta::{arg_into_owned, AsArg, GodotConvert};
-use crate::obj::{Gd, GodotClass, Inherits};
+use crate::obj::{Gd, Inherits};
 use crate::registry::property::Var;
 use std::fmt::{self, Debug, Formatter};
 use std::mem;
@@ -19,12 +19,17 @@ use std::mem;
 /// Godot in particular encourages initialization inside `ready()`, e.g. to access the scene tree after a node is inserted into it.
 /// The alternative to using this pattern is [`Option<T>`][option], which needs to be explicitly unwrapped with `unwrap()` or `expect()` each time.
 ///
-/// `OnReady<T>` should always be used as a field. There are two modes to use it:
+/// If you have a value that you expect to be initialized in the Godot editor, use [`OnEditor<T>`][crate::obj::OnEditor] instead.
+/// As a general "maybe initialized" type, `Option<Gd<T>>` is always available, even if more verbose.
 ///
-/// 1. **Automatic mode, using [`new()`](OnReady::new), [`from_base_fn()`](OnReady::from_base_fn) or
-///    [`node()`](OnReady::<Gd<T>>::node).**<br>
+/// # Late-init semantics
+///
+/// `OnReady<T>` should always be used as a struct field. There are two modes to use it:
+///
+/// 1. **Automatic mode, using [`new()`](OnReady::new), [`from_base_fn()`](OnReady::from_base_fn),
+///    [`from_node()`][Self::from_node] or [`from_loaded()`][Self::from_loaded].**<br>
 ///    Before `ready()` is called, all `OnReady` fields constructed with the above methods are automatically initialized,
-///    in the order of declaration. This means that you can safely access them in `ready()`.<br><br>
+///    in the order of declaration. This means that you can safely access them in `ready()`.<br>
 /// 2. **Manual mode, using [`manual()`](Self::manual).**<br>
 ///    These fields are left uninitialized until you call [`init()`][Self::init] on them. This is useful if you need more complex
 ///    initialization scenarios than a closure allows. If you forget initialization, a panic will occur on first access.
@@ -86,8 +91,10 @@ use std::mem;
 /// #[class(init, base = Node)]
 /// struct MyClass {
 ///    base: Base<Node>,
+///
 ///    #[init(node = "ChildPath")]
 ///    auto: OnReady<Gd<Node2D>>,
+///
 ///    #[init(val = OnReady::manual())]
 ///    manual: OnReady<i32>,
 /// }
@@ -109,21 +116,51 @@ pub struct OnReady<T> {
     state: InitState<T>,
 }
 
-impl<T: GodotClass + Inherits<Node>> OnReady<Gd<T>> {
+impl<T: Inherits<Node>> OnReady<Gd<T>> {
     /// Variant of [`OnReady::new()`], fetching the node located at `path` before `ready()`.
     ///
-    /// This is the functional equivalent of the GDScript pattern `@onready var node = $NodePath`.
+    /// This is the functional equivalent of:
+    /// - the GDScript pattern `@onready var node = $NODE_PATH`.
+    /// - the Rust method [`Node::get_node_as()`].
     ///
-    /// # Panics
-    /// - If `path` does not point to a valid node.
+    /// When used with `#[class(init)]`, the field can be annotated with `#[init(node = "NODE_PATH")]` to call this constructor.
+    ///
+    /// # Panics (deferred)
+    /// - If `path` does not point to a valid node, or its type is not a `T` or a subclass.
     ///
     /// Note that the panic will only happen if and when the node enters the SceneTree for the first time
-    ///  (i.e.: it receives the `READY` notification).
-    pub fn node(path: impl AsArg<NodePath>) -> Self {
+    /// (i.e. it receives the `READY` notification).
+    pub fn from_node(path: impl AsArg<NodePath>) -> Self {
         arg_into_owned!(path);
 
         Self::from_base_fn(move |base| base.get_node_as(&path))
     }
+
+    #[deprecated = "Renamed to `from_node`."]
+    pub fn node(path: impl AsArg<NodePath>) -> Self {
+        Self::from_node(path)
+    }
+}
+
+impl<T: Inherits<Resource>> OnReady<Gd<T>> {
+    /// Variant of [`OnReady::new()`], loading the resource stored at `path` before `ready()`.
+    ///
+    /// This is the functional equivalent of:
+    /// - the GDScript pattern `@onready var res = load(...)`.
+    /// - the Rust function [`tools::load()`][crate::tools::load].
+    ///
+    /// When used with `#[class(init)]`, the field can be annotated with `#[init(load = "FILE_PATH")]` to call this constructor.
+    ///
+    /// # Panics (deferred)
+    /// - If the resource does not exist at `path`, cannot be loaded or is not compatible with type `T`.
+    ///
+    /// Note that the panic will only happen if and when the node enters the SceneTree for the first time
+    /// (i.e. it receives the `READY` notification).
+    pub fn from_loaded(path: impl AsArg<GString>) -> Self {
+        arg_into_owned!(path);
+
+        Self::new(move || crate::tools::load(&path))
+    }
 }
 
 impl<T> OnReady<T> {
@@ -168,7 +205,7 @@ impl<T> OnReady<T> {
     ///
     /// # Panics
     /// - If `init()` was called before.
-    /// - If this object was already provided with a closure during construction, in [`Self::new()`].
+    /// - If this object was already provided with a closure during construction, in [`Self::new()`] or any other automatic constructor.
     pub fn init(&mut self, value: T) {
         match &self.state {
             InitState::ManualUninitialized { .. } => {