Crate bevy_coroutine

Bevy Coroutine

A simple Bevy library to run coroutines similar to Unity’s coroutines.
Bevy Coroutine is very experimental and new versions may contain breaking changes !

Usage

The main motivation behind Bevy Coroutine is to allows you to spread the execution of a system across several frames. It also helps with managing and running systems in sequence over time.

use bevy::prelude::*;
use bevy_coroutine::prelude::*;

fn startup_system(mut commands: Commands) {
	// Launch the coroutine from a system
	commands.queue(Coroutine::new(my_coroutine));
}

fn my_coroutine(

) -> CoResult {
	let mut res = co_break();
	// Print number from 0 to 3, printing a single number every second
	for i in 0..=3 {
		res.add_subroutines((
			wait(std::time::Duration::from_secs(1)),
			with_input(i, print_number),
		));
	}
	res
}

fn print_number(
	In(i): In<u32>,
) -> CoResult {
	println!("{i}");
	co_break()
}

Coroutines are systems. They can access any system parameter like Query and Res.
Coroutines don’t use a ‘yield’ statement but instead return a CoResult. The CoResult indicates if the coroutine should ‘break’ and stops its execution or ‘continue’ and be executed again at the next update. In addition, a coroutine can run other coroutines and wait for their completion by adding them as subroutines to the CoResult.

The state of execution of your coroutine can be stored between frames using Locals as parameters in the coroutine system.

use bevy::prelude::*;
use bevy_coroutine::prelude::*;

fn my_coroutine(
	mut i: Local<u32>,
) -> CoResult {
	if *i <= 3
	{
		println!("{}", *i);
		*i += 1;
		return co_continue(); // Rerun the system next frame
	}
	co_break()
}

Performance

Each coroutine run in an exclusive system. They won’t run in parallel with each other nor with other bevy systems.
For CPU intensive tasks, consider using bevy_tasks or bevy_defer.

Versions

bevy	bevy_coroutine
0.16	0.3.0
0.15	0.2.0
0.14	0.1.3
0.14	0.1.2
0.14	0.1.1
0.14.0-rc.4	0.1.0

Modules

prelude

use bevy_coroutine::prelude::*; to import the plugin, essential types and utility functions.

Structs

CoResult

The result of a coroutine resumption.

Coroutine

Command that launches a coroutine.

CoroutinePlugin

Plugin to enable bevy_coroutine in your App.

CoroutineUpdateSystem

The SystemSet for the system that updates coroutines.

Traits

IntoCoroutines

Conversion trait to turn something into a sequence of BoxedCoroutine.

Functions

co_break

Stops the execution of the current coroutine.

co_continue

Rerun the current coroutine next update.

launch_coroutine

Returns a system that launches the given coroutine when executed.

wait

Generates a coroutine system that waits for the given duration then breaks

wait_real_time

Generates a coroutine system that waits for the given real time duration then breaks

wait_until

Generates a coroutine system that waits until the given system returns true then breaks

wait_while

Generates a coroutine system that waits while the given system returns true then breaks

with_input

Generates a system that executes the given system with the given input

Type Aliases

BoxedCoroutine

A type alias for a boxed system that can be used in a coroutine.