While for Bevy out of the box scripting is a non-goal, scripting support is being worked on. This crate is an attempt to make scripting a possibility with the current state of Bevy.
The API will likely change in the future as more scripting support is rolled out.
require (enabled with unsafe_lua_modules cargo feature due to potential unsafety)To install:
- Add this crate to your Cargo.toml file dependencies
- The crate is still in development so I recommended pinning to a git commit
- Add ScriptingPlugin to your app
- Add the ScriptHosts you plan on using (add_script_host)
- Make sure to attach it to a stage running AFTER any systems which may generate modify/create/remove script components
- Add script handler stages to capture events in the priority range you're expecting (add_script_handler_stage)
- Add systems which generate ScriptEvents corresponding to your script host
- Add systems which add ScriptCollection components to your entities and fill them with scripts
An example can be seen below
```rust,ignore
fn main() -> std::io::Result<()> {
let mut app = App::new();
app.addplugin(ScriptingPlugin)
.addplugins(DefaultPlugins)
// pick and register only the hosts you want to use
// use any stage AFTER any systems which add/remove/modify script components
// in order for your script updates to propagate in a single frame
.addscripthost::
.addscripthost::
// the handlers should be placed after any stages which produce script events
// PostUpdate is okay only if your API doesn't require the core Bevy systems' commands
// to run beforehand.
// Note, this setup assumes a single script handler stage with all events having identical
// priority of zero (see examples for more complex scenarios)
.add_script_handler_stage::<LuaScriptHost<MyLuaArg>, _, 0, 0>(
CoreStage::PostUpdate,
)
.add_script_handler_stage::<RhaiScriptHost<RhaiEventArgs>, _, 0, 0>(
CoreStage::PostUpdate,
)
// generate events for scripts to pickup
.add_system(trigger_on_update_lua)
.add_system(trigger_on_update_rhai)
// attach script components to entities
.add_startup_system(load_a_script);
app.run();
Ok(())
} ```
Scripts are triggered by firing ScriptEvents. This crate uses custom priority event writers and readers, so events are sent along with a priority. Together with your event pipeline this priority affects when your events are handled. A priority of 0 is the highest.
You can use this to create game loops akin to Unity's or other game engine's.
There are no guarantees that force the script callbacks to be executed fully for all scripts, i.e. before processing the next callback event, so this order guarantee only holds on a per script basis.
Examples of systems which generate callbacks can be seen below:
Use valid lua function names for hook names and any number of arguments which are to be passed on to the function.
Any types implementing the mlua::ToLua trait can be used.
``` rust use bevy::prelude::; use bevy_mod_scripting::{prelude::,events::,langs::mlu::{mlua,mlua::prelude::}};
// event callback generator for lua
pub fn triggeronupdatelua(mut w: PriorityEventWriter
w.send(event,0);
} ```
Rhai supports any rust types implementing FuncArgs as function arguments.
``` rust use bevy::prelude::; use bevy_mod_scripting::{prelude::,langs::rhai::FuncArgs};
pub struct MyRhaiArgStruct { // ... }
impl FuncArgs for MyRhaiArgStruct {
fn parse
// event callback generator for rhai
// rhai event arguments can be any rust type implementing FuncArgs
pub fn triggeronupdaterhai(mut w: PriorityEventWriter
w.send(event,0);
} ```
A script consist of: - an asset handle to their code file - a name which is usually their path relative to the assets folder
Scripts are attached to entities in the form of bevy_mod_scripting::ScriptCollection components as seen below:
``` rust use std::sync::Mutex; use bevy::prelude::; use bevy_mod_scripting::prelude::;
// An example of a startup system which loads the lua script "consoleintegration.lua"
// placed in "assets/scripts/" and attaches it to a new entity
pub fn loadascript(
server: Res
commands.spawn().insert(ScriptCollection::<LuaFile> {
scripts: vec![Script::<LuaFile>::new(
path, handle,
)],
});
} ```
To expose an API to your scripts, implement the APIProvider trait. To register this API with your script host use the add_api_provider of App. APIProviders are a little bit like plugins, since they can also have access to the bevy App via one of the methods provided, and
``` rust use ::std::sync::Mutex; use bevymodscripting::{prelude::,langs::{mlu::mlua::prelude::,rhai::*}};
pub struct LuaAPI;
/// the custom Lua api, world is provided via a global pointer,
/// and callbacks are defined only once at script creation
impl APIProvider for LuaAPI {
type APITarget = Mutex
fn attach_api(&mut self, ctx: &mut Self::APITarget) -> Result<(),ScriptError> {
// generate API here
// world is provided via ctx see examples
// ...
Ok(())
}
}
pub struct RhaiAPI {}
impl APIProvider for RhaiAPI { type APITarget = Engine; type DocTarget = RhaiDocFragment; type ScriptContext = RhaiContext;
fn attach_api(&mut self, ctx: &mut Self::APITarget) -> Result<(),ScriptError> {
// ...
Ok(())
}
}
```
Register the API providers like so:
rust,ignore
app.add_plugins(DefaultPlugins)
.add_plugin(ScriptingPlugin)
.add_script_host::<LuaScriptHost<MyLuaArg>, _>(CoreStage::PostUpdate)
.add_script_host::<RhaiScriptHost<MyRhaiArg>, _>(CoreStage::PostUpdate)
.add_api_provider::<LuaScriptHost<MyLuaArg>>(Box::new(LuaAPIProvider))
.add_api_provider::<LuaScriptHost<MyRhaiArg>>(Box::new(RhaiAPIProvider))
//...
Note that the APIProvider interface also contains setup_script and get_doc_fragment methods which are by default no-ops. These can be used to provide documentation (see examples) and guaranteed one-time-per-script setup (such as lua package path setup).
Documentation features are exposed at runtime via the update_documentation builder trait method for App:
```rust use bevy::prelude::; use bevy_mod_scripting::prelude::;
fn main() -> std::io::Result<()> { let mut app = App::new();
app.add_plugins(DefaultPlugins)
.add_plugin(ScriptingPlugin)
.add_script_host::<LuaScriptHost<()>, _>(CoreStage::PostUpdate)
// Note: This is a noop in optimized builds unless the `doc_always` feature is enabled!
// this will pickup any API providers added *BEFOREHAND* like this one
// .add_api_provider::<LuaScriptHost<()>>(Box::new(LuaAPIProvider))
.update_documentation::<LuaScriptHost<()>>()
.add_script_handler_stage::<LuaScriptHost<()>, _, 0, 0>(
CoreStage::PostUpdate,
);
Ok(())
}
``
Currently we generate documentation at runtime due to the waytealr` works but this might change in the future as ideally this would be done statically.
It is probably a wise idea to setup a separate executable whose purpose is to only generate documentation, and run it every time before a release. But keeping this step in your main app will make sure your script environment is always setup correctly.
Lua documentation is provided by tealr, a wrapper around the mlua lua api which decorates their standard types. On top of providing documentation generation it's also capable of generating d.tl files which can be used to introduce static typing to lua via the teal project (you do not need to use teal to generate documentation).
This can all be seen at work in the this example.
Teal is the reccomended way of introducing lua to your bevy game. This functionality is locked behind the teal cargo feature however, since it's quite opinionanted when it comes to your asset structure (script and scripts/build, folders under assets), and also requires lua + teal + cargo tealr_doc_gen to be installed (see https://github.com/teal-language/tl and tealr).
Once enabled, .tl files can be loaded as lua scripts in addition to .lua files and compiled on the fly. With full hot-reloading support. When you're ready to release your game, you just need to run tl build from the assets/scripts directory to compile your teal files. This will generate .lua files under assets/scripts/build. You can manage loading scripts using the [bevy_mod_scripting::lua_path] macro.
If teal is enabled and you've added the update_documentation step to your app, every time you run/build your app in development the following will be generated/synced:
- a scripts/doc directory containing documentation for your lua exposed API
- a scripts/types directory containing .d.tl files for your lua IDE
- a scripts/tlconfig.lua file will be generated once if it does not yet exist
- any scripts with a .tl extension will be compiled to lua code and type checked
On optimized release builds none of this happens (no debug_asserts).
The reccomended workflow is to use vscode and the official teal extension with an additional tlconfig.lua file at the root of your workspace with the
following content:
lua
return {
include_dir = {
"path_to_your_lib/",
}
}
Rhai currently does not have any utilities existing for generating documentation (for the rust provided API), once something comes out we'll include it.
SCRIPT_DOC_DIR - documentation is generated in assets/scripts/docs or to the path in this ENV variable if it's set.The Script components will persist a scene load, but their script contexts won't, after a scene load you must manually reload the scripts using Script::reload_script
To see more complex applications of this library have a look at the examples:
Below is a video showcasing the gameoflife example:
