NEOLearn

Tasks

Run work off the frame with NEO's task pools, poll or detach tasks, send results back over channels, and size the thread pools.

Updated October 20, 2026

On this page

Some work takes longer than a frame: generating a level, pathfinding over a big map, decoding a file. Run it as a task on one of the engine's thread pools, and the game keeps drawing while it runs. When the task finishes, you apply its result to the world.

Systems already run in parallel on these pools, so you don't need tasks for ordinary per-frame work. Use them for work that would make a frame late.

The task pools#

PoolFor
ComputeTaskPoolWork that must finish this frame. The scheduler runs systems here, and par_iter uses it.
AsyncComputeTaskPoolCPU-heavy work that may take several frames. Most of your tasks go here.
IoTaskPoolWaiting on I/O: work that spends little time actually computing. The asset server uses it.

Each pool is a global you get with ::get(). TaskPoolPlugin (in DefaultPlugins and MinimalPlugins) creates them.

Spawn a task and poll it#

spawn takes a future and returns a Task<T>. Keep the task in a component, and check it each frame with check_ready:

Rust
use neo::{
    prelude::*,
    tasks::{futures::check_ready, AsyncComputeTaskPool, Task},
};

#[derive(Component)]
struct Generating(Task<Vec<Vec3>>);

fn start(mut commands: Commands) {
    let pool = AsyncComputeTaskPool::get();
    let task = pool.spawn(async move {
        // expensive work, off the main thread
        (0..10_000).map(|i| Vec3::new(i as f32, 0.0, 0.0)).collect::<Vec<_>>()
    });
    commands.spawn(Generating(task));
}

fn finish(mut commands: Commands, mut q: Query<(Entity, &mut Generating)>) {
    for (entity, mut generating) in &mut q {
        if let Some(points) = check_ready(&mut generating.0) {
            info!("generated {} points", points.len());
            commands.entity(entity).despawn();
        }
    }
}
ItemWhat it does
pool.spawn(future)Starts the task and returns a Task<T>. Dropping the Task cancels it.
check_ready(&mut task)Returns the result once the task has finished, and None until then. Never blocks.
task.detach()Lets the task run on with nobody holding it. Use it with a channel (below).
task.is_finished()Whether the task is done.
block_on(future)Waits on the current thread. Don't use it in a system: it stalls the frame.

To change the world from a task, build a CommandQueue inside it and append it with commands.append(&mut queue) when it's ready. Example: cargo run --example async_compute.

Send results over a channel#

Instead of polling, a detached task can send its result back. Keep the receiving end in a resource and drain it each frame:

Rust
use crossbeam_channel::{Receiver, Sender};

#[derive(Resource)]
struct Results {
    sender: Sender<Vec3>,
    receiver: Receiver<Vec3>,
}

fn setup(mut commands: Commands) {
    let (sender, receiver) = crossbeam_channel::unbounded();
    commands.insert_resource(Results { sender, receiver });
}

fn start(results: Res<Results>) {
    let sender = results.sender.clone();
    AsyncComputeTaskPool::get()
        .spawn(async move {
            let _ = sender.send(Vec3::ONE);
        })
        .detach();
}

fn collect(results: Res<Results>) {
    for value in results.receiver.try_iter() {
        info!("got {value}");
    }
}

The same pattern works for a thread you start yourself, such as a network listener. Examples: cargo run --example async_channel_pattern, external_source_external_thread.

Scoped work#

ComputeTaskPool::get().scope(...) runs several tasks that borrow local data and waits for all of them. It's for splitting one job across cores inside a system:

Rust
let pool = ComputeTaskPool::get();
let sums = pool.scope(|s| {
    for chunk in data.chunks(1024) {
        s.spawn(async move { chunk.iter().sum::<f32>() });
    }
});

For iterating a query, par_iter and par_iter_mut do this for you. See Queries.

Size the pools#

By default the engine divides the machine's cores between the pools. Set your own split with TaskPoolPlugin:

Rust
App::new().add_plugins(DefaultPlugins.set(TaskPoolPlugin {
    task_pool_options: TaskPoolOptions::with_num_threads(4),
}));

On the web#

A browser build has one thread. Tasks still work, but they run on that thread between frames, so a long task makes the game stutter there. Break long work into steps, or spread it over several frames.

Next steps#