Support Result<T, E> as return type in #[func]

Mechanisms:
- FuncError + func_bail! macro for explicit error propagation
- Error strategies (strats) for flexible error handling approaches
- Automatic Result-to-Godot error conversion via error_to_godot trait
- ptrcall disabling for fatal Result errors (uses varcall instead)
- Call error tracking for introspection and debugging

Author: Bromeon

godot-core/src/meta/error/call_error.rs

@@ -326,6 +326,11 @@ impl CallError {
         err
     }
 
+    /// `#[func]` returning `Result<T, E>` which hits the `Err(E)` case *and* intends to fail the Godot call.
+    pub(crate) fn failed_by_user_result(call_ctx: &CallContext, message: String) -> Self {
+        Self::new(call_ctx, message, None)
+    }
+
     /// Whether this error was caused by a Rust panic (as opposed to a Godot or godot-rust error).
     ///
     /// If true, the panic hook has already printed the error; callers can avoid printing it again.

godot-core/src/meta/error/error_to_godot.rs

@@ -0,0 +1,137 @@
+/*
+ * 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/.
+ */
+
+//! The [`ErrorToGodot`] trait for mapping `Result<T, E>` to Godot return types.
+//!
+//! Built-in strategies are in the [`strat`][super::strat] module.
+
+use crate::meta::{GodotConvert, ToGodot};
+
+/// Defines how a Rust error type maps to Godot when used in `Result<T, E>` return types of `#[func]` methods.
+///
+/// The associated type [`Mapped`][Self::Mapped] determines what GDScript sees as the function's return type. This type
+/// can depend on `T` -- the ok-value type of the `Result` -- because the trait is generic over `T`.
+///
+/// # Usage
+/// Users implement the required method [`result_to_godot`][Self::result_to_godot] and set the `Mapped` associated type.
+/// Use a blanket impl over `T` to cover all possible ok-types at once.
+///
+/// ## Failing function call + error message
+/// Use [`strat::Bail`][super::strat::Bail] to make the GDScript function call fail. It lets you use `?` with any `impl Error` type.
+/// The declared type on GDScript side is `T`.
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// use godot::meta::error::func_bail;
+/// # #[derive(GodotClass)] #[class(init, base=Node)] struct MyNode;
+/// #[godot_api]
+/// impl MyNode {
+///     #[func]
+///     fn load_config(&self, path: GString) -> Result<i64, strat::Bail> {
+///         let data = std::fs::read_to_string(path.to_string())?;
+///         let score = data.trim().parse::<i64>()?;
+///
+///         if score < 0 {
+///             func_bail!("invalid score in {path}");
+///         }
+///
+///         Ok(score)
+///     }
+/// }
+/// ```
+///
+/// ## `global::Error`
+/// Use the dedicated Godot enum [`global::Error`][crate::global::Error]. This only allows unit types for the `Ok` path.
+/// ```no_run
+/// # use godot::prelude::*;
+/// # use godot::global;
+/// # #[derive(GodotClass)] #[class(init, base=Node)] struct MyNode;
+/// #[godot_api]
+/// impl MyNode {
+///     #[func]
+///     fn do_fallible_work(&self) -> Result<(), global::Error> {
+///         // ...
+///         Ok(())
+///     }
+/// }
+/// ```
+///
+/// ## Custom implementation: typed `Array<T>` with 0 or 1 elements
+/// Since the trait is generic over `T`, custom implementations can require tighter bounds (such as
+/// [`Element`][crate::meta::Element]) and use a typed `Array<T>` as the via type. This example returns
+/// a 1-element array on success and an empty array on error. GDScript sees `Array[T]` as the return type.
+///
+/// ```no_run
+/// # use godot::prelude::*;
+/// use godot::builtin::Array;
+/// use godot::meta::error::ErrorToGodot;
+/// use godot::meta::{Element, GodotConvert, ref_to_arg, ToGodot};
+///
+/// struct MyError(String);
+///
+/// impl<T: Element> ErrorToGodot<T> for MyError {
+///     // GDScript sees `Array[T]` -- a typed array.
+///     type Mapped = Array<T>;
+///
+///     fn result_to_godot(result: Result<&T, &Self>) -> Result<Array<T>, String> {
+///         match result {
+///             Ok(val) => Ok(array![ref_to_arg(val)]),
+///             Err(_) => Ok(Array::new()),
+///         }
+///     }
+/// }
+/// ```
+///
+/// GDScript usage:
+/// ```gdscript
+/// var result: Array[int] = node.try_something()
+/// if result.is_empty():
+///     print("Operation failed")
+/// else:
+///     var value = result[0]
+/// ```
+///
+/// # Built-in strategies
+///
+/// See the [`strat`] module for all provided implementations and an overview table.
+///
+/// [`strat`]: crate::meta::error::strat
+///
+/// # Fatal errors and calling conventions
+///
+/// Fatal error types (those where [`result_to_godot`][Self::result_to_godot] returns `Err(msg)` on failure) rely on
+/// Godot's varcall mechanism to abort the calling GDScript function. However, Godot internally selects between two
+/// calling conventions based on static type information in the script, and this choice is **not controllable from GDExtension**:
+///
+/// - **Varcall** is used when the caller or arguments are untyped (e.g. `var obj: Variant`).
+///   Varcall provides an `r_error` output parameter, which gdext uses to signal call failure. The GDScript VM then
+///   aborts the calling function — similar to how a panic would behave.
+///
+/// - **Ptrcall** is used when both the object and all argument/return types are statically known
+///   (e.g. `var obj: MyClass`, `var x: int = obj.my_func()`).
+///   Ptrcall has **no** error output parameter, so fatal errors cannot abort the calling function.
+///   Instead, the error is logged as a Godot error and a default value is returned.
+///
+/// In practice, this means that a fatal `Result::Err` will abort the GDScript function in most cases (varcall),
+/// but will degrade to a logged error + default return value when GDScript has full type information (ptrcall).
+/// This is a limitation of Godot's GDExtension API, not something gdext can work around.
+pub trait ErrorToGodot<T: ToGodot>: Sized {
+    /// The type to which `Result<T, Self>` is mapped on Godot side.
+    type Mapped: GodotConvert;
+
+    /// Map a `Result<T, Self>` to a Godot representation or a fatal error message.
+    ///
+    /// Return `Ok(via)` to pass the value back to GDScript (the call succeeds), or `Err(message)` to abort the
+    /// GDScript function call and print an error. The latter is the "fatal" mode.
+    ///
+    // TODO: replace Result<Via, String> with a dedicated ErrorHandling<Via> enum to communicate intent more clearly:
+    //   Return(Via)  — pass this value to GDScript; the call succeeds.
+    //   Abort(String) — abort the GDScript call with this error message.
+    fn result_to_godot(
+        result: Result<&T, &Self>,
+    ) -> Result<<Self::Mapped as GodotConvert>::Via, String>;
+}

godot-core/src/meta/error/io_error.rs

@@ -12,7 +12,12 @@ use crate::classes::FileAccess;
 use crate::global::Error as GodotError;
 use crate::obj::Gd;
 
-/// Error that can occur while using `gdext` IO utilities.
+/// Error that can occur while using godot-rust I/O utilities.
+///
+/// Some APIs using this:
+/// - [`tools::try_load()`][crate::tools::try_load]
+/// - [`tools::try_save()`][crate::tools::try_save]
+/// - [`tools::GFile::try_from_unique()`][crate::tools::GFile::try_from_unique]
 #[derive(Debug)]
 pub struct IoError {
     data: ErrorData,

godot-core/src/meta/error/mod.rs

@@ -10,11 +10,17 @@
 mod call_error;
 mod call_error_type;
 mod convert_error;
+mod error_to_godot;
 mod io_error;
 mod string_error;
 
+pub mod strat;
+
 pub use call_error::*;
 pub use call_error_type::*;
 pub use convert_error::*;
+pub use error_to_godot::*;
 pub use io_error::*;
 pub use string_error::*;
+
+pub use crate::func_bail;