Best Practices for Communicating Between Bevy ECS and JavaScript: Events and Global Mutex?

[bennobuilder]

👋 Hello everyone,
I'm exploring how to efficiently communicate between the Bevy ECS and the outside world (Javascript in this case).
I'm interested in passing events both ways -> getting events from the Javascript layer into the ECS,
and also emitting events from the ECS to the Javascript layer.

In my current implementation I use a global Mutex<Vec<JsEvent>>, like so:

pub static JS_EVENT_QUEUE: Mutex<Vec<JsEvent>> = Mutex::new(Vec::new());

And then draining this queue in a wasm-bound function.

But I was wondering whether there is a "better" way
or what the recommended way to make such communication happen is?

Thanks for any insights :)

use bevy_ecs::system::Resource;
use serde::Serialize;
use std::sync::Mutex;
use wasm_bindgen::{prelude::*, JsValue};

// Static JS_EVENT_QUEUE serves as a global state to hold events for JS execution.
// We use a Mutex for safe concurrent modification. This way, events can be added to
// the queue from multiple parts of the Rust code, and later polled and drained for JS handling.
pub static JS_EVENT_QUEUE: Mutex<Vec<JsEvent>> = Mutex::new(Vec::new());

#[derive(Debug, Serialize, Clone)]
pub enum JsEvent {
    SomeEvent(String),
}

#[derive(Resource, Default, Debug)]
pub struct JsEventQueue;

impl JsEventQueue {
    pub fn push_event(&mut self, event: JsEvent) {
        let mut js_event_queue = JS_EVENT_QUEUE.lock().unwrap();
        js_event_queue.push(event);
    }
}

#[wasm_bindgen]
pub fn poll_js_event_queue() -> JsValue {
    let mut event_queue = JS_EVENT_QUEUE.lock().unwrap();
    let events = event_queue.drain(..).collect::<Vec<_>>();
    return serde_wasm_bindgen::to_value(&events).unwrap();
}

[SIGSTACKFAULT]

i've been working on this same problem. I haven't found a better way to communicate from JavaScript to Rust, but a bevy system can call a JS function just fine. here's some code from my actual project (permalink)

// with the way vite-plugin-wasm-pack works, modules are relative to the js project root (i.e., next to package.json)
#[wasm_bindgen(raw_module = "./src/vtt/renderer_interface")]
extern "C" {
    pub fn get_ships() -> Option<Vec<ShipObject>>;
    pub fn get_ship(uuid: String) -> Option<ShipObject>;
    pub fn update_primary_selection(uuid: String);
}

/// handle clicks on ships and set their `selected` field
pub fn handle_ship_click(
    //
    mut click: EventReader<GridClickInside>,
    mut ships: Query<(&mut Ship, &GridTransform)>,
    kb: Res<Input<KeyCode>>,
) {
    if kb.pressed(KeyCode::Q) {
        // clicking while holding Q
        // another system handles burn-changing
        return;
    }
    for event in click.iter() {
        for (mut ship, trans) in ships.iter_mut() {
            if trans.hex == event.location {
                info!("clicked on ship at {:?}", event);
                ship.selected = !ship.selected;
                if ship.selected {
                    update_primary_selection(ship.uuid.to_string());
                }
                break;
            }
        }
    }
}

[bennobuilder]

Thanks for the insights :)

Initially, I attempted to utilize callbacks directly within the ECS. However, I encountered a roadblock because Rust's implementation of a Javascript Function is not thread-safe (*mut u8 cannot be shared between threads safely). Since Bevy requires Resource types to be thread-safe, implementing the + Send + Sync + 'static traits, I was stuck in a loop for a while.

    pub fn add_js_callback(&mut self, js_callback: Function) {
        let callback = Box::new(|event: RenderEvent| {
            let this = JsValue::null();
            if let Ok(event_str) = serde_json::to_string(&event) {
                let js_event = JsValue::from(event_str);
                // let _ = js_callback.call1(&this, &js_event); // TODO: `*mut u8` cannot be shared between threads safely
            }
        }) as Box<dyn Fn(RenderEvent) + Send + Sync + 'static>;

        self.add_callback(callback);
    }

However, your method illuminated a more straightforward approach. Rather than registering callbacks within the ECS or creating a Mutex queue, I can call JavaScript functions directly from my systems and manage the callbacks on the JavaScript side.

use bevy_ecs::system::Resource;
use serde::Serialize;
use wasm_bindgen::{prelude::*, JsValue};

#[wasm_bindgen(raw_module = "./xyz")]
extern "C" {
    pub fn handle_js_event(js_event: JsValue);
}

#[derive(Debug, Serialize, Clone)]
pub enum JsEvent {
    SomeEvent(String),
}

#[derive(Resource, Default, Debug)]
pub struct JsEventHandler;

impl JsEventHandler {
    pub fn push_event(&mut self, event: JsEvent) {
        let js_value = serde_wasm_bindgen::to_value(&event).unwrap();
        handle_js_event(js_value);
    }
}

And regarding receiving events I could collect them on the Javascript side and then poll them each update cycle via a wasm bound Javascript function? How do you receive e.g. input events from the Javascript side?

What are your thoughts of this approach? Did you encounter problems directly integrating like wasm bound Javascript functions into the ECS?

Thanks :)

[SIGSTACKFAULT]

How do you receive e.g. input events from the Javascript side?

Haven't gotten that far. i'll probably use the queue method.

[SIGSTACKFAULT]

I'm using app.insert_resource(WinitSettings::desktop_app()); which causes the event loop to pause with no input. I've been hoping for a way to trigger a bevy update from JS (the controls for my game are partially on the webpage) but i don't think it's possible, at least not safely.

[PraxTube]

If your use case is only Bevy -> JS, than you could possibly get away with just sending a simple string over.

In my case all I want is to save some data to local storage before unload. I decided to just buffer the game state every second and write that on beforeunload. Though this of course is a very niche problem solution.

In js:

// Buffer game state
let bufferedGameState = {};
window.buffer_game_state = function(json) {
    try {
        bufferedGameState = JSON.parse(json);
    } catch (e) {
        console.error("Invalid state JSON:", e);
    }
};

// Save game before unloading the page
window.addEventListener('beforeunload', () => {
    for (const [key, value] of Object.entries(bufferedGameState)) {
        localStorage.setItem(key, value);
    }
});

and in Bevy I run the following (scheduled to run once a second in my case):

#[cfg(target_arch = "wasm32")]
#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = window)]
    fn buffer_game_state(json: &str);
}

#[cfg(target_arch = "wasm32")]
fn sync_state_to_js(
    core: Res<ProgressionCore>,
    map_data: Res<MapData>,
    q_player: Query<&Transform, With<Player>>,
) {
    let Ok(player_transform) = q_player.single() else {
        return;
    };

    let data = package_save_data(&core, &map_data, &player_transform);
    let save_data: HashMap<&&str, &String> = WASM_KEYS.iter().zip(data.iter()).collect();

    buffer_game_state(
        &serde_json::to_string(&save_data).expect("failed to parse hashmap save data to json"),
    );
}

[ryanwarfield]

I don't know how idiomatic this is (especially the read-write locks, maybe that can be improved without unsafe code), but here is my bi-directional interface using bevy_channel_trigger

static GUMBALLS_AVAILABLE_EVENT_SENDER: RwLock<Option<ChannelSender<GumballsAvailable>>> = RwLock::new(None);
static GUMBALL_DROP_EVENT_SENDER: RwLock<Option<ChannelSender<GumballDrop>>> = RwLock::new(None);

#[wasm_bindgen]
extern "C" {
    /// relays information about which ball fell
    pub fn dropped(id: u32);
}

#[derive(Event)]
pub struct GumballsAvailable(Vec<Ball>);

#[derive(Event)]
pub struct GumballDrop;

pub fn js_binding_plugin(app: &mut App) {
    let mut gumballs_available_sender = GUMBALLS_AVAILABLE_EVENT_SENDER.write().unwrap();
    let mut gumball_drop_sender = GUMBALL_DROP_EVENT_SENDER.write().unwrap();

    *gumballs_available_sender = Some(app.add_channel_trigger::<GumballsAvailable>());
    *gumball_drop_sender = Some(app.add_channel_trigger::<GumballDrop>());
}

#[wasm_bindgen]
pub fn gumballs_available(raw_gumballs: JsValue) -> Result<(), JsValue> {
    let gumballs: Vec<Ball> = serde_wasm_bindgen::from_value(raw_gumballs)?;
    GUMBALLS_AVAILABLE_EVENT_SENDER.read()
        .unwrap()
        .as_ref()
        .unwrap()
        .send(GumballsAvailable(gumballs));

    Ok(())
}

#[wasm_bindgen]
pub fn drop_gumball() {
    GUMBALL_DROP_EVENT_SENDER.read()
        .unwrap()
        .as_ref()
        .unwrap()
        .send(GumballDrop);
}