If you ever played a mid-big modpack with good optimization and performance mods you might have noticed that sometimes no matter what there seems to be lag spikes mostly around mobs (specifically villagers) if you have a not so great pc like me or sometimes even with a good machine, this bottleneck is the reason Pathfinder exists because a huge deal of long entity ticks are sometimes from vanilla pathfinding calculations and due to a lack of not many mods directly tackling this persistent. Below is a list of what the mod does.

1. Chunk-Aware Cache Invalidation

When a block changes, Pathfinder drops every cached path whose target sits in that chunk. A mixin on Level.setBlock computes the chunk coords (pos >> 4) on each successful block change, then calls PathResultCache.invalidateChunk. A secondary index (Map<ChunkKey, Set<CacheKey>>) keeps the lookup O(k), where k is the number of cached entries in that chunk. Usually 0–5. Without this, cached paths go stale whenever terrain changes (a door closes, a block gets placed). With proactive invalidation, longer TTLs are safe, because the cache is always fresh.

2. Unreachable Target Cache

When A* fails to reach a target, Pathfinder marks that target as unreachable for 10 seconds. Any mob trying to reach it during that window gets an instant null, no A* runs. Failures are stored under a global key (dimension, mobId=0, target), and lookups check this global tier before the per-mob tier. Failed searches are the most expensive pathfinds, because they walk the entire search region (~800 nodes) before giving up. In villages with walls or locked doors, villagers constantly try to reach POIs they can’t actually get to, and each attempt costs 1–5ms. This cache kills the retry storm.

3. Distance-Based Level of Detail (LOD)

Mobs far from every player (default 48+ blocks) get a reduced recompute rate. Nearby mobs stay fully responsive. LODManager.shouldApplyLOD checks nearestPlayerDistSq > 48². When LOD applies and a mob has an active path, a per-navigation counter increments. recomputePath is cancelled unless the counter hits lod.tickInterval (default 15 ticks). A villager 60 blocks from any player doesn’t need to re-evaluate its path every 20 ticks. Nobody is watching. Spacing out recomputes saves CPU with no visible difference.

4. Per-Mob Path Cache

When a mob completes a path to a target, that path is cached. If the same mob pathfinds to the same target again within 30 seconds, the cached path is returned instantly. The cache key is (dimension, mobId, target). Villagers re-pathfind to their workstation or bed all the time, same source, same destination. On a cache hit, createPath returns early without running A*. This saves 1–5ms per repeated pathfind, which is common in villages where villagers follow daily routines.

5. Search Depth Limiter

Caps the maximum nodes A* can visit per pathfind (default 400). Vanilla computes node budget as followRange × 16 × maxVisitedNodesMultiplier. If that exceeds the configured cap, Pathfinder clamps maxVisitedNodesMultiplier so the effective budget equals the cap. This happens in createPath HEAD before A* starts, most successful villager paths complete in 200–300 nodes. Failed paths can visit 800+. Capping at 400 makes failures fail about 2x faster with minimal impact on success rate.

6. Recomputation Cooldown

After a failed pathfind, wait longer before retrying. Default 60 ticks, vanilla is 20. In recomputePath HEAD, if this.path is null (previous path failed) and gameTime - timeLastRecompute < cooldownTicks, the recompute is cancelled. Vanilla retries failed pathfinds every second. If a villager can’t reach a bed because a door is closed, retrying every second is wasted CPU.

7. Pathfinding Throttle

Limits how many path computations can run per server tick. Default 4. A static counter (PathThrottle.pathfindsThisTick) increments on each pathfind attempt. If it exceeds the limit, createPath returns null and the pathfind is deferred to the next tick. The counter resets every server tick via ServerTickEvent.Post. At dawn, when 20 villagers all pathfind to their workstations at once, the server thread can stall for many milliseconds. The throttle spreads this across 5 ticks and keeps TPS stable.

8. Brain Tick Reduction

Skips Brain.tick for idle mobs every 4th tick. That’s a 75% reduction. Navigation is unaffected, mobs still move. A mixin injects at Brain.tick HEAD. SimpleTickReducer.shouldSkipTick checks: is the feature enabled? Is the mob urgent? Is mob.tickCount % 4 != 0? Is the activity IDLE or REST? If all pass, the brain tick is cancelled. Brain.tick runs memory expiry, sensor updates, and behavior scheduling. For idle villagers, most of this produces no visible change. Skipping 3 of every 4 ticks saves real CPU.

9. Urgency Bypass

Mobs in combat (have a target, or were recently hurt) skip every other optimization. Full-rate pathfinding, full-rate brain ticks, no throttle, no depth cap. LODManager.isUrgent checks two fields: mob.getTarget() and mob.getLastHurtByMob(). That’s cheaper than checking Activity (which needs a brain lookup), and more correct. A WORK-activity mob that just got attacked should still pathfind at full rate.

What does this all mean?: well vanilla pathfinding cores are preserved meaning this mod should not break vanilla and other modded entities, and as for the optimization part these changes tackles mostly the "worse" ticks pathfinding can create, in terms of fps for example this means overall fps might not see a huge gain, most cases just 2-4 fps increase, but in the lowest percentile of the lowest drops the 99% percentile there is a big difference in real scenarios like a modded village with bad terrain generation and lots of villagers and guard villagers compared to vanilla the 99% fps can get a difference of +10-15fps so instead of huge raw fps and TPS increase there is a smoother more stable experience with better MSPT and less villager ticking overall.

Credits

Three main features of this mod took heavy inspiration from Pathwright, a recent pathfinding optimization for Minecraft 26.1.2 mod, specifically the Path Result Caching, Urgency Bypass and Pathfinding LOD which are also implemented here.

Path finder