`SwarmBuilder`: support for multi-threaded execution

[bystepii]

Question

Currently, SwarmBuilder uses tokio::task::LocalSet to ensure state consistency across bot handlers. However, this prevents the swarm from utilizing multiple CPU cores, causing single-threaded bottlenecks at ~100 bots.

Is there a possibility to support multi-threaded swarms while maintaining the correctness guarantees?

Context

When running 200+ bots with the current architecture:

• All handlers run in a single LocalSet (single thread)
• CPU usage caps at 100% on one core, even with tokio::runtime::Builder::new_multi_thread()
• Only solution is spawning multiple bot-rust processes (not ideal for unified management)

I understand from the docs that spawn_local is used to guarantee state consistency:

"If you spawn a task with tokio::spawn and move your bot into it, it's possible for Tokio to run the handler function or schedule a Minecraft tick at an unexpected moment."

Questions

1. Could per-bot isolation reduce this concern? If each bot's handler runs on its own dedicated thread (via tokio::spawn_blocking or similar), would the state consistency guarantee hold for that individual bot?

2. Partial multi-threading? Could the ECS tick schedule remain single-threaded while handler async tasks run on the multi-threaded pool?

3. Is this a known limitation? Are there plans to address swarm scaling beyond the single-threaded pattern?

References

• https://azalea.matdoes.dev/azalea/#using-tokiotaskspawn_local-instead-of-tokiospawn
• Swarm builder: https://github.com/azalea-rs/azalea/blob/main/azalea/src/swarm/builder.rs#L565-L603

[mat-1]

Thanks for the issue. :)

With the way swarms work, having the handler function be called on separate threads would be a source of too many problems for users, and the handler function is almost never actually the bottleneck. The ECS (which handles ticking), on the other hand, is generally much heavier but can (and does) run partially in parallel, though not as well as it could.

If the bottleneck is in your handler function, then the solution is fairly easy -- you could just optimize your code or move the heavy parts into separate tasks/threads. Alternatively, you could refactor your bot to work as an Azalea plugin.

As for the ECS, Bevy does run it partially in parallel (by running non-conflicting systems at the same time -- aka external parallelism), but it won't scale up infinitely with CPU cores. Bevy also has a way to do "internal parallelism" for individual systems by using par_iter but Azalea doesn't currently take advantage of this because it's never been necessary.

If you're interested in trying to fixing this, I'd recommend first profiling your program to find where most of the time is being spent (using cargo-flamegraph or similar). Then, you can decide where the optimizations should actually be applied.

[bystepii]

Just to clarify: I’m not using handler functions at all — my bot behavior runs as ECS systems.

I don't think the reason the swarm saturates one core isn’t that a handler is “heavy”.

Here’s a high-level sketch of what my bot does:

fn simple_walk_task_system(
    mut query: Query<(&BotClient, &mut Task, &Position)>,
) {
    for (bot_client, task, pos) in query.iter_mut() {
        // determine if we should update movement (every few secconds)
        if should_update() {
            let (yaw, should_jump) = compute_next_target(pos, &task);

            // issue movement commands asynchronously
            let bot = bot_client.clone();
            tokio::spawn(async move {
                bot.set_direction(yaw);
                bot.set_jumping(should_jump);
                bot.walk_forward();
            });

            update_task_state(task);
        }
    }
}

Even though the actual movement logic is light, all of these spawn_local tasks get run on one core because the whole swarm is driven inside a LocalSet that never leaves a single thread.