Add OnReady::from_loaded() + #[init(load = …)]

Bromeon · Bromeon · commit 7096bac632fd · 2025-03-16T21:35:55.000+01:00
diff --git a/godot-core/src/obj/on_ready.rs b/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;
@@ -21,10 +21,10 @@ use std::mem;
 ///
 /// `OnReady<T>` should always be used as a field. There are two modes to use it:
 ///
-/// 1. **Automatic mode, using [`new()`](OnReady::new), [`from_base_fn()`](OnReady::from_base_fn) or
-///    [`node()`](OnReady::<Gd<T>>::from_node).**<br>
+/// 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.
@@ -111,16 +111,18 @@ 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`.
     ///
-    /// # 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).
+    /// (i.e. it receives the `READY` notification).
     pub fn from_node(path: impl AsArg<NodePath>) -> Self {
         arg_into_owned!(path);
 
@@ -133,6 +135,25 @@ impl<T: GodotClass + Inherits<Node>> OnReady<Gd<T>> {
     }
 }
 
+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(...)`.
+    ///
+    /// 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> {
     /// Schedule automatic initialization before `ready()`.
     ///
@@ -175,7 +196,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 { .. } => {
diff --git a/godot-macros/src/class/data_models/field.rs b/godot-macros/src/class/data_models/field.rs
@@ -6,6 +6,7 @@
  */
 
 use crate::class::{FieldExport, FieldVar};
+use crate::util::error;
 use proc_macro2::{Ident, Span, TokenStream};
 use quote::ToTokens;
 
@@ -37,6 +38,48 @@ impl Field {
             span: field.span(),
         }
     }
+
+    #[must_use]
+    pub fn ensure_preconditions(
+        &self,
+        cond: Option<FieldCond>,
+        span: Span,
+        errors: &mut Vec<venial::Error>,
+    ) -> bool {
+        let prev_size = errors.len();
+
+        if self.default_val.is_some() {
+            errors.push(error!(
+                span,
+                "#[init] can have at most one key among `val|node|load`"
+            ));
+        }
+
+        match cond {
+            Some(FieldCond::IsOnReady) if !self.is_onready => {
+                errors.push(error!(
+                    span,
+                    "used #[init(…)] pattern requires field type `OnReady<T>`"
+                ));
+            }
+
+            Some(FieldCond::IsOnEditor) if !self.is_oneditor => {
+                errors.push(error!(
+                    span,
+                    "used #[init(…)] pattern requires field type `OnEditor<T>`"
+                ));
+            }
+
+            _ => {}
+        }
+
+        errors.len() == prev_size
+    }
+}
+
+pub enum FieldCond {
+    IsOnReady,
+    IsOnEditor,
 }
 
 pub struct Fields {
diff --git a/godot-macros/src/class/derive_godot_class.rs b/godot-macros/src/class/derive_godot_class.rs
@@ -9,8 +9,8 @@ use proc_macro2::{Ident, Punct, TokenStream};
 use quote::{format_ident, quote, quote_spanned};
 
 use crate::class::{
-    make_property_impl, make_virtual_callback, BeforeKind, Field, FieldDefault, FieldExport,
-    FieldVar, Fields, SignatureInfo,
+    make_property_impl, make_virtual_callback, BeforeKind, Field, FieldCond, FieldDefault,
+    FieldExport, FieldVar, Fields, SignatureInfo,
 };
 use crate::util::{
     bail, error, format_funcs_collection_struct, ident, path_ends_with_complex,
@@ -530,7 +530,7 @@ fn parse_fields(
                 );
             }
 
-            // #[init(val = expr)]
+            // #[init(val = EXPR)]
             if let Some(default) = parser.handle_expr("val")? {
                 field.default_val = Some(FieldDefault {
                     default_val: default,
@@ -555,30 +555,13 @@ fn parse_fields(
                 })
             }
 
-            // #[init(node = "NodePath")]
+            // #[init(node = "PATH")]
             if let Some(node_path) = parser.handle_expr("node")? {
-                let mut is_well_formed = true;
-                if !field.is_onready {
-                    is_well_formed = false;
-                    errors.push(error!(
-                        parser.span(),
-                        "The key `node` in attribute #[init] requires field of type `OnReady<T>`\n\
-				         Hint: the syntax #[init(node = \"NodePath\")] is equivalent to \
-				         #[init(val = OnReady::from_node(\"NodePath\"))], \
-				         which can only be assigned to fields of type `OnReady<T>`"
-                    ));
-                }
-
-                if field.default_val.is_some() {
-                    is_well_formed = false;
-                    errors.push(error!(
-				        parser.span(),
-				        "The key `node` in attribute #[init] is mutually exclusive with the keys `default` and `val`\n\
-				         Hint: the syntax #[init(node = \"NodePath\")] is equivalent to \
-				         #[init(val = OnReady::from_node(\"NodePath\"))], \
-				         both aren't allowed since they would override each other"
-			        ));
-                }
+                let is_well_formed = field.ensure_preconditions(
+                    Some(FieldCond::IsOnReady),
+                    parser.span(),
+                    &mut errors,
+                );
 
                 let default_val = if is_well_formed {
                     quote! { OnReady::from_node(#node_path) }
@@ -592,27 +575,36 @@ fn parse_fields(
                 });
             }
 
-            // #[init(sentinel = val)]
-            if let Some(sentinel_representation) = parser.handle_expr("sentinel")? {
-                let mut is_well_formed = true;
-                if !field.is_oneditor {
-                    is_well_formed = false;
-                    errors.push(error!(
-                        parser.span(),
-                        "The key `sentinel` in attribute #[init] requires field of type `OnEditor<T>`"
-                    ));
-                }
+            // #[init(load = "PATH")]
+            if let Some(resource_path) = parser.handle_expr("load")? {
+                let is_well_formed = field.ensure_preconditions(
+                    Some(FieldCond::IsOnReady),
+                    parser.span(),
+                    &mut errors,
+                );
 
-                if field.default_val.is_some() {
-                    is_well_formed = false;
-                    errors.push(error!(
-				        parser.span(),
-				        "The key `sentinel` in attribute #[init] is mutually exclusive with the key `val`"
-			        ));
-                }
+                let default_val = if is_well_formed {
+                    quote! { OnReady::from_loaded(#resource_path) }
+                } else {
+                    quote! { todo!() }
+                };
+
+                field.default_val = Some(FieldDefault {
+                    default_val,
+                    span: parser.span(),
+                });
+            }
+
+            // #[init(sentinel = EXPR)]
+            if let Some(sentinel_value) = parser.handle_expr("sentinel")? {
+                let is_well_formed = field.ensure_preconditions(
+                    Some(FieldCond::IsOnEditor),
+                    parser.span(),
+                    &mut errors,
+                );
 
                 let default_val = if is_well_formed {
-                    quote! { OnEditor::from_sentinel( #sentinel_representation ) }
+                    quote! { OnEditor::from_sentinel(#sentinel_value) }
                 } else {
                     quote! { todo!() }
                 };
@@ -649,6 +641,9 @@ fn parse_fields(
             if let Some(override_onready) = handle_opposite_keys(&mut parser, "onready", "hint")? {
                 field.is_onready = override_onready;
             }
+
+            // Not yet implemented for OnEditor.
+
             parser.finish()?;
         }
 
diff --git a/itest/rust/src/engine_tests/save_load_test.rs b/itest/rust/src/engine_tests/save_load_test.rs
@@ -5,7 +5,9 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
-use godot::obj::NewGd;
+use godot::classes;
+use godot::classes::notify::NodeNotification;
+use godot::obj::{Base, Gd, NewAlloc, NewGd, OnReady};
 use godot::register::GodotClass;
 use godot::tools::{load, save, try_load, try_save};
 
@@ -25,6 +27,17 @@ struct SavedGame {
     level: u32,
 }
 
+// Needed to test OnReady integration of load.
+#[derive(GodotClass)]
+#[class(base=Node, init)]
+struct GameLoader {
+    // Test also more complex expressions.
+    #[init(load = &format!("res://{}", RESOURCE_NAME))]
+    game: OnReady<Gd<SavedGame>>,
+
+    _base: Base<classes::Node>,
+}
+
 const RESOURCE_NAME: &str = "test_resource.tres";
 const FAULTY_PATH: &str = "no_such_path";
 
@@ -69,3 +82,20 @@ fn load_test() {
 
     remove_test_file(RESOURCE_NAME);
 }
+
+#[itest]
+fn load_with_onready() {
+    let res_path = format!("res://{}", RESOURCE_NAME);
+
+    let mut resource = SavedGame::new_gd();
+    resource.bind_mut().set_level(555);
+
+    save(&resource, &res_path);
+
+    let mut loader = GameLoader::new_alloc();
+    loader.notify(NodeNotification::READY);
+    assert_eq!(loader.bind().game.bind().get_level(), 555);
+    loader.free();
+
+    remove_test_file(RESOURCE_NAME);
+}
diff --git a/itest/rust/src/object_tests/onready_test.rs b/itest/rust/src/object_tests/onready_test.rs
@@ -5,6 +5,8 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/.
  */
 
+// Integration of OnReady with #[init(load = "PATH")] is tested in save_load_test.rs.
+
 use crate::framework::{expect_panic, itest};
 use godot::classes::notify::NodeNotification;
 use godot::classes::{INode, Node};
