bevy_mod_scripting_luars 0.2.0

A luars backend for bevy_mod_scripting with WASM support
Documentation

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

▶ Run the WASM demo

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

at your option.