How to Use Paper Async Pathfinding
Enable and configure Paper's async pathfinding to offload mob navigation from the main thread and improve TPS.
What Is Async Pathfinding?
Pathfinding is the process mobs use to navigate around obstacles, find players, and reach their targets. In vanilla Minecraft, all pathfinding runs on the main server thread, competing with every other task for that 50 ms tick budget. Paper async pathfinding minecraft feature moves this work to separate threads, freeing the main thread to handle other game logic.
Why It Matters
On a server with hundreds of mobs, pathfinding can consume 10 to 30% of each tick. Villagers are particularly expensive because they constantly recalculate paths to workstations, beds, and points of interest. Zombies pathfinding toward villagers, skeletons navigating around obstacles, and pillagers during raids all add up. Paper async pathfinding minecraft offloads this entire calculation to worker threads.
How to Enable It
In paper-global.yml, find the async chunks and pathfinding section:
misc:
async-pathfinding:
enabled: true
max-threads: 2
Set enabled to true. The max-threads value controls how many CPU threads Paper dedicates to pathfinding. For most servers, 2 is a good starting point. Servers with 50+ players and high mob counts can benefit from 3 or 4.
Thread Count Guidelines
| Server Size | Recommended Threads |
|---|---|
| Small (1-20 players) | 1-2 |
| Medium (20-50 players) | 2-3 |
| Large (50+ players) | 3-4 |
Do not set this higher than the number of available CPU cores minus 2. The main thread and chunk loading also need cores. Over-allocating pathfinding threads can cause contention.
Compatibility
Paper async pathfinding minecraft works with the vast majority of plugins. Since pathfinding is an internal server operation, plugins that interact with mob behavior through the Bukkit API are unaffected. However, plugins that directly manipulate NMS pathfinding classes could conflict. Test after enabling and check your console for errors.
This feature requires Paper 1.19 or later. If you are running an older version, consider updating to take advantage of this and many other improvements.
Measuring the Improvement
Before enabling, run a Spark profile and note the time spent in pathfinding-related methods. After enabling, run another profile under similar conditions. You should see pathfinding disappear from the main thread's top entries, replaced by faster mob tick times.
On our test server with 80 villagers and 200 hostile mobs, enabling paper async pathfinding minecraft reduced main-thread entity tick time by 22%.
Need a server built for performance? Astroworld Hosting runs NVMe SSDs with optimized Paper configs on every plan.
Pairing with Other Optimizations
- Reduce mob caps if pathfinding is still heavy. See mob cap explained.
- Use entity activation range to skip pathfinding for distant mobs.
- Limit villager counts per village to reduce POI scanning.
- Combine with entity lag reduction for maximum effect.