bevy-tokio-tasks

A simple Bevy plugin which integrates a Tokio runtime into a Bevy app.

How To

How to initialize this plugin

To initialize the plugin, simply install the TokioTasksPlugin when initializing your Bevy app. The simplest way to do this is to use the TokioTasksPlugin::default() method, which sets up a Tokio Runtime with default settings (the plugin calls Runtime::enable_all to enable Tokio's IO and timing functionality).

fn main() {
    bevy::App::new()
        .add_plugins(bevy_tokio_tasks::TokioTasksPlugin::default())
}

If you want to customize the Tokio Runtime setup, you may do so by specifying a make_runtime callback on the TokioTasksPlugin.

fn main() {
    bevy::App::new()
        .add_plugins(bevy_tokio_tasks::TokioTasksPlugin {
            make_runtime: Box::new(|| {
                let mut runtime = tokio::runtime::Builder::new_multi_thread();
                runtime.enable_all();
                runtime.build().unwrap()
            }),
            ..bevy_tokio_tasks::TokioTasksPlugin::default()
        })
}

How to spawn a background task

To spawn a background task from a Bevy system function, add a TokioTasksRuntime as a resource parameter and call the spawn_background_task function.

fn example_system(runtime: ResMut<TokioTasksRuntime>) {
    runtime.spawn_background_task(|_ctx| async move {
        println!("This task is running on a background thread");
    });
}

How to synchronize with the main thread

Often times, background tasks will need to synchronize with the main Bevy app at certain points. You may do this by calling the run_on_main_thread function on the TaskContext that is passed to each background task.

fn example_system(runtime: ResMut<TokioTasksRuntime>) {
    runtime.spawn_background_task(|mut ctx| async move {
        println!("This print executes from a background Tokio runtime thread");
        ctx.run_on_main_thread(move |ctx| {
            // The inner context gives access to a mutable Bevy World reference.
            let _world: &mut World = ctx.world;
        }).await;
    });
}

Examples

• change_clear_color - This example spawns a background task which runs forever. Every second, the background task updates the app's background clear color. This demonstrates how background tasks can synchronize with the main thread to update game state.
• current_thread_runtime - This example demonstrates how you can customize the Tokio Runtime. It configures a current_thread Runtime instead of a multi-threading Runtime.
• async_fn - Does the same thing as the change_clear_color example, except that it shows how you can pass an async fn to spawn_background_task.
• shutdown_after_sleep - This example spawns a background task which sleeps for 120 Bevy game updates, then shuts down the Bevy app.

Version Compatibility

This crate's major and minor version numbers will match Bevy's. To allow this crate to publish updates between Bevy updates, the patch version is allowed to increment independent of Bevy's release cycle.