bevy_scriptum is a a plugin for Bevy that allows you to write some of your game logic in a scripting language. Currently, only Rhai is supported, but more languages may be added in the future.
It'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: ```rust use bevy::prelude::; use bevy_scriptum::prelude::;
App::new()
.addplugins(DefaultPlugins)
.addplugins(ScriptingPlugin::default())
.addscriptfunction(String::from("hellobevy"), || {
println!("hello bevy, called from script");
});
And you can call them in your scripts like this:
rhai
hellobevy();
```
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:
```rust use bevy::prelude::; use bevy_scriptum::prelude::;
struct Player;
App::new()
.addplugins(DefaultPlugins)
.addplugins(ScriptingPlugin::default())
.addscriptfunction(
String::from("printplayernames"),
|players: Query<&Name, With
You can also pass arguments to your callback functions, just like you would in a regular Bevy system - using In structs with tuples:
```rust
use bevy::prelude::;
use bevy_scriptum::prelude::;
use rhai::ImmutableString;
App::new()
.addplugins(DefaultPlugins)
.addplugins(ScriptingPlugin::default())
.addscriptfunction(
String::from("funwithstringparam"),
|In((x,)): In<(ImmutableString,)>| {
println!("called with string: '{}'", x);
},
);
which you can then call in your script like this:
rhai
funwithstringparam("Hello world!");
```
Add the following to your Cargo.toml:
toml
[dependencies]
bevy_scriptum = "0.2"
or execute cargo add bevy_scriptum from your project directory.
Add the following to your main.rs:
```rust use bevy::prelude::; use bevy_scriptum::prelude::;
App::new() .addplugins(DefaultPlugins) .addplugins(ScriptingPlugin::default()) .run(); ```
You can now start exposing functions to the scripting language. For example, you can expose a function that prints a message to the console:
```rust use rhai::ImmutableString; use bevy::prelude::; use bevy_scriptum::prelude::;
App::new() .addplugins(DefaultPlugins) .addplugins(ScriptingPlugin::default()) .addscriptfunction( String::from("myprint"), |In((x,)): In<(ImmutableString,)>| { println!("myprint: '{}'", x); }, ); ```
Then you can create a script file in assets directory called script.rhai that calls this function:
rhai
my_print("Hello world!");
And spawn a Script component with a handle to a script source file`:
```rust use bevy::prelude::*; use bevy_scriptum::Script;
App::new()
.addsystems(Startup,|mut commands: Commands, assetserver: Res
You can also try running provided examples by cloning this repository and running cargo run --example <example_name>. For example:
bash
cargo run --example hello_world
The examples live in examples directory and their corresponding scripts live in assets/examples directory within the repository.
| bevy version | bevy_scriptum version | |--------------|----------------------| | 0.11 | 0.2 | | 0.10 | 0.1 |
Every function called from script returns a promise that you can call .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:
rhai
get_player_name().then(|name| {
print(name);
});
A variable called entity is automatically available to all scripts - it represents bevy entity that the Script component is attached to.
It exposes .index() method that returns bevy entity index.
It is useful for accessing entity's components from scripts.
It can be used in the following way:
rhai
print("Current entity index: " + entity.index());
Contributions are welcome! Feel free to open an issue or submit a pull request.
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)