feat: implement variadics in bindings via VariadicTuple and add ScriptValue::Tuple (#527)

Author: makspll

assets/tests/variadics/variadics.lua

@@ -0,0 +1,10 @@
+function on_test()
+    local unpacked_a, unpacked_b = unpack_args({ 1, 2 })
+
+    local packed = pack_args(1, 2)
+
+    assert(packed[1] == unpacked_a,
+        "Expected packed[1] to be: " .. tostring(unpacked_a) .. " Got: " .. tostring(packed[1]))
+    assert(packed[2] == unpacked_b,
+        "Expected packed[2] to be:" .. tostring(unpacked_b) .. " Got: " .. tostring(packed[2]))
+end

benches/benchmarks.rs

@@ -2,7 +2,7 @@ extern crate bevy_mod_scripting;
 extern crate script_integration_test_harness;
 extern crate test_utils;
 use bevy_platform::collections::HashMap;
-use std::{path::PathBuf, sync::LazyLock, time::Duration};
+use std::{collections::VecDeque, path::PathBuf, sync::LazyLock, time::Duration};
 
 use bevy::{
     log::{
@@ -173,9 +173,9 @@ fn conversion_benchmarks(criterion: &mut Criterion) {
     perform_benchmark_with_generator(
         "ScriptValue::List",
         &|rng, _| {
-            let mut array = Vec::new();
+            let mut array = VecDeque::new();
             for _ in 0..10 {
-                array.push(ScriptValue::Integer(rng.random()));
+                array.push_back(ScriptValue::Integer(rng.random()));
             }
             ScriptValue::List(array)
         },

crates/bevy_mod_scripting_bindings/src/docgen/info.rs

@@ -10,6 +10,10 @@ use std::{any::TypeId, borrow::Cow};
 use super::typed_through::{ThroughTypeInfo, TypedThrough};
 
 /// for things you can call and provide some introspection capability.
+#[diagnostic::on_unimplemented(
+    message = "This function contains types in its signature which don't implement [`ArgMeta`] or [`TypedThrough`].",
+    note = "These types are necessary to build [`FunctionInfo`] structs for each registered function."
+)]
 pub trait GetFunctionInfo<Marker> {
     /// Get the function info for the function.
     fn get_function_info(&self, name: Cow<'static, str>, namespace: Namespace) -> FunctionInfo;

crates/bevy_mod_scripting_bindings/src/docgen/typed_through.rs

@@ -1,10 +1,10 @@
 //! Defines a set of traits which destruture [`bevy_reflect::TypeInfo`] and implement a light weight wrapper around it, to allow types
 //! which normally can't implement [`bevy_reflect::Typed`] to be used in a reflection context.
 
-use std::{any::TypeId, ffi::OsString, path::PathBuf};
+use std::{any::TypeId, collections::VecDeque, ffi::OsString, path::PathBuf};
 
 use crate::{
-    ReflectReference,
+    ReflectReference, VariadicTuple,
     function::{
         from::{M, R, Union, V},
         script_function::{DynamicScriptFunction, DynamicScriptFunctionMut, FunctionCallContext},
@@ -76,6 +76,8 @@ pub enum TypedWrapperKind {
     InteropResult(Box<ThroughTypeInfo>),
     /// Wraps a tuple of through typed types.
     Tuple(Vec<ThroughTypeInfo>),
+    /// Wraps a tuple of script values
+    UntypedTuple,
 }
 
 /// A dynamic version of [`TypedThrough`], which can be used to convert a [`TypeInfo`] into a [`ThroughTypeInfo`].
@@ -248,6 +250,12 @@ impl<T: TypedThrough> TypedThrough for Vec<T> {
     }
 }
 
+impl<T: TypedThrough> TypedThrough for VecDeque<T> {
+    fn through_type_info() -> ThroughTypeInfo {
+        ThroughTypeInfo::TypedWrapper(TypedWrapperKind::Vec(Box::new(T::through_type_info())))
+    }
+}
+
 impl<K: TypedThrough, V: TypedThrough> TypedThrough for HashMap<K, V> {
     fn through_type_info() -> ThroughTypeInfo {
         ThroughTypeInfo::TypedWrapper(TypedWrapperKind::HashMap(
@@ -286,6 +294,12 @@ impl<T: TypedThrough> TypedThrough for Option<T> {
     }
 }
 
+impl TypedThrough for VariadicTuple {
+    fn through_type_info() -> ThroughTypeInfo {
+        ThroughTypeInfo::TypedWrapper(TypedWrapperKind::UntypedTuple)
+    }
+}
+
 macro_rules! impl_through_typed {
     ($($ty:ty => $ident:ident),*) => {
         $(

crates/bevy_mod_scripting_bindings/src/function/arg_meta.rs

@@ -1,10 +1,12 @@
 //! Trait implementations to help with function dispatch.
 
-use std::{ffi::OsString, path::PathBuf};
+use std::{collections::VecDeque, ffi::OsString, path::PathBuf};
 
 use bevy_platform::collections::HashMap;
 
-use crate::{ReflectReference, ScriptValue, docgen::TypedThrough, error::InteropError};
+use crate::{
+    ReflectReference, ScriptValue, VariadicTuple, docgen::TypedThrough, error::InteropError,
+};
 
 use super::{
     from::{FromScript, M, R, Union, V},
@@ -35,10 +37,25 @@ pub trait ArgMeta {
     fn default_value() -> Option<ScriptValue> {
         None
     }
+
+    /// If returns true, will absorb all arguments following itself
+    fn variadic() -> bool {
+        false
+    }
 }
 
 impl ArgMeta for ScriptValue {}
 
+impl ArgMeta for VariadicTuple {
+    fn default_value() -> Option<ScriptValue> {
+        Some(ScriptValue::Tuple(Default::default()))
+    }
+
+    fn variadic() -> bool {
+        true
+    }
+}
+
 macro_rules! impl_arg_info {
     ($($ty:ty),*) => {
         $(
@@ -85,6 +102,8 @@ impl<T> ArgMeta for Option<T> {
 }
 
 impl<T> ArgMeta for Vec<T> {}
+impl<T> ArgMeta for VecDeque<T> {}
+
 impl<T, const N: usize> ArgMeta for [T; N] {}
 
 impl<K, V> ArgMeta for HashMap<K, V> {}

crates/bevy_mod_scripting_bindings/src/function/from.rs

@@ -2,12 +2,14 @@
 
 use crate::{
     ReflectReference, ScriptValue, WorldGuard, access_map::ReflectAccessId, error::InteropError,
+    script_value::VariadicTuple,
 };
 use bevy_platform::collections::{HashMap, HashSet};
 use bevy_reflect::{FromReflect, Reflect};
 use nonmax::NonMaxU32;
 use std::{
     any::TypeId,
+    collections::VecDeque,
     ffi::OsString,
     ops::{Deref, DerefMut},
     path::PathBuf,
@@ -411,6 +413,30 @@ where
     }
 }
 
+#[profiling::all_functions]
+impl<T: FromScript + 'static> FromScript for VecDeque<T>
+where
+    for<'w> T::This<'w>: Into<T>,
+{
+    type This<'w> = Self;
+    #[profiling::function]
+    fn from_script(value: ScriptValue, world: WorldGuard) -> Result<Self, InteropError> {
+        match value {
+            ScriptValue::List(list) => {
+                let mut vec = VecDeque::with_capacity(list.len());
+                for item in list {
+                    vec.push_back(T::from_script(item, world.clone())?.into());
+                }
+                Ok(vec)
+            }
+            _ => Err(InteropError::value_mismatch(
+                std::any::TypeId::of::<VecDeque<T>>(),
+                value,
+            )),
+        }
+    }
+}
+
 #[profiling::all_functions]
 impl<T: FromScript + 'static, const N: usize> FromScript for [T; N]
 where
@@ -615,6 +641,23 @@ where
     }
 }
 
+impl FromScript for VariadicTuple {
+    type This<'w> = Self;
+
+    fn from_script(
+        value: ScriptValue,
+        _world: WorldGuard<'_>,
+    ) -> Result<Self::This<'_>, InteropError>
+    where
+        Self: Sized,
+    {
+        match value {
+            ScriptValue::List(tuple) | ScriptValue::Tuple(VariadicTuple(tuple)) => Ok(Self(tuple)),
+            v => Ok(Self(VecDeque::from_iter([v]))),
+        }
+    }
+}
+
 macro_rules! impl_from_script_tuple {
     ($($ty:ident),*) => {
         #[allow(non_snake_case)]
@@ -630,7 +673,7 @@ macro_rules! impl_from_script_tuple {
 
             fn from_script(value: ScriptValue, world: WorldGuard<'_>) -> Result<Self, InteropError> {
                 match value {
-                    ScriptValue::List(list) => {
+                    ScriptValue::List(list) | ScriptValue::Tuple(VariadicTuple(list)) => {
                         let expected_arg_count = $crate::function::script_function::count!( $($ty)* );
                         if list.len() != expected_arg_count {
                             return Err(InteropError::length_mismatch(expected_arg_count, list.len()));

crates/bevy_mod_scripting_bindings/src/function/into.rs

@@ -1,10 +1,10 @@
 //! Implementations of the [`IntoScript`] trait for various types.
 
 use super::{DynamicScriptFunction, DynamicScriptFunctionMut, Union, V};
-use crate::{ReflectReference, ScriptValue, WorldGuard, error::InteropError};
+use crate::{ReflectReference, ScriptValue, VariadicTuple, WorldGuard, error::InteropError};
 use bevy_platform::collections::HashMap;
 use bevy_reflect::Reflect;
-use std::{borrow::Cow, ffi::OsString, path::PathBuf};
+use std::{borrow::Cow, collections::VecDeque, ffi::OsString, path::PathBuf};
 
 /// Converts a value into a [`ScriptValue`].
 pub trait IntoScript {
@@ -136,9 +136,20 @@ impl<T: IntoScript> IntoScript for Option<T> {
 #[profiling::all_functions]
 impl<T: IntoScript> IntoScript for Vec<T> {
     fn into_script(self, world: WorldGuard) -> Result<ScriptValue, InteropError> {
-        let mut values = Vec::with_capacity(self.len());
+        let mut values = VecDeque::with_capacity(self.len());
         for val in self {
-            values.push(val.into_script(world.clone())?);
+            values.push_back(val.into_script(world.clone())?);
+        }
+        Ok(ScriptValue::List(values))
+    }
+}
+
+#[profiling::all_functions]
+impl<T: IntoScript> IntoScript for VecDeque<T> {
+    fn into_script(self, world: WorldGuard) -> Result<ScriptValue, InteropError> {
+        let mut values = VecDeque::with_capacity(self.len());
+        for val in self {
+            values.push_back(val.into_script(world.clone())?);
         }
         Ok(ScriptValue::List(values))
     }
@@ -147,9 +158,9 @@ impl<T: IntoScript> IntoScript for Vec<T> {
 #[profiling::all_functions]
 impl<T: IntoScript, const N: usize> IntoScript for [T; N] {
     fn into_script(self, world: WorldGuard) -> Result<ScriptValue, InteropError> {
-        let mut values = Vec::with_capacity(N);
+        let mut values = VecDeque::with_capacity(N);
         for val in self {
-            values.push(val.into_script(world.clone())?);
+            values.push_back(val.into_script(world.clone())?);
         }
         Ok(ScriptValue::List(values))
     }
@@ -194,14 +205,20 @@ impl IntoScript for InteropError {
     }
 }
 
+impl IntoScript for VariadicTuple {
+    fn into_script(self, _world: WorldGuard) -> Result<ScriptValue, InteropError> {
+        Ok(ScriptValue::Tuple(self))
+    }
+}
+
 macro_rules! impl_into_script_tuple {
     ($( $ty:ident ),* ) => {
         #[allow(non_snake_case)]
         #[profiling::all_functions]
         impl<$($ty: IntoScript),*> IntoScript for ($($ty,)*) {
         fn into_script(self, world: WorldGuard) -> Result<ScriptValue, InteropError> {
             let ($($ty,)*) = self;
-            Ok(ScriptValue::List(vec![$($ty.into_script(world.clone())?),*]))
+            Ok(ScriptValue::Tuple(crate::script_value::VariadicTuple(VecDeque::from_iter([$($ty.into_script(world.clone())?),*].into_iter()))))
         }
     }
 }

crates/bevy_mod_scripting_bindings/src/function/script_function.rs

@@ -2,6 +2,7 @@
 
 use super::MagicFunctions;
 use super::{from::FromScript, into::IntoScript, namespace::Namespace};
+use crate::VariadicTuple;
 use crate::docgen::info::{FunctionInfo, GetFunctionInfo};
 use crate::function::arg_meta::ArgMeta;
 use crate::{ScriptValue, ThreadWorldContainer, WorldGuard, error::InteropError};
@@ -17,10 +18,8 @@ use std::collections::VecDeque;
 use std::hash::Hash;
 use std::ops::{Deref, DerefMut};
 use std::sync::Arc;
-
 #[diagnostic::on_unimplemented(
-    message = "This function does not fulfil the requirements to be a script callable function. All arguments must implement the ScriptArgument trait and all return values must implement the ScriptReturn trait",
-    note = "If you're trying to return a non-primitive type, you might need to use V<T> R<T> or M<T> wrappers"
+    message = "This function does not fulfil the requirements to be a script callable function. All arguments must implement the ScriptArgument trait and all return values must implement the ScriptReturn trait"
 )]
 /// A trait implemented by functions which can act as dynamic script functions, which can then be registered against a [`ScriptFunctionRegistry`].
 pub trait ScriptFunction<'env, Marker> {
@@ -30,7 +29,7 @@ pub trait ScriptFunction<'env, Marker> {
 
 #[diagnostic::on_unimplemented(
     message = "Only functions with all arguments impplementing FromScript and return values supporting IntoScript are supported. Registering functions also requires they implement GetTypeDependencies",
-    note = "If you're trying to return a non-primitive type, you might need to use V<T> R<T> or M<T> wrappers"
+    note = "If you're trying to use a non-primitive type, you might need to use V<T> R<T> or M<T> wrappers"
 )]
 /// A trait implemented by functions which can act as mutable dynamic script functions.
 pub trait ScriptFunctionMut<'env, Marker> {
@@ -608,6 +607,19 @@ macro_rules! count {
         ( $x:tt $($xs:tt)* ) => (1usize + $crate::function::script_function::count!($($xs)*));
 }
 
+/// Pops the stack of args depending on how many are requested by the current argument.
+/// If failed to find argument, returns None
+fn pop_args_stack_for_arg<A: ArgMeta>(args: &mut VecDeque<ScriptValue>) -> Option<ScriptValue> {
+    if A::variadic() {
+        // just absorb the rest, tuplify it
+        if !args.is_empty() {
+            return Some(ScriptValue::Tuple(VariadicTuple(std::mem::take(args))));
+        }
+    }
+
+    args.pop_front().or_else(A::default_value)
+}
+
 pub(crate) use count;
 
 macro_rules! impl_script_function {
@@ -674,15 +686,10 @@ macro_rules! impl_script_function {
                                 $(let $param = {
                                         profiling::scope!("argument conversion", &format!("argument #{}", current_arg));
                                         current_arg += 1;
-                                        let $param = args.pop_front();
-                                        let $param = match $param {
+                                        let $param = match pop_args_stack_for_arg::<$param>(&mut args) {
                                             Some($param) => $param,
                                             None => {
-                                                if let Some(default) = <$param>::default_value() {
-                                                    default
-                                                } else {
-                                                    return Err(InteropError::argument_count_mismatch(expected_arg_count,received_args_len));
-                                                }
+                                                return Err(InteropError::argument_count_mismatch(expected_arg_count,received_args_len));
                                             }
                                         };
                                         let $param = <$param>::from_script($param, world.clone())