bevy_scriptum 📜

bevy_scriptum is a a plugin for Bevy that allows you to write some of your game logic in a scripting language. Currently Rhai and Lua are supported, but more languages may be added in the future.

API docs are available in docs.rs

bevy_scriptum's main advantages include:

  • low-boilerplate
  • easy to use
  • asynchronicity with a promise-based API
  • flexibility
  • hot-reloading

Scripts are separate files that can be hot-reloaded at runtime. This allows you to quickly iterate on your game logic without having to recompile your game.

All you need to do is register callbacks on your Bevy app like this:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("hello_bevy"), || {
               println!("hello bevy, called from script");
             });
        })
        .run();
}

And you can call them in your scripts like this:

hello_bevy()

Every callback function that you expose to the scripting language is also a Bevy system, so you can easily query and mutate ECS components and resources just like you would in a regular Bevy system:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

#[derive(Component)]
struct Player;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
            runtime.add_function(
                String::from("print_player_names"),
                |players: Query<&Name, With<Player>>| {
                    for player in &players {
                        println!("player name: {}", player);
                    }
                },
            );
        })
        .run();
}

You can also pass arguments to your callback functions, just like you would in a regular Bevy system - using In structs with tuples:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
            runtime.add_function(
                String::from("fun_with_string_param"),
                |In((x,)): In<(String,)>| {
                    println!("called with string: '{}'", x);
                },
            );
        })
        .run();
}

which you can then call in your script like this:

fun_with_string_param("Hello world!")

It is also possible to split the definition of your callback functions up over multiple plugins. This enables you to split up your code by subject and keep the main initialization light and clean. This can be accomplished by using add_scripting_api. Be careful though, add_scripting has to be called before adding plugins.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

struct MyPlugin;
impl Plugin for MyPlugin {
    fn build(&self, app: &mut App) {
        app.add_scripting_api::<LuaRuntime>(|runtime| {
            runtime.add_function(String::from("hello_from_my_plugin"), || {
                info!("Hello from MyPlugin");
            });
        });
    }
}

// Main
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|_| {
            // nice and clean
        })
        .add_plugins(MyPlugin)
        .run();
}

Usage

Add the following to your Cargo.toml:

[dependencies]
bevy_scriptum = { version = "0.8", features = ["lua"] }

or execute cargo add bevy_scriptum --features lua from your project directory.

You can now start exposing functions to the scripting language. For example, you can expose a function that prints a message to the console:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
           runtime.add_function(
               String::from("my_print"),
               |In((x,)): In<(String,)>| {
                   println!("my_print: '{}'", x);
               },
           );
        })
        .run();
}

Then you can create a script file in assets directory called script.lua that calls this function:

my_print("Hello world!")

And spawn an entity with attached Script component with a handle to a script source file:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
           runtime.add_function(
               String::from("my_print"),
               |In((x,)): In<(String,)>| {
                   println!("my_print: '{}'", x);
               },
           );
        })
        .add_systems(Startup,|mut commands: Commands, asset_server: Res<AssetServer>| {
            commands.spawn(Script::<LuaScript>::new(asset_server.load("script.lua")));
        })
        .run();
}

You should then see my_print: 'Hello world!' printed in your console.

Provided examples

You can also try running provided examples by cloning this repository and running cargo run --example <example_name>_<language_name>. For example:

cargo run --example hello_world_lua

The examples live in examples directory and their corresponding scripts live in assets/examples directory within the repository.

Promises - getting return values from scripts

Every function called from script returns a promise that you can call :and_then with a callback function on. This callback function will be called when the promise is resolved, and will be passed the return value of the function called from script. For example:

get_player_name():and_then(function(name)
    print(name)
end)

which will print out John when used with following exposed function:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
       .add_plugins(DefaultPlugins)
       .add_scripting::<LuaRuntime>(|runtime| {
               runtime.add_function(String::from("get_player_name"), || String::from("John"));
       });
}

Access entity from script

A variable called entity is automatically available to all scripts - it represents bevy entity that the Script component is attached to. It exposes index property that returns bevy entity index. It is useful for accessing entity's components from scripts. It can be used in the following way:

print("Current entity index: " .. entity.index)

entity variable is currently not available within promise callbacks.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

License

bevy_scriptum is licensed under either of the following, at your option: Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Runtimes

This chapter demonstrates how to work with bevy_scriptum when using a specific runtime.

Lua

This chapter demonstrates how to work with bevy_scriptum when using Lua language runtime.

Installation

Add the following to your Cargo.toml:

[dependencies]
bevy = "0.16"
bevy_scriptum = { version = "0.8", features = ["lua"] }

If you need a different version of bevy you need to use a matching bevy_scriptum version according to the bevy support matrix

Hello World

After you are done installing the required crates, you can start developing your first game or application using bevy_scriptum.

To start using the library you need to first import some structs and traits with Rust use statements.

For convenience there is a main "prelude" module provided called bevy_scriptum::prelude and a prelude for each runtime you have enabled as a create feature.

You can now start exposing functions to the scripting language. For example, you can expose a function that prints a message to the console:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
           runtime.add_function(
               String::from("my_print"),
               |In((x,)): In<(String,)>| {
                   println!("my_print: '{}'", x);
               },
           );
        })
        .run();
}

Then you can create a script file in assets directory called script.lua that calls this function:

my_print("Hello world!")

And spawn an entity with attached Script component with a handle to a script source file:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
           runtime.add_function(
               String::from("my_print"),
               |In((x,)): In<(String,)>| {
                   println!("my_print: '{}'", x);
               },
           );
        })
        .add_systems(Startup,|mut commands: Commands, asset_server: Res<AssetServer>| {
            commands.spawn(Script::<LuaScript>::new(asset_server.load("script.lua")));
        })
        .run();
}

You should then see my_print: 'Hello world!' printed in your console.

Spawning scripts

To spawn a Lua script you will need to get a handle to a script asset using bevy's AssetServer.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn my_spawner(mut commands: Commands, assets_server: Res<AssetServer>) {
    commands.spawn(Script::<LuaScript>::new(
        assets_server.load("my_script.lua"),
    ));
}

fn main() {}

After they scripts have been evaled by bevy_scriptum, the entities that they've been attached to will get the Script::<LuaScript> component stripped and instead LuaScriptData component will be attached.

So to query scipted entities you could do something like:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn my_system(
    mut scripted_entities: Query<(Entity, &mut LuaScriptData)>,
) {
    for (entity, mut script_data) in &mut scripted_entities {
        // do something with scripted entities
    }
}

fn main() {}

Calling Rust from Lua

To call a rust function from Lua first you need to register a function within Rust using builder pattern.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
            // `runtime` is a builder that you can use to register functions
        })
        .run();
}

For example to register a function called my_rust_func you can do the following:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("my_rust_func"), || {
               println!("my_rust_func has been called");
             });
        })
        .run();
}

After you do that the function will be available to Lua code in your spawned scripts.

my_rust_func()

Registered functions can also take parameters. A parameter can be any type that implements FromLua.

Since a registered callback function is a Bevy system, the parameters are passed to it as In struct with tuple, which has to be the first parameter of the closure.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("func_with_params"), |args: In<(String, i64)>| {
               println!("my_rust_func has been called with string {} and i64 {}", args.0.0, args.0.1);
             });
        })
        .run();
}

To make it look nicer you can destructure the In struct.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("func_with_params"), |In((a, b)): In<(String, i64)>| {
               println!("my_rust_func has been called with string {} and i64 {}", a, b);
             });
        })
        .run();
}

The above function can be called from Lua

func_with_params("abc", 123)

Return value via promise

Any registered rust function that returns a value will retrurn a promise when called within a script. By calling :and_then on the promise you can register a callback that will receive the value returned from Rust function.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("returns_value"), || {
                123
             });
        })
        .run();
}
returns_value():and_then(function (value)
    print(value) -- 123
end)

Calling Lua from Rust

To call a function defined in Lua

function on_update()
end

We need to acquire LuaRuntime resource within a bevy system. Then we will be able to call call_fn on it, providing the name of the function to call, LuaScriptData that has been automatically attached to entity after an entity with script attached has been spawned and its script evaluated, the entity and optionally some arguments.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn call_lua_on_update_from_rust(
    mut scripted_entities: Query<(Entity, &mut LuaScriptData)>,
    scripting_runtime: ResMut<LuaRuntime>,
) {
    for (entity, mut script_data) in &mut scripted_entities {
        // calling function named `on_update` defined in lua script
        scripting_runtime
            .call_fn("on_update", &mut script_data, entity, ())
            .unwrap();
    }
}

fn main() {}

We can also pass some arguments by providing a tuple or Vec as the last call_fn argument.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn call_lua_on_update_from_rust(
    mut scripted_entities: Query<(Entity, &mut LuaScriptData)>,
    scripting_runtime: ResMut<LuaRuntime>,
) {
    for (entity, mut script_data) in &mut scripted_entities {
        scripting_runtime
            .call_fn("on_update", &mut script_data, entity, (123, String::from("hello")))
            .unwrap();
    }
}

fn main() {}

They will be passed to on_update Lua function

function on_update(a, b)
    print(a) -- 123
    print(b) -- hello
end

Any type that implements IntoLua can be passed as an argument withing the tuple in call_fn.

Interacting with bevy in callbacks

Every registered function is also just a regular Bevy system.

That allows you to do anything you would do in a Bevy system.

You could for example create a callback system function that prints names of all entities with Player component.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

#[derive(Component)]
struct Player;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
            runtime.add_function(
                String::from("print_player_names"),
                |players: Query<&Name, With<Player>>| {
                    for player in &players {
                        println!("player name: {}", player);
                    }
                },
            );
        })
        .run();
}

In script:

print_player_names()

You can use functions that interact with Bevy entities and resources and take arguments at the same time. It could be used for example to mutate a component.

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

#[derive(Component)]
struct Player {
    health: i32
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
            runtime.add_function(
                String::from("hurt_player"),
                |In((hit_value,)): In<(i32,)>, mut players: Query<&mut Player>| {
                    let mut player = players.single_mut();
                    player.health -= hit_value;
                },
            );
        })
        .run();
}

And it could be called in script like:

hurt_player(5)

Builtin types

bevy_scriptum provides following types that can be used in Lua:

  • Vec3
  • BevyEntity

Vec3

Constructor

Vec3(x: number, y: number, z: number)

Properties

  • x: number
  • y: number
  • z: number

Example Lua usage

my_vec = Vec3(1, 2, 3)
set_translation(entity, my_vec)

Example Rust usage

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("set_translation"), set_translation);
        })
        .run();
}

fn set_translation(
    In((entity, translation)): In<(BevyEntity, BevyVec3)>,
    mut entities: Query<&mut Transform>,
) {
    let mut transform = entities.get_mut(entity.0).unwrap();
    transform.translation = translation.0;
}

BevyEntity

Constructor

None - instances can only be acquired by using built-in entity global variable.

Properties

  • index: integer

Example Lua usage

print(entity.index)
pass_to_rust(entity)

Example Rust usage

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|runtime| {
             runtime.add_function(String::from("pass_to_rust"), |In((entity,)): In<(BevyEntity,)>| {
               println!("pass_to_rust called with entity: {:?}", entity);
             });
        })
        .run();
}

Builtin variables

entity

A variable called entity is automatically available to all scripts - it represents bevy entity that the Script component is attached to. It exposes index property that returns bevy entity index. It is useful for accessing entity's components from scripts. It can be used in the following way:

print("Current entity index: " .. entity.index)

entity variable is currently not available within promise callbacks.

Rhai

This chapter demonstrates how to work with bevy_scriptum when using Rhai language runtime.

Installation

Add the following to your Cargo.toml:

[dependencies]
bevy = "0.16"
bevy_scriptum = { version = "0.8", features = ["rhai"] }

If you need a different version of bevy you need to use a matching bevy_scriptum version according to the bevy support matrix

Workflow

Demonstration of useful approaches when working with bevy_scriptum.

Live-reload

Bevy included support

To enable live reload it should be enough to enable file-watcher feature within bevy dependency in Cargo.toml

bevy = { version = "0.16", features = ["file_watcher"] }

Init-teardown pattern for game development

It is useful to structure your game in a way that would allow making changes to the scripting code without restarting the game.

A useful pattern is to hava three functions "init", "update" and "teardown".

  • "init" function will take care of starting the game(spawning the player, the level etc)

  • "update" function will run the main game logic

  • "teardown" function will despawn all the entities so game starts at fresh state.

This pattern is very easy to implement in bevy_scriptum. All you need is to define all needed functions in script:

player = {
    entity = nil
}

-- spawning all needed entities
local function init()
	player.entity = spawn_player()
end

-- game logic here, should be called in a bevy system using call_fn
local function update()
    (...)
end

-- despawning entities and possible other cleanup logic needed
local function teardown()
	despawn(player.entity)
end

-- call init to start the game, this will be called on each file-watcher script
-- reload
init()

The function calls can be implemented on Rust side the following way:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;
use bevy_scriptum::runtimes::lua::BevyVec3;

fn init(mut commands: Commands, assets_server: Res<AssetServer>) {
    commands.spawn(Script::<LuaScript>::new(
        assets_server.load("scripts/game.lua"),
    ));
}


fn update(
    mut scripted_entities: Query<(Entity, &mut LuaScriptData)>,
    scripting_runtime: ResMut<LuaRuntime>,
) {
    for (entity, mut script_data) in &mut scripted_entities {
        scripting_runtime
            .call_fn("update", &mut script_data, entity, ())
            .unwrap();
    }
}


fn teardown(
    mut ev_asset: EventReader<AssetEvent<LuaScript>>,
    scripting_runtime: ResMut<LuaRuntime>,
    mut scripted_entities: Query<(Entity, &mut LuaScriptData)>,
) {
    for event in ev_asset.read() {
        if let AssetEvent::Modified { .. } = event {
            for (entity, mut script_data) in &mut scripted_entities {
                scripting_runtime
                    .call_fn("teardown", &mut script_data, entity, ())
                    .unwrap();
            }
        }
    }
}

fn main() {}

And to tie this all together we do the following:

use bevy::prelude::*;
use bevy_scriptum::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_scripting::<LuaRuntime>(|builder| {
            builder
                .add_function(String::from("spawn_player"), spawn_player)
                .add_function(String::from("despawn"), despawn);
        })
        .add_systems(Startup, init)
        .add_systems(Update, (update, teardown))
        .run();
}

fn init() {} // Implemented elsewhere
fn update() {} // Implemented elsewhere
fn despawn() {} // Implemented elsewhere
fn teardown() {} // Implemented elsewhere
fn spawn_player() {} // Implemented elsewhere

despawn can be implemented as:

use bevy::prelude::*;
use bevy_scriptum::runtimes::lua::prelude::*;

fn despawn(In((entity,)): In<(BevyEntity,)>, mut commands: Commands) {
    commands.entity(entity.0).despawn();
}

fn main() {} // Implemented elsewhere

Implementation of spawn_player has been left out as an exercise for the reader.

Bevy support matrix

bevy versionbevy_scriptum version
0.160.8
0.150.7
0.140.6
0.130.4-0.5
0.120.3
0.110.2
0.100.1