Expand description
§bevy_mod_scripting_luars
A luars backend for bevy_mod_scripting that supports WASM instead of mlua, which does not support WASM yet.
§Usage
Leave BMS’s bundled Lua (mlua) off. Add this plugin instead.
[dependencies]
bevy = "0.19"
bevy_mod_scripting = { version = "0.21", default-features = false, features = ["core_functions"] }
bevy_mod_scripting_luars = { git = "https://github.com/shanecelis/bevy_mod_scripting_luars" }use bevy::prelude::*;
use bevy_mod_scripting::BMSPlugin;
use bevy_mod_scripting_luars::LuarsScriptingPlugin;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins((BMSPlugin, LuarsScriptingPlugin::default()))
.run();
}Do not enable BMS lua or lua54 features alongside this crate; that would
pull in two Lua VMs.
Assets with .lua and .luau suffixes load as Lua 5.5.
§Technical Note
luars is enabled with unsafe-send so the VM is Send for Bevy.
§Library API
LuarsScriptingPlugin is the whole product for most apps. Add it and load
scripts the BMS way. Scripts see world, entity, script_asset,
register_callback, and any other globals registered with BMS.
These types are for talking to the VM:
| Item | When you need it |
|---|---|
LuarsContext | ScriptContexts gave you the VM; deref to luars::Lua |
luars | Re-export of the Luars crate (LuaApi, LuaError, …) |
(Multi)LuaScriptValue | eval / eval_multi in BMS values |
into_bms_error | Turn a LuaError into a readable BMS error |
Lua(Static)ReflectReference | Inject a reflected value or type into a context |
§Example: eval
A small Bevy window that acts as a Lua REPL. Type an expression, press Enter,
and the result shows above the prompt. Globals persist for the session (assign
x = 3, then evaluate x * x).
§Native
cargo run --example eval --features eval§WASM
Run the eval example in the browser (needs trunk and the
wasm32-unknown-unknown target). Debug wasm is hundreds of MiB. Pass
--release for a smaller wasm, but it takes longer.
trunk serve --config web/Trunk.toml; # Debug. Fast but big: ~290MiB.
trunk serve --config web/Trunk.toml --release; # Release. Slow but small: ~18MiB.Then open http://localhost:8080/. Click the canvas so it receives keyboard focus. Host a release build with gzip or brotli; that shrinks transfer further.
Try:
1 + 2
string.upper("hi")
x = 10
x * x§Wasm
On wasm32 the VM opens a subset of the standard library: basic, math, string,
table, utf8, coroutine, package, and debug. Not io or os.
getrandom uses the wasm_js backend (see .cargo/config.toml). The eval
binary is linked with a 16MB stack. Trunk copies assets/ next to the wasm so
eval.lua loads in the browser.
§Compatibility
| bevy_mod_scripting_luars | bms | bevy |
|---|---|---|
| 0.2.0 | 0.23 | 0.20 |
| 0.1.0 | 0.21 | 0.19 |
§Provenance
This project was extracted from the Nano-9 code base.
§License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Re-exports§
pub use luars;
Structs§
- LuaReflect
Reference - Lua userdata for a live
ReflectReference. - LuaScript
Value - A
ScriptValuethat converts through luarsFromLua/IntoLua. - LuaStatic
Reflect Reference - Lua userdata for a type, so scripts can call
Entity.from_raw(...). - Luars
Context - Per-script Lua 5.5 VM, stored as BMS’s language context.
- Luars
Scripting Plugin - BMS language plugin that runs Lua 5.5 via luars instead of mlua.
- Multi
LuaScript Value - Several
ScriptValues, for Lua’s multiple return values.
Functions§
- into_
bms_ error - Convert a luars
LuaErrorinto a BMSInteropErrorusing the VM’s stored message.