Moving 10,000 agents in Godot without the frame spike

The result, up front

One shared field moved 10,000 agents in Godot at a 5 ms median frame - 0% of frames over the 16.6 ms budget, measured on an eight-year-old desktop. The same build holds those 10,000 at 77 fps in a browser tab, pure GDScript, nothing native in the hot path. If your Godot pathfinding is slow, this is the optimization shape to look for: reduce path queries per frame before blaming the agent count.

Godot pathfinding lags with many agents when too many agents ask for a path in the same frame. I measured it. Five hundred agents, each calling AStarGrid2D.get_id_path() every physics frame, produced a median frame of 670 ms - and a worst sampled frame of 5.7 seconds. Swap those 500 per-agent queries for one shared field the whole crowd reads, and the median dropped to 2 ms, with no sampled frame over the 16.6 ms budget. Same agents, same machine, same goal.

That is roughly 330x lower median frame time for the scheduled shared-field approach in this measured setup: 670.291 ms down to 2.028 ms.

The win was not a faster solver or a clever movement trick. It was changing the shape of the work: instead of 500 agents solving nearly the same problem every frame, the scheduled version builds one piece of shared movement data over time and lets every agent read from it.

The 500-agent problem was never too many sprites moving. It was 500 repeated pathfinding queries landing in the same frame.

Benchmark setup

This is a native deterministic benchmark, not a browser timing claim. The browser demo is the visual artifact; the JSON files are the measurement source.

What counts as an agent here

An agent in this benchmark is a moving 2D unit with a position, a per-frame movement step, and a target it needs grid direction toward. Five hundred of them advance every physics frame. They are not sprites being slid along a precomputed track; each one reads the navigation data and moves itself.

The detail that makes the fix possible: they are not solving unrelated problems. They are a crowd heading toward the same goal area. When 500 units want to reach the same place, the system should not compute 500 separate answers to nearly the same question.

Why Godot pathfinding lags with many agents

Godot is not slow because 500 things exist on screen. The spike shows up when the code asks the pathfinding system to do too much repeated work inside one frame. The naive version is the one almost everyone writes first:

It is easy to write and easy to reason about, and it is the worst possible shape for a crowd that shares a goal. The cost scales with the number of agents and it all lands inside the frame budget. At 500 agents that is not a mild slowdown. It is a frame collapse.

1. Loop through every agent.
2. Ask AStarGrid2D for a path.
3. Move the agent.
4. Do it all again next frame.

The naive baseline: 500 AStarGrid2D queries per frame

AStarGrid2D is a good Godot class for grid A*. It is the right starting point for plenty of small and moderate cases, and nothing here says otherwise. The problem is not that AStarGrid2D exists. It is using it as if every agent should recompute its own full path every single frame.

Every sampled frame missed budget, and the worst one took most of six seconds. The baseline is not a recommendation. It is here because it shows the failure mode with no ambiguity.

The fix: one shared field the whole crowd reads

The scheduled version changes the model. Instead of each agent computing a path, the system keeps one shared direction field for the crowd: for each grid cell, which way to step next toward the goal. Agents read from it. When the goal moves, the field is rebuilt over several frames inside a fixed work budget, and agents keep using the last completed field until the new one is ready.

A flow field like this is not a built-in Godot feature. It is a technique you implement on top of the grid. The scheduled version does not make pathfinding free. It moves the cost out of the hottest frame and makes it predictable.

The measured result at 500 agents

At this scale, pathfinding stopped being the frame-time problem. Even the worst sampled frame, which includes a rebuild slice, came in under 10 ms - inside a 60 FPS budget with room to spare.

What the stable frame costs: rebuild latency

Nothing here is free. The scheduled version trades frame spikes for path-update latency. When the goal jumps, the new field is not ready instantly; it finishes over the next batch of frames. With this benchmark's default work budget of 1536 steps per frame, the new field takes a median of about 2.15 seconds (max 2.93 s) to fully complete after a goal move. That is field-completion latency, not frozen movement or input lag. During that window, agents follow the last completed field.

That is the real decision, not a magic setting: how fast the field refreshes versus how much frame budget it is allowed to spend. A predictable two-second path refresh is usually far easier to live with than a random multi-second stall, especially for a crowd where no single unit needs a brand-new perfect path on the same frame the goal changed.

It also tells you when this approach is wrong. If your target teleports every frame, a field that takes two seconds to settle is the wrong tool. This fits crowds moving toward a goal that changes on a human timescale, not a goal that flickers.

How far does it scale? 5,000, 10,000, 20,000 agents

The 500-agent before-and-after is the case people actually search for: why does my Godot pathfinding lag with many units? But a shared field barely cares how many agents read it, so here is the native scheduled ladder - each count measured separately, same machine, same 256x256 grid, though the 5,000-to-20,000 runs use a smaller per-frame field-step budget than the 500 baseline, which is the knob behind their longer refresh latency below.

From 500 to 20,000 agents (40x the crowd), the median frame goes from 2 ms to 9.5 ms, still inside the 60 FPS budget. The per-frame cost is reading a field, which scales with how many agents read it, not with a path solve per agent. Naive has no row past the first: it cannot get there. At 500 it already produces a 670 ms median, and a 5,000-query frame sampled on its own sits near 7.7 seconds.

The honest cost keeps its shape: field-completion latency of about 4.3 seconds to fully settle after a goal move at this budget, and at 20,000 a rare rebuild frame that grazes the budget - 0.14% of frames, while the steady state stays at 0%. Headroom with a labeled edge, not a promise. The 10,000 and 20,000 datasets are downloadable below.

Ten thousand agents, in a browser tab

The runs above are native, measured, with JSON attached. This one is different on purpose: it is the same scheduled shared field exported to WebAssembly and run in a browser. On the same commodity desktop - a 2018 AMD Ryzen 5 2600X, not a lab machine - the scheduled mode holds 10,000 agents at 77 fps in a browser tab. Pure GDScript, no Rust in the hot path, no DOTS.

Here is why it survives the browser when so much else does not: the browser throttles per-agent compute, and a shared field has almost none. Each agent samples one direction vector and moves - there is no path query to slow down. The expensive part, rebuilding the field, is rare and time-sliced. That is also why the live demo caps naive mode at 1,000: per-agent queries are exactly the work a browser punishes hardest, so the same crowd that collapses at a few hundred in naive mode runs at ten thousand in scheduled mode.

Two honest caveats. There is no naive baseline at 10,000 - the per-agent loop cannot get there, which is itself the point. And the web build will not reproduce the exact native millisecond numbers above; the cited benchmark is native, and 77 fps is the live browser frame rate, not a frame-time measurement. What the browser proves is the shape: once per-agent cost is a field read, the agent count stops being the thing that breaks.

How to optimize pathfinding for hundreds of units in Godot

If you have many enemies, workers, soldiers, or swarm units, the practical checklist from this test is simple. The optimization is not use fewer agents. It is stop making every agent solve the same problem at the same time.

For Godot pathfinding optimization, treat a Godot pathfinding slow report as a query-shape problem first: count how many full paths you ask the engine to solve in one frame.

1. Count your path queries per frame. That number, not the agent count, is usually the problem.
2. Separate unique-goal units from shared-goal crowds.
3. Stop recomputing equivalent paths for every agent, every frame.
4. When many agents head to the same place, compute shared direction data once and let them read it.
5. Rebuild that data over multiple frames with a fixed work budget.
6. Keep the last completed field live while the next one builds.
7. Track median, p95, p99, max, and percent of frames over budget - not average FPS.
8. Give high-priority or hero units exact per-agent paths only when they actually need them.

Why average FPS hides this

If you only watch average frame rate, the naive run can look survivable while it ships a 5-second stall a player feels as a freeze. For spiky workloads, the tail is the story. That is why every table here leads with the distribution: p95, p99, max, and over-budget percentage.

What this benchmark does and does not claim

It does not claim every Godot pathfinding problem wants a shared field, that every game's units can share one destination, that AStarGrid2D is bad, that avoidance, physics, animation, and combat are free, that a web build performs like a native one, or that your machine will print these exact numbers.

It does claim, narrowly: repeated per-agent path queries can destroy the frame budget; one shared field can turn that repeated global work into shared data many agents reuse; bounded rebuild work trades frame spikes for controlled, measurable latency; and for this kind of test, p95, p99, max, and over-budget frames are the numbers worth publishing.

If your project is already hitting the edges around agent count, blockers, clearance, and scheduling, the broader production question is where AStarGrid2D stops being enough in Godot. This benchmark is one measured slice of that larger boundary.

Where PathForge fits

This benchmark is where PathForge started. It is being built as a production Godot grid-navigation toolkit: clearance maps for multi-size agents, dynamic blockers without full rebuilds, budgeted path queries, and editor diagnostics that explain why a route failed instead of returning an empty array. The crowd-scheduling layer measured here is one piece of that.

The claim worth standing behind is the small one, and it is the one with receipts: in this benchmark, replacing repeated per-agent path queries with one scheduled shared field removed the frame spike at 500 agents and held the field to 20,000. Not the fastest pathfinding in Godot, not solved crowds - that one measured thing, with the JSON attached.

Try it

The interactive web demo runs the comparison in your browser: drag the goal, flip between naive and scheduled modes, and read the live readouts. Naive is capped at 1,000 so the browser stays safe; push the scheduled mode up to 10,000 agents and watch it hold. It is the visual proof and exploration surface, not the measurement source.

The full benchmark JSON, budget sweep, 5,000/10,000/20,000 scheduled runs, and runnable Godot project are downloadable so you can check the numbers against the conditions yourself.