Skip to main content

Crate bevy_mod_scripting_luars

Crate bevy_mod_scripting_luars 

Source
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:

ItemWhen you need it
LuarsContextScriptContexts gave you the VM; deref to luars::Lua
luarsRe-export of the Luars crate (LuaApi, LuaError, …)
(Multi)LuaScriptValueeval / eval_multi in BMS values
into_bms_errorTurn a LuaError into a readable BMS error
Lua(Static)ReflectReferenceInject 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_luarsbmsbevy
0.2.00.230.20
0.1.00.210.19

§Provenance

This project was extracted from the Nano-9 code base.

§License

Licensed under either of

at your option.

Re-exports§

pub use luars;

Structs§

LuaReflectReference
Lua userdata for a live ReflectReference.
LuaScriptValue
A ScriptValue that converts through luars FromLua / IntoLua.
LuaStaticReflectReference
Lua userdata for a type, so scripts can call Entity.from_raw(...).
LuarsContext
Per-script Lua 5.5 VM, stored as BMS’s language context.
LuarsScriptingPlugin
BMS language plugin that runs Lua 5.5 via luars instead of mlua.
MultiLuaScriptValue
Several ScriptValues, for Lua’s multiple return values.

Functions§

into_bms_error
Convert a luars LuaError into a BMS InteropError using the VM’s stored message.