Merge pull request #1315 from godot-rust/qol/type-safe-replacements

More type-safe engine APIs (mostly int -> enum)

Author: Bromeon

godot-codegen/src/generator/classes.rs

@@ -573,6 +573,8 @@ fn make_class_method_definition(
         return FnDefinition::none();
     };
 
+    // Note: parameter type replacements (int -> enum) are already handled during domain mapping.
+
     let rust_class_name = class.name().rust_ty.to_string();
     let rust_method_name = method.name();
     let godot_method_name = method.godot_name();

godot-codegen/src/generator/default_parameters.rs

@@ -80,7 +80,7 @@ pub fn make_function_definition_with_defaults(
         #[doc = #builder_doc]
         #[must_use]
         #cfg_attributes
-        pub struct #builder_ty<'a> {
+        #vis struct #builder_ty<'a> {
             _phantom: std::marker::PhantomData<&'a ()>,
             #( #builder_field_decls, )*
         }

godot-codegen/src/models/domain.rs

@@ -509,47 +509,93 @@ pub struct FnParam {
 }
 
 impl FnParam {
-    pub fn new_range(method_args: &Option<Vec<JsonMethodArg>>, ctx: &mut Context) -> Vec<FnParam> {
-        option_as_slice(method_args)
-            .iter()
-            .map(|arg| Self::new(arg, ctx))
-            .collect()
+    /// Creates a new parameter builder for constructing function parameters with configurable options.
+    pub fn builder() -> FnParamBuilder {
+        FnParamBuilder::new()
+    }
+}
+
+/// Builder for constructing `FnParam` instances with configurable enum replacements and default value handling.
+pub struct FnParamBuilder {
+    replacements: EnumReplacements,
+    no_defaults: bool,
+}
+
+impl FnParamBuilder {
+    /// Creates a new parameter builder with default settings (no replacements, defaults enabled).
+    pub fn new() -> Self {
+        Self {
+            replacements: &[],
+            no_defaults: false,
+        }
     }
 
-    pub fn new_range_no_defaults(
+    /// Configures the builder to use specific enum replacements.
+    pub fn enum_replacements(mut self, replacements: EnumReplacements) -> Self {
+        self.replacements = replacements;
+        self
+    }
+
+    /// Configures the builder to exclude default values from generated parameters.
+    pub fn no_defaults(mut self) -> Self {
+        self.no_defaults = true;
+        self
+    }
+
+    /// Builds a single function parameter from the provided JSON method argument.
+    pub fn build_single(self, method_arg: &JsonMethodArg, ctx: &mut Context) -> FnParam {
+        self.build_single_impl(method_arg, ctx)
+    }
+
+    /// Builds a vector of function parameters from the provided JSON method arguments.
+    pub fn build_many(
+        self,
         method_args: &Option<Vec<JsonMethodArg>>,
         ctx: &mut Context,
     ) -> Vec<FnParam> {
         option_as_slice(method_args)
             .iter()
-            .map(|arg| Self::new_no_defaults(arg, ctx))
+            .map(|arg| self.build_single_impl(arg, ctx))
             .collect()
     }
 
-    pub fn new(method_arg: &JsonMethodArg, ctx: &mut Context) -> FnParam {
+    /// Core implementation for processing a single JSON method argument into a `FnParam`.
+    fn build_single_impl(&self, method_arg: &JsonMethodArg, ctx: &mut Context) -> FnParam {
         let name = safe_ident(&method_arg.name);
         let type_ = conv::to_rust_type(&method_arg.type_, method_arg.meta.as_ref(), ctx);
-        let default_value = method_arg
-            .default_value
-            .as_ref()
-            .map(|v| conv::to_rust_expr(v, &type_));
+
+        // Apply enum replacement if one exists for this parameter
+        let matching_replacement = self
+            .replacements
+            .iter()
+            .find(|(p, ..)| *p == method_arg.name);
+        let type_ = if let Some((_, enum_name, is_bitfield)) = matching_replacement {
+            if !type_.is_integer() {
+                panic!(
+                    "Parameter `{}` is of type {}, but can only replace int with enum",
+                    method_arg.name, type_
+                );
+            }
+            conv::to_enum_type_uncached(enum_name, *is_bitfield)
+        } else {
+            type_
+        };
+
+        let default_value = if self.no_defaults {
+            None
+        } else {
+            method_arg
+                .default_value
+                .as_ref()
+                .map(|v| conv::to_rust_expr(v, &type_))
+        };
 
         FnParam {
             name,
             type_,
             default_value,
         }
     }
-
-    /// `impl AsArg<Gd<T>>` for object parameters. Only set if requested and `T` is an engine class.
-    pub fn new_no_defaults(method_arg: &JsonMethodArg, ctx: &mut Context) -> FnParam {
-        FnParam {
-            name: safe_ident(&method_arg.name),
-            type_: conv::to_rust_type(&method_arg.type_, method_arg.meta.as_ref(), ctx),
-            //type_: to_rust_type(&method_arg.type_, &method_arg.meta, ctx),
-            default_value: None,
-        }
-    }
 }
 
 impl fmt::Debug for FnParam {
@@ -572,9 +618,31 @@ pub struct FnReturn {
 
 impl FnReturn {
     pub fn new(return_value: &Option<JsonMethodReturn>, ctx: &mut Context) -> Self {
+        Self::with_enum_replacements(return_value, &[], ctx)
+    }
+
+    pub fn with_enum_replacements(
+        return_value: &Option<JsonMethodReturn>,
+        replacements: EnumReplacements,
+        ctx: &mut Context,
+    ) -> Self {
         if let Some(ret) = return_value {
             let ty = conv::to_rust_type(&ret.type_, ret.meta.as_ref(), ctx);
 
+            // Apply enum replacement if one exists for return type (indicated by empty string)
+            let matching_replacement = replacements.iter().find(|(p, ..)| p.is_empty());
+            let ty = if let Some((_, enum_name, is_bitfield)) = matching_replacement {
+                if !ty.is_integer() {
+                    panic!(
+                        "Return type is of type {}, but can only replace int with enum",
+                        ty
+                    );
+                }
+                conv::to_enum_type_uncached(enum_name, *is_bitfield)
+            } else {
+                ty
+            };
+
             Self {
                 decl: ty.return_decl(),
                 type_: Some(ty),
@@ -607,6 +675,14 @@ impl FnReturn {
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+// Int->enum replacements
+
+/// Replacement of int->enum in engine APIs; each tuple being `(param_name, enum_type, is_bitfield)`.
+///
+/// Empty string `""` is used as `param_name` to denote return type replacements.
+pub type EnumReplacements = &'static [(&'static str, &'static str, bool)];
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Godot type
 
@@ -682,6 +758,18 @@ impl RustTy {
             other => quote! { -> #other },
         }
     }
+
+    pub fn is_integer(&self) -> bool {
+        let RustTy::BuiltinIdent { ty, .. } = self else {
+            return false;
+        };
+
+        // isize/usize currently not supported (2025-09), but this is more future-proof.
+        matches!(
+            ty.to_string().as_str(),
+            "i8" | "i16" | "i32" | "i64" | "u8" | "u16" | "u32" | "u64" | "isize" | "usize"
+        )
+    }
 }
 
 impl ToTokens for RustTy {

godot-codegen/src/models/domain_mapping.rs

@@ -13,14 +13,14 @@ use crate::context::Context;
 use crate::models::domain::{
     BuildConfiguration, BuiltinClass, BuiltinMethod, BuiltinSize, BuiltinVariant, Class,
     ClassCommons, ClassConstant, ClassConstantValue, ClassMethod, ClassSignal, Constructor, Enum,
-    Enumerator, EnumeratorValue, ExtensionApi, FnDirection, FnParam, FnQualifier, FnReturn,
-    FunctionCommon, GodotApiVersion, ModName, NativeStructure, Operator, RustTy, Singleton, TyName,
-    UtilityFunction,
+    EnumReplacements, Enumerator, EnumeratorValue, ExtensionApi, FnDirection, FnParam, FnQualifier,
+    FnReturn, FunctionCommon, GodotApiVersion, ModName, NativeStructure, Operator, RustTy,
+    Singleton, TyName, UtilityFunction,
 };
 use crate::models::json::{
     JsonBuiltinClass, JsonBuiltinMethod, JsonBuiltinSizes, JsonClass, JsonClassConstant,
     JsonClassMethod, JsonConstructor, JsonEnum, JsonEnumConstant, JsonExtensionApi, JsonHeader,
-    JsonMethodReturn, JsonNativeStructure, JsonOperator, JsonSignal, JsonSingleton,
+    JsonMethodArg, JsonMethodReturn, JsonNativeStructure, JsonOperator, JsonSignal, JsonSingleton,
     JsonUtilityFunction,
 };
 use crate::util::{get_api_level, ident, option_as_slice};
@@ -378,7 +378,9 @@ impl BuiltinMethod {
                 godot_name: method.name.clone(),
                 // Disable default parameters for builtin classes.
                 // They are not public-facing and need more involved implementation (lifetimes etc.). Also reduces number of symbols in API.
-                parameters: FnParam::new_range_no_defaults(&method.arguments, ctx),
+                parameters: FnParam::builder()
+                    .no_defaults()
+                    .build_many(&method.arguments, ctx),
                 return_value: FnReturn::new(&return_value, ctx),
                 is_vararg: method.is_vararg,
                 is_private: false, // See 'exposed' below. Could be special_cases::is_method_private(builtin_name, &method.name),
@@ -431,7 +433,7 @@ impl ClassMethod {
 
         Self::from_json_inner(
             method,
-            rust_method_name,
+            rust_method_name.as_ref(),
             class_name,
             FnDirection::Outbound { hash },
             ctx,
@@ -518,8 +520,22 @@ impl ClassMethod {
             is_required_in_json
         };
 
-        let parameters = FnParam::new_range(&method.arguments, ctx);
-        let return_value = FnReturn::new(&method.return_value, ctx);
+        // Ensure that parameters/return types listed in the replacement truly exist in the method.
+        // The validation function now returns the validated replacement slice for reuse.
+        let enum_replacements = validate_enum_replacements(
+            class_name,
+            &method.name,
+            option_as_slice(&method.arguments),
+            method.return_value.is_some(),
+        );
+
+        let parameters = FnParam::builder()
+            .enum_replacements(enum_replacements)
+            .build_many(&method.arguments, ctx);
+
+        let return_value =
+            FnReturn::with_enum_replacements(&method.return_value, enum_replacements, ctx);
+
         let is_unsafe = Self::function_uses_pointers(&parameters, &return_value);
 
         // Future note: if further changes are made to the virtual method name, make sure to make it reversible so that #[godot_api]
@@ -586,7 +602,7 @@ impl ClassSignal {
 
         Some(Self {
             name: json_signal.name.clone(),
-            parameters: FnParam::new_range(&json_signal.arguments, ctx),
+            parameters: FnParam::builder().build_many(&json_signal.arguments, ctx),
             surrounding_class: surrounding_class.clone(),
         })
     }
@@ -605,7 +621,7 @@ impl UtilityFunction {
         let parameters = if function.is_vararg && args.len() == 1 && args[0].name == "arg1" {
             vec![]
         } else {
-            FnParam::new_range(&function.arguments, ctx)
+            FnParam::builder().build_many(&function.arguments, ctx)
         };
 
         let godot_method_name = function.name.clone();
@@ -737,6 +753,44 @@ impl ClassConstant {
     }
 }
 
+// ----------------------------------------------------------------------------------------------------------------------------------------------
+
+/// Validates that all parameters and non-unit return types declared in an enum replacement slices actually exist in the method.
+///
+/// This is a measure to prevent accidental typos or listing inexistent parameters, which would have no effect.
+fn validate_enum_replacements(
+    class_ty: &TyName,
+    godot_method_name: &str,
+    method_arguments: &[JsonMethodArg],
+    has_return_type: bool,
+) -> EnumReplacements {
+    let replacements =
+        special_cases::get_class_method_param_enum_replacement(class_ty, godot_method_name);
+
+    for (param_name, enum_name, _) in replacements {
+        if param_name.is_empty() {
+            assert!(has_return_type,
+                "Method `{class}.{godot_method_name}` has no return type, but replacement with `{enum_name}` is declared",
+                class = class_ty.godot_ty
+            );
+        } else if !method_arguments.iter().any(|arg| arg.name == *param_name) {
+            let available_params = method_arguments
+                .iter()
+                .map(|arg| format!("  * {}: {}", arg.name, arg.type_))
+                .collect::<Vec<_>>()
+                .join("\n");
+
+            panic!(
+                "Method `{class}.{godot_method_name}` has no parameter `{param_name}`, but a replacement with `{enum_name}` is declared\n\
+                \n{count} parameters available:\n{available_params}\n",
+                class = class_ty.godot_ty, count = method_arguments.len(),
+            );
+        }
+    }
+
+    replacements
+}
+
 // ----------------------------------------------------------------------------------------------------------------------------------------------
 // Native structures