Bevy WASM

Mod your Bevy games with WebAssembly!

bevy_wasm_modding		For games
bevy_wasm_modding_sys		For mods
bevy_wasm_modding_shared		For protocols

See examples/cubes for a comprehensive example of how to use this.

Changelog

Installation

rustup add target wasm32-unknown-unknown

optional (bad installation)

cargo clean

Now, to build 2 cubes in 2 separate mods In root directory,

cargo run -p cubes

Q. So where are the mods? A. In examples/cubes/cubes/assets

Q. So did I build the .wasm to wasm32-unknown-unknown? Yes. Cubes has a build.rs that builds them into the game. If you want to build the mod yourself to test In mod_with_bevy directory,

cargo build -p mod_with_bevy --target wasm32-unknown-unknown

However, when building your game (cubes/cubes/src/main.rs) it will automatically build the mods.

Protocol

Our protocol crate defines the two message types for communicating between the game and mods.

[dependencies]

bevy_wasm_modding_shared = "0.19.2"

serde = { version = "1.0", features = ["derive"] }

use bevy_wasm_modding_shared::prelude::*;
use serde::{Deserialize, Serialize};
use bevy_ecs::message::{MessageReader, MessageWriter, Message};

/// The version of the protocol. Automatically set from the `CARGO_PKG_VERSION` environment variable.
pub const PROTOCOL_VERSION: Version = version!();

/// A message to be sent Mod -> Game.
#[derive(Message, Clone, Serialize, Deserialize, Debug)]
pub enum ModMessage {
    Hello,
}

/// A message to be sent Game -> Mod.
#[derive(Message, Clone, Serialize, Deserialize, Debug)]
pub enum GameMessage {
    HiThere,
}

Game

Our game will import WasmPlugin from bevy_wasm, and use it to automatically send and receive messages with the mods.

[dependencies]

bevy = "0.19.0"

bevy_wasm_modding = "0.19.2"

my_game_protocol = { git = "https://github.com/username/my_game_protocol" }

use bevy::{log::LogPlugin, prelude::*};
use bevy_wasm_modding::prelude::*;
use simple_protocol::{GameMessage, ModMessage, PROTOCOL_VERSION};
use bevy::ecs::message::{MessageWriter, Message, MessageReader};

fn main() {
    App::new()
        .add_plugins(LogPlugin::default())
        .add_plugins(AssetPlugin::default())
        .add_plugins(MinimalPlugins)
        .add_plugins(WasmPlugin::<GameMessage, ModMessage>::new(PROTOCOL_VERSION))
        .add_systems(Startup, insert_mods)
        .add_systems(Update, listen_for_mod_messages)
        .add_systems(Update, send_messages_to_mods)
        .run();
}

fn insert_mods(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(WasmMod {
        wasm: asset_server.load("simple_mod.wasm"),
    });
}

fn listen_for_mod_messages(mut events: MessageReader<ModMessage>) {
    for event in events.read() {
        match event {
            ModMessage::Hello => {
                info!("The mod said hello!");
            }
        }
    }
}

fn send_messages_to_mods(mut events: MessageWriter<GameMessage>) {
    events.write(GameMessage::HiThere);
}

Mod

Our mod will import FFIPlugin from bevy_wasm_modding_sys, and use it to automatically send and receive messages with the game.

[dependencies]

bevy_wasm_modding_sys = "0.19.2"

my_game_protocol = { git = "https://github.com/username/my_game_protocol" }

use bevy_wasm_modding_sys::prelude::*;
use simple_protocol::{GameMessage, ModMessage, PROTOCOL_VERSION};
use bevy_ecs::message::{MessageWriter, MessageReader};

#[allow(clippy::missing_safety_doc)]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn build_app() {
    App::new()
        .add_plugins(FFIPlugin::<GameMessage, ModMessage>::new(PROTOCOL_VERSION))
        .add_systems(Update, listen_for_game_messages)
        .add_systems(Update, send_messages_to_game)
        .run();
}

fn listen_for_game_messages(mut events: MessageReader<GameMessage>) {
    for event in events.read() {
        match event {
            GameMessage::HiThere => {
                info!("The game said hi there!");
            }
        }
    }
}

fn send_messages_to_game(mut events: MessageWriter<ModMessage>) {
    events.write(ModMessage::Hello);
}

Sharing Resources

Protocol:

#[derive(Debug, Default, Clone, Resource, Serialize, Deserialize, Reflect)]
pub struct MyCoolResource {
    pub value: u32,
    pub string: String,
}

Game:

App::new()
    ...
    .insert_resource(MyCoolResource {
        value: 0,
        string: "Hello from MyCoolResource!".to_string(),
    })
    .add_plugins(
        WasmPlugin::<HostMessage, ModMessage>::new(PROTOCOL_VERSION)
            .share_resource::<MyCoolResource>(),
    )
    .add_systems(Update, update_resource)
    ...

fn update_resource(mut my_cool_resource: ResMut<MyCoolResource>) {
    my_cool_resource.value += 1;
}

Mod:

App::new()
    ...
    .add_plugins(FFIPlugin::<HostMessage, ModMessage>::new(PROTOCOL_VERSION))
    .add_systems(Startup, startup_system)
    .add_systems(Update, print_resource_value)
    ...

fn startup_system(mut resources: ResMut<ExternResources>) {
    resources.insert::<MyCoolResource>();
}

fn print_resource_value(resource: ExternRes<MyCoolResource>) {
    info!("{:?}", resource);
}

See examples/shared_resources for a full example.

Roadmap

License

Bevy WASM modding is free, open source and permissively licensed! Except where noted (below and/or in individual files), all code in this repository is dual-licensed under either:

• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)
• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

at your option. This means you can select the license you prefer! This dual-licensing approach is the de-facto standard in the Rust ecosystem and there are very good reasons to include both.

Your contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.