improve docs

Author: makspll

crates/bevy_mod_scripting_core/src/asset.rs

@@ -16,12 +16,12 @@ use bevy::{
         ResMut,
     },
     reflect::TypePath,
-    utils::HashMap,
+    utils::hashbrown::HashMap,
 };
 use std::borrow::Cow;
 
 /// Represents a scripting language. Languages which compile into another language should use the target language as their language.
-#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Default)]
 pub enum Language {
     /// The Rhai scripting language
     Rhai,
@@ -32,6 +32,7 @@ pub enum Language {
     /// An external scripting language
     External(Cow<'static, str>),
     /// Set if none of the asset path to language mappers match
+    #[default]
     Unknown,
 }
 
@@ -110,8 +111,8 @@ impl AssetLoader for ScriptAssetLoader {
 pub struct ScriptAssetSettings {
     /// Strategy for mapping asset paths to script ids, by default this is the identity function
     pub script_id_mapper: AssetPathToScriptIdMapper,
-    /// Strategies for mapping asset paths to languages
-    pub script_language_mappers: Vec<AssetPathToLanguageMapper>,
+    /// Mapping from extension to script language
+    pub extension_to_language_map: HashMap<&'static str, Language>,
 
     /// The currently supported asset extensions
     /// Should be updated by each scripting plugin to include the extensions it supports.
@@ -123,15 +124,11 @@ pub struct ScriptAssetSettings {
 impl ScriptAssetSettings {
     /// Selects the language for a given asset path
     pub fn select_script_language(&self, path: &AssetPath) -> Language {
-        for mapper in &self.script_language_mappers {
-            let language = (mapper.map)(path);
-            match language {
-                Language::Unknown => continue,
-                _ => return language,
-            }
-        }
-
-        Language::Unknown
+        let extension = path.path().extension().and_then(|ext| ext.to_str()).unwrap_or_default();
+        self.extension_to_language_map
+            .get(extension)
+            .cloned()
+            .unwrap_or_default()    
     }
 }
 
@@ -141,7 +138,12 @@ impl Default for ScriptAssetSettings {
             script_id_mapper: AssetPathToScriptIdMapper {
                 map: (|path: &AssetPath| path.path().to_string_lossy().into_owned().into()),
             },
-            script_language_mappers: vec![],
+            extension_to_language_map: HashMap::from_iter(vec![
+                ("lua", Language::Lua),
+                ("luau", Language::Lua),
+                ("rhai", Language::Rhai),
+                ("rn", Language::Rune),
+            ]),
             supported_extensions: &[],
         }
     }
@@ -154,20 +156,6 @@ pub struct AssetPathToScriptIdMapper {
     pub map: fn(&AssetPath) -> ScriptId,
 }
 
-#[derive(Clone, Copy)]
-/// Strategy for mapping asset paths to languages
-pub struct AssetPathToLanguageMapper {
-    /// The mapping function
-    pub map: fn(&AssetPath) -> Language,
-}
-
-impl Default for AssetPathToLanguageMapper {
-    fn default() -> Self {
-        Self {
-            map: |_| Language::Unknown,
-        }
-    }
-}
 
 /// A cache of asset id's to their script id's. Necessary since when we drop an asset we won't have the ability to get the path from the asset.
 #[derive(Default, Debug, Resource)]
@@ -393,26 +381,10 @@ mod tests {
             script_id_mapper: AssetPathToScriptIdMapper {
                 map: |path| path.path().to_string_lossy().into_owned().into(),
             },
-            script_language_mappers: vec![
-                AssetPathToLanguageMapper {
-                    map: |path| {
-                        if path.path().extension().unwrap() == "lua" {
-                            Language::Lua
-                        } else {
-                            Language::Unknown
-                        }
-                    },
-                },
-                AssetPathToLanguageMapper {
-                    map: |path| {
-                        if path.path().extension().unwrap() == "rhai" {
-                            Language::Rhai
-                        } else {
-                            Language::Unknown
-                        }
-                    },
-                },
-            ],
+            extension_to_language_map: HashMap::from_iter(vec![
+                ("lua", Language::Lua),
+                ("rhai", Language::Rhai),
+            ]),
         }
     }
 

crates/bevy_mod_scripting_core/src/lib.rs

@@ -4,7 +4,7 @@
 
 use crate::event::ScriptErrorEvent;
 use asset::{
-    configure_asset_systems, configure_asset_systems_for_plugin, AssetPathToLanguageMapper,
+    configure_asset_systems, configure_asset_systems_for_plugin,
     Language, ScriptAsset, ScriptAssetLoader, ScriptAssetSettings,
 };
 use bevy::prelude::*;
@@ -87,16 +87,17 @@ pub struct ScriptingPlugin<P: IntoScriptPluginParams> {
     /// The strategy for assigning contexts to scripts
     pub context_assignment_strategy: ContextAssignmentStrategy,
 
-    /// The asset path to language mapper for the plugin
-    pub language_mapper: AssetPathToLanguageMapper,
+    /// The language this plugin declares
+    pub language: Language,
+    /// Supported extensions to be added to the asset settings without the dot
+    /// By default BMS populates a set of extensions for the languages it supports.
+    pub additional_supported_extensions: &'static [&'static str],
 
     /// initializers for the contexts, run when loading the script
     pub context_initializers: Vec<ContextInitializer<P>>,
     /// initializers for the contexts run every time before handling events
     pub context_pre_handling_initializers: Vec<ContextPreHandlingInitializer<P>>,
 
-    /// Supported extensions to be added to the asset settings without the dot
-    pub supported_extensions: &'static [&'static str],
 }
 
 impl<P: IntoScriptPluginParams> Default for ScriptingPlugin<P> {
@@ -106,10 +107,10 @@ impl<P: IntoScriptPluginParams> Default for ScriptingPlugin<P> {
             callback_handler: CallbackSettings::<P>::default().callback_handler,
             context_builder: Default::default(),
             context_assignment_strategy: Default::default(),
-            language_mapper: Default::default(),
+            language: Default::default(),
             context_initializers: Default::default(),
             context_pre_handling_initializers: Default::default(),
-            supported_extensions: Default::default(),
+            additional_supported_extensions: Default::default(),
         }
     }
 }
@@ -136,13 +137,9 @@ impl<P: IntoScriptPluginParams> Plugin for ScriptingPlugin<P> {
         // add extension for the language to the asset loader
         once_per_app_init(app);
 
-        app.add_supported_script_extensions(self.supported_extensions);
-
-        app.world_mut()
-            .resource_mut::<ScriptAssetSettings>()
-            .as_mut()
-            .script_language_mappers
-            .push(self.language_mapper);
+        if !self.additional_supported_extensions.is_empty() {
+            app.add_supported_script_extensions(self.additional_supported_extensions, self.language.clone());
+        }
 
         register_types(app);
     }
@@ -203,6 +200,11 @@ pub trait ConfigureScriptPlugin {
     /// This means that all scripts will share the same context. This is useful for when you want to share data between scripts easilly.
     /// Be careful however as this also means that scripts can interfere with each other in unexpected ways! Including overwriting each other's handlers.
     fn enable_context_sharing(self) -> Self;
+
+    /// Set the set of extensions to be added for the plugin's language.
+    /// 
+    /// This is useful for adding extensions that are not supported by default by BMS.
+    fn set_additional_supported_extensions(self, extensions: &'static [&'static str]) -> Self;
 }
 
 impl<P: IntoScriptPluginParams + AsMut<ScriptingPlugin<P>>> ConfigureScriptPlugin for P {
@@ -231,6 +233,13 @@ impl<P: IntoScriptPluginParams + AsMut<ScriptingPlugin<P>>> ConfigureScriptPlugi
         self.as_mut().context_assignment_strategy = ContextAssignmentStrategy::Global;
         self
     }
+
+    fn set_additional_supported_extensions(mut self, extensions: &'static [&'static str]) -> Self {
+        self.as_mut().additional_supported_extensions = extensions;
+        self
+    }
+
+    
 }
 
 fn once_per_app_finalize(app: &mut App) {
@@ -386,11 +395,13 @@ impl ManageStaticScripts for App {
 /// Any changes to the asset settings after that will not be reflected in the asset loader.
 pub trait ConfigureScriptAssetSettings {
     /// Adds a supported extension to the asset settings
-    fn add_supported_script_extensions(&mut self, extensions: &[&'static str]) -> &mut Self;
+    /// 
+    /// This is only valid to call in the plugin building phase, as the asset loader will be created in the `finalize` phase.
+    fn add_supported_script_extensions(&mut self, extensions: &[&'static str], language: Language) -> &mut Self;
 }
 
 impl ConfigureScriptAssetSettings for App {
-    fn add_supported_script_extensions(&mut self, extensions: &[&'static str]) -> &mut Self {
+    fn add_supported_script_extensions(&mut self, extensions: &[&'static str], language: Language) -> &mut Self {
         let mut asset_settings = self
             .world_mut()
             .get_resource_or_init::<ScriptAssetSettings>();
@@ -402,6 +413,9 @@ impl ConfigureScriptAssetSettings for App {
         let new_arr_static = Vec::leak(new_arr);
 
         asset_settings.supported_extensions = new_arr_static;
+        for extension in extensions {
+            asset_settings.extension_to_language_map.insert(*extension, language.clone());
+        }
 
         self
     }

crates/languages/bevy_mod_scripting_lua/src/lib.rs

@@ -134,7 +134,7 @@ impl Default for LuaScriptingPlugin {
                         .map_err(ScriptError::from_mlua_error)?;
                     Ok(())
                 }],
-                supported_extensions: &["lua"],
+                additional_supported_extensions: &["lua"],
             },
         }
     }

crates/languages/bevy_mod_scripting_rhai/src/lib.rs

@@ -159,7 +159,7 @@ impl Default for RhaiScriptingPlugin {
                     context.scope.set_or_push("script_id", script.to_owned());
                     Ok(())
                 }],
-                supported_extensions: &["rhai"],
+                additional_supported_extensions: &["rhai"],
             },
         }
     }

docs/src/SUMMARY.md

@@ -16,6 +16,7 @@
 # Scripting Reference
 
 - [Introduction](./ScriptingReference/introduction.md)
+- [Constructing Arbitrary Types](./ScriptingReference/constructing-arbitrary-types.md)
 - [Core Bindings](./ScriptingReference/core-api.md)
     - [World](./ScriptingReference/world.md)
     - [ReflectReference](./ScriptingReference/reflect-reference.md)

docs/src/ScriptingReference/constructing-arbitrary-types.md

@@ -0,0 +1,72 @@
+# Constructing Arbitrary Types
+
+When interfacing with bevy, we do this via reflection.
+While the generated bindings do not cover constructors for every single type that bevy or other libraries provide, reflection allows us to construct some (not all types implement `FromReflect`) types from dynamic structs.
+
+BMS exposes this ability to all script writers via the `construct` global function.
+
+
+## Structs
+
+The following struct:
+```rust,ignore
+pub struct MyStruct {
+    pub my_field: String
+}
+```
+
+can be constructed from lua like so:
+```lua
+local MyStruct = world.get_type_by_name("MyStruct")
+local concrete_my_struct = construct(MyStruct, {
+    my_field = "hello"
+})
+```
+
+## Tuple Structs
+The following tuple struct:
+```rust,ignore
+
+pub struct MyTupleStruct(pub String);
+```
+
+can be constructed like so:
+```lua
+
+local MyTupleStruct = world.get_type_by_name("MyTupleStruct")
+local concrete_my_tuple_struct = construct(MyTupleStruct, {
+    _1 = "hello"
+})
+```
+
+## Enums
+The following enum:
+```rust,ignore
+pub enum MyEnum {
+    VariantA {
+        field: String
+    },
+    VariantB
+}
+```
+
+can be constructed like so:
+```lua
+
+local MyEnum = world.get_type_by_name("MyEnum")
+local variantA = construct(MyEnum, {
+    variant = "VariantA",
+    field = "hello"
+})
+local variantB = construct(MyEnum, {
+    variant = "VariantB"
+})
+```
+
+When working with enums you can also figure out the variant at runtime using `variant_name`:
+
+```lua
+if my_enum:variant_name() == "VariantA" then
+    print(my_enum.field)
+end
+```

docs/src/ScriptingReference/introduction.md

@@ -8,5 +8,5 @@ If you are a modder, welcome! 👋, apologies for the rust-centricity of this gu
 
 Scripts will have access to a few global variables in most callbacks:
 - `world`: a static reference to the world, with all sorts of functions available
-- `entity`: the entity the script is attached to, not available on load/unload callbacks
+- `entity`: the entity the script is attached to, not available on load/unload callbacks, and in dynamic system callbacks.
 - `script_id`: the ID of the current script 

docs/src/Summary/controlling-script-bindings.md

@@ -59,6 +59,32 @@ hello_world2("hi from global!");
 
 Note the `new_unregistered` call instead of `new`, this is because `GlobalNamespace` is not a `Reflect` type, and the `new` call also automatically registers the type in the reflection registry.
 
+## Macros
+The above is a bit tedious, so instead you can use the `script_bindings` macro, which applies to impl blocks like so:
+
+```rust,ignore
+#[script_bindings("test_fn")]
+impl TestStruct {
+    /// My docs !!
+    /// 
+    /// Arguments:
+    /// * `_self` - the first argument
+    /// * `arg1` - the second argument
+    /// Returns:
+    /// * `return` - nothing
+    fn test_fn(_self: Ref<TestStruct>, mut arg1: usize) {}
+}
+
+
+pub fn main() {
+    let mut app = App::new();
+    register_test_fn(app.world_mut())
+}
+```
+
+Note the documentation will automatically be picked up and stored for the purposes of reflection and documentation generation, including argument/return type specific docs.
+
+
 ## Context Arguments
 
 Each script function call always receives an additional context argument: `FunctionCallContext`.