Feature: Async Pathfinding Workers and Queue Bound

This feature expands pathfinding throughput with additional async workers and optional queue bounding.

Where It Lives

Main patch:

• patches/VSEssentials/Entity/Pathfinding/PathfindingAsync.cs.patch

Extra Worker Threads

The patch adds PathfindingAsyncWorker, each with its own AStar instance:

internal class PathfindingAsyncWorker : IAsyncServerSystem
{
    private readonly PathfindingAsync owner;
    public AStar Astar;

    public void OnSeparateThreadTick()
    {
        owner.ProcessQueue(Astar, 100);
    }
}

PathfindingAsync still registers the built-in thread:

api.Server.AddServerThread("ai-pathfinding", this);

Then Stratum may add more:

for (int i = 0; i < extra; i++)
{
    var worker = new PathfindingAsyncWorker(this, api);
    stratumExtraWorkers.Add(worker);
    api.Server.AddServerThread("ai-pathfinding-" + (i + 2), worker);
}

Config Bridge

The patch reflectively reads Stratum config from VintagestoryLib to avoid hard compile-time coupling from VSEssentials:

Assembly libAsm = AppDomain.CurrentDomain.GetAssemblies().FirstOrDefault(a => a.GetName().Name == "VintagestoryLib");
Type runtimeT = libAsm?.GetType("Vintagestory.Server.StratumRuntime");
object cfg = runtimeT?.GetProperty("Config", BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Static)?.GetValue(null);

From Performance.Pathfinding, it reads:

• Async
• WorkerThreads
• MaxQueued

If WorkerThreads <= 0, it falls back to:

workers = Math.Max(2, Environment.ProcessorCount / 2);

Queue Bound

When MaxQueued > 0, the queue is bounded by dropping oldest work under sustained pressure:

if (stratumMaxQueued > 0 && PathfinderTasks.Count >= stratumMaxQueued)
{
    PathfinderTasks.TryDequeue(out _);
}
PathfinderTasks.Enqueue(task);

Behavior Summary

• Pathfinding stays async.
• The number of worker threads can scale above one.
• Queue growth can be capped to avoid unbounded backlog.

Related Files

• patches/VSEssentials/Entity/Pathfinding/PathfindingAsync.cs.patch
• VSEssentials/Entity/Pathfinding/PathfindingAsync.cs
• sources/VintagestoryLib/Vintagestory/Server/StratumConfig.cs (Performance.Pathfinding)