DEV Community: Vav Labs

TileMapLayer Custom Data for Movement Costs in Godot

Vav Labs — Sat, 22 Aug 2026 10:21:06 +0000

Your units keep preferring a strip of tiles you never gave a movement cost.
There's no error anywhere. The path is legal. The route is wrong.

Here's the chain that produces it in Godot 4.7.2. A typed float custom-data
layer defaults to 0.0. TileData.has_custom_data() checks whether the named
layer exists in the TileSet — it doesn't know whether you actually painted a
value on this tile. And AStarGrid2D.set_point_weight_scale() rejects negative
values but accepts 0.0 without complaint. So one unpainted tile imports as
free to enter, and every step of that is silent.

To be fair, this is documented behavior. has_custom_data() is honest about
what it checks. People still hit it constantly, because the name reads like a
per-tile check. This guard is the usual suspect:

if tile_data.has_custom_data("movement_cost"):
    var cost := float(tile_data.get_custom_data("movement_cost"))

Once the layer exists, that branch succeeds for every tile that has one —
including tiles still holding the typed default 0.0.

The fix is an importer, not a call

What worked for me is treating the TileSet like untrusted input:

Resolve the custom-data layer once, by name, and verify its Variant type.
Read TileData for each used cell. get_cell_tile_data() returns null for scene-collection tiles, so decide what happens to those instead of silently costing them like grass.
Reject non-finite values and anything below your declared minimum. I use 1.0 — it makes an untouched default fail loudly instead of quietly becoming a free tile.
Validate the complete batch first, then write. Half an imported grid is worse than a clean failure.
Apply weights only after AStarGrid2D.update(), because update() clears all point data — solidity and weight scale both. Replay from your normalized data after any later structural update.

If different units read terrain differently (infantry vs vehicles), don't
author a float at all. Store a terrain_id string on the tile and resolve it
through per-profile cost tables at runtime. One authored float can't represent
two movement policies.

Two more one-liners worth stealing:

jumping_enabled disables weight scaling entirely. It's in the class reference, and the 4.7.2 source carries a TODO for weighted jumping. If costs must affect route choice, keep jumping off.
Weight is charged on entry: the engine multiplies the step cost by the weight scale of the point being entered, so a path's terrain total skips the starting cell.

What's verified

The write-up ships a standalone Godot 4.7.2 project (MIT) with a serialized
TileSet fixture and a 14-check receipt, zero failures, including a clean rerun
after extracting the package. My favorite check opens the .tres as text and
proves the untouched tile has no explicit custom_data_0 property before
loading it and observing the runtime 0.0 — so the fixture can't cheat with
an editor-serialized explicit zero.

It's a correctness proof, not a benchmark. No timing, no throughput, no claims
about large-map import time.

The importer isn't clever, and that's the point. Its job is to make invalid
authoring visible before it becomes a plausible but wrong route.

Full version with the importer source, the fixture, the failure-mode table and
the raw receipt JSON:

TileMapLayer Custom Data for Movement Costs in Godot

Smooth Grid Paths in Godot: Post-Smoothing vs Theta*

Vav Labs — Fri, 21 Aug 2026 19:53:52 +0000

AStarGrid2D` returns a perfectly legal route that still looks like it was drawn
on graph paper. East, 45 degrees, east again, repeat, across a room that could
have been crossed in one straight line.

That's not an A* failure. The search was asked to move between grid neighbors,
so it returned a path made of grid moves.

There are two standard fixes and they get treated as interchangeable. They
aren't.

Smoothing runs after the search

Keep the first cell, connect it to the farthest later cell it can see, keep that
one, repeat until the goal.

`gdscript
var output: Array[Vector2i] = [input[0]]
var anchor_index := 0

while anchor_index < input.size() - 1:
var candidate_index := input.size() - 1
while candidate_index > anchor_index:
calls += 1
if visibility.has_line_of_sight(
input[anchor_index], input[candidate_index], profile_id
):
break
candidate_index -= 1

if candidate_index == anchor_index:
    return _result(
        false, "MOVEMENT_VISIBILITY_MISMATCH", output,
        input.size(), calls, revision
    )

output.append(input[candidate_index])
anchor_index = candidate_index

Search backward from the goal, not forward. Visibility isn't monotonic along the
waypoint list, so one blocked candidate doesn't prove every later endpoint is
blocked. The straightforward pass costs a quadratic number of line-of-sight
calls in the number of waypoints, which is fine at waypoint counts and worth
measuring before optimizing.

Smooth over cell IDs from get_id_path(), not world positions. That keeps the
visibility test in grid space instead of rebuilding cell identity by rounding
floats.

Theta* runs inside it

Basic Theta* changes the relaxation step. When it reaches a neighbor it also
asks whether the current node's parent can see that neighbor, and reparents
when the visible shortcut is cheaper.

`gdscript
for direction in DIRECTIONS:
var neighbor := current + direction
if closed.has(neighbor) \
or not visibility.is_anchor_open(neighbor, profile_id):
continue

los_calls += 1
if not visibility.has_line_of_sight(current, neighbor, profile_id):
    continue

var best_parent := current
var best_cost := float(g_score[current]) + _distance(current, neighbor)
var ancestor := Vector2i(parent[current])
if ancestor != current:
    los_calls += 1
    if visibility.has_line_of_sight(ancestor, neighbor, profile_id):
        var ancestor_cost := float(g_score[ancestor]) \
            + _distance(ancestor, neighbor)
        if ancestor_cost < best_cost - EPSILON:
            best_cost = ancestor_cost
            best_parent = ancestor

if best_cost >= float(g_score.get(neighbor, INF_COST)) - EPSILON:
    continue
g_score[neighbor] = best_cost
parent[neighbor] = best_parent
frontier.push(neighbor, best_cost, _distance(neighbor, goal))

Note the first line-of-sight call. It tests the ordinary local step, not the
shortcut. Drop it and your diagonal moves start cutting blocked corners that the
search itself forbids, which is the whole bug this contract exists to prevent.

Use Euclidean distance for cost and heuristic. Octile prices a route along
eight-neighbor grid edges, so it overestimates any segment whose slope is
neither axial nor 45 degrees.

Where smoothing stops

Smoothing can only delete waypoints from the route A* already committed to. It
can't move the path to the other side of an obstacle, because the bend it would
need was never in the list.

One authored fixture in the verified project: the AStarGrid2D route measures
19.314 cell units. Smoothing gets it to 18.806 and stays on the upper side.
Basic Theta* takes the lower side at 18.601.

Operation counts tell the same story from the other direction. The open Theta*
case expands 9 nodes and makes 120 line-of-sight calls. Expansion counts alone
hide that work entirely.

What the line-of-sight contract has to say

This is the part that actually decides whether your implementation is correct,
and prose can't prove it:

where a node lives (cell corners in the paper, cell centers in most Godot tile code)
what happens at a blocked corner, and whether it matches the diagonal rule the search already uses
which cells a segment touches, boundary to boundary, with deterministic ties
whether line_of_sight(a, b) == line_of_sight(b, a)
whether the agent footprint fits along the whole segment, not just the center line
which topology revision a cached visibility result belongs to

Godot 4.7.2 has none of this built in. AStarGrid2D has no any-angle mode, and
jumping_enabled is Jump Point Search-style pruning, not arbitrary-angle
parents.

What's verified and what isn't

The standalone Godot 4.7.2 project is MIT licensed. Its receipt records 12
checks and zero failures, including line-of-sight symmetry across 5,995
unordered cell pairs, an 80-grid generated corpus where all 594 returned
segments pass the same contract, deterministic ties across 21 runs, and a clean
rerun after package extraction.

It records no timing, memory, or throughput data at all. Basic Theta* is
complete under its model and not optimal. The square_2x2 profile is a
translated occupied-cell offset set, not a disk or a rotating shape.

Full version with the corner rules, the FAQ, the sources, the source zip and the
raw receipt JSON:

Smooth Grid Paths in Godot: Post-Smoothing vs Theta*

3D Pathfinding in Godot 4: NavigationAgent3D, the Three Radii, and When You Actually Need AStar3D

Vav Labs — Fri, 07 Aug 2026 08:26:42 +0000

Originally published on vav-labs.com. Everything below is Godot 4.7.1 stable, and there's a runnable MIT-licensed project with a verification receipt at the end.

You add a NavigationRegion3D, bake a mesh, drop a NavigationAgent3D on your character, set target_position, hit Play, and the character stands there doing nothing at all.

That's the normal first run. All of it is documented, and people still lose an evening to it (me included). The reason is that 3D navigation in Godot is really four separate systems that have to agree with each other: the baked mesh, the physics body, the agent, and your own movement code. Any one of them can be wrong on its own terms while looking fine in the inspector.

So here's the whole contract in one place, in the order you'd actually build it.

Navmesh or AStar3D? Decide by movement space

Before any setup, pick the representation. This is the choice people get wrong most often, and it's not really about 2D versus 3D.

Your movement space	Use
Grounded movement over authored 3D geometry	`NavigationMesh` + `NavigationAgent3D`
Voxels, stacked tiles, waypoints, other predefined positions	An explicit `AStar3D` point graph
Fully volumetric flight or swimming	An explicit 3D graph or something purpose-built

A navmesh describes continuous walkable space. One polygon can cover a whole floor, and the bake follows your authored geometry instead of chopping the level into cubes. That's the ordinary answer for a character walking through a scene.

AStar3D describes points and connections, and it's the better fit when the positions themselves are the rules: a voxel that can be occupied, a flying unit hopping between lattice nodes, a turn-based actor paying for one exact step. The catch is that AStar3D won't inspect a GridMap and discover the graph for you. You add every point, connect every legal pair, and keep the thing in sync when the world changes.

This post builds the first case.

The scene, and the order to build it

Nothing exotic. Everything here is authored before Play.

Main (Node3D)
├── NavigationRegion3D
│   └── LevelGeometry (floor, ramp, platform, walls)
├── Player (CharacterBody3D)
│   ├── CollisionShape3D
│   ├── MeshInstance3D
│   └── NavigationAgent3D
├── MovingObstacle (AnimatableBody3D)
│   └── NavigationObstacle3D
├── TargetMarker
├── PathLine
└── Camera3D

Build it in this order and you get a working result at every step, which makes it obvious where things broke:

NavigationRegion3D with the level geometry under it. The floor, ramp, platform and walls are visible in the editor.
A NavigationMesh resource on the region, baked and saved. You now have a walkable surface.
CharacterBody3D with a NavigationAgent3D child. A grounded body can follow one target across the ramp.
Physics-step mouse raycast. Left click produces a world-space target.
Closest-point clamping and a path line. The target snaps to the navmesh and the route is visible.
Optional avoidance obstacle. Local steering reacts to motion without touching the global path.

Baking the NavigationMesh

Put the walkable geometry under NavigationRegion3D, create a NavigationMesh on the region, bake. Turn on the navigation debug view while you're adjusting things — the colored overlay should connect the lower floor to the upper platform and keep visible clearance around dividers.

NavigationMesh property	Starter value	What it changes
`agent_radius`	`0.50`	Erodes clearance around walls and ledges
`agent_height`	`2.0`	Minimum vertical space the body needs
`agent_max_climb`	`0.50`	Joins surfaces across small height changes
`agent_max_slope`	`35.0`	Keeps the 20-degree ramp walkable
`cell_size`	`0.25`	Horizontal bake resolution
`cell_height`	`0.25`	Vertical bake resolution

Two things that bite here. cell_size and cell_height have to match the navigation map, and Godot rounds the bake radius up to a multiple of cell_size. So a coarse cell size can quietly erode more space than the radius field suggests, and your doorway disappears for reasons the inspector never shows you.

Keep the three radii separate

This is the one I'd put on a sticky note. Three different settings all read like "the agent radius" during a quick inspector pass, and they don't do the same job.

Setting	Starter value	Owner
`CapsuleShape3D.radius`	`0.48`	Physics collision
`NavigationMesh.agent_radius`	`0.50`	Bake-time wall and ledge clearance
`NavigationAgent3D.radius`	`0.55`	Local avoidance only

The bake radius should cover the physical body plus a small margin. The avoidance radius can run a little wider, because it controls preferred spacing between agents, not whether a doorway is legal.

Get the relationship backwards and you get two distinct bugs. Bake for a body smaller than the collision capsule and the path will happily route around a corner that physics won't let you take. Bake too large and narrow doors vanish from the mesh entirely. When something looks wrong at a doorway, debug the baked surface and the collision shape together, not one at a time.

Wait until the navigation map is usable

The empty-first-path case is documented: the map hasn't synchronized the region yet. For a small scene, deferring setup and waiting one physics frame is the normal baseline.

The starter is stricter than that, because it assigns an automatic target the moment the scene is ready. It waits for a map iteration, a registered region, and a closest point near the authored spawn:

func _ready() -> void:
    _spawn_transform = global_transform
    floor_snap_length = 0.45
    floor_max_angle = deg_to_rad(45.0)
    agent.velocity_computed.connect(_on_velocity_computed)
    _finish_navigation_setup.call_deferred()


func _finish_navigation_setup() -> void:
    while true:
        var map_rid := agent.get_navigation_map()
        var map_has_data := NavigationServer3D.map_get_iteration_id(map_rid) > 0 \
            and not NavigationServer3D.map_get_regions(map_rid).is_empty()
        var closest_point := NavigationServer3D.map_get_closest_point(
            map_rid, global_position) if map_has_data else Vector3.ZERO
        if map_has_data and closest_point.distance_to(global_position) < 2.0:
            break
        await get_tree().physics_frame
    _navigation_is_ready = true
    navigation_ready.emit()

Don't copy the two-metre check into a reusable library. It belongs to this authored spawn point. In your scene, pick a readiness assertion that matches where your character is actually supposed to start.

Raycast the click during the physics step

Mouse input arrives outside the physics callback, but direct_space_state wants to be queried during physics processing. Store the screen position, consume it in _physics_process():

func _unhandled_input(event: InputEvent) -> void:
    if event is InputEventMouseButton \
            and event.button_index == MOUSE_BUTTON_LEFT \
            and event.pressed:
        _pending_click = event.position
        get_viewport().set_input_as_handled()


func _physics_process(_delta: float) -> void:
    if _pending_click == null:
        return
    var click_position: Vector2 = _pending_click
    _pending_click = null
    _raycast_target(click_position)


func _raycast_target(screen_position: Vector2) -> void:
    var ray_origin := camera.project_ray_origin(screen_position)
    var ray_end := ray_origin + camera.project_ray_normal(screen_position) * 200.0
    var query := PhysicsRayQueryParameters3D.create(ray_origin, ray_end, 1)
    query.exclude = [player.get_rid()]
    var hit := get_world_3d().direct_space_state.intersect_ray(query)
    if hit.is_empty():
        _set_status("No level surface under that click.")
        return
    _set_target(hit.position)

A physics hit is not a navigation target

A click can land on the side of a wall, on geometry outside the baked region, or next to a disconnected surface. Normalize it explicitly:

func set_navigation_target(requested_position: Vector3) -> Vector3:
    if not _navigation_is_ready:
        return global_position

    var reachable_target := NavigationServer3D.map_get_closest_point(
        agent.get_navigation_map(), requested_position)
    agent.target_position = reachable_target
    _has_target = true
    _last_path = PackedVector3Array()
    return reachable_target

Keep both values around if your UI ever needs to explain a correction — the starter displays the requested world position next to the clamped navmesh target. When a character stops short of where you clicked, get_final_position() gives you the reachable end of the current path and is_target_reachable() tells you what the agent thinks of the request.

NavigationAgent3D does not move your character

It computes path information. That's it. Your controller asks for one next point per physics frame, flattens the steering onto the ground plane, applies acceleration, and calls move_and_slide():

func _physics_process(delta: float) -> void:
    if not is_on_floor():
        velocity.y -= _gravity * delta
    elif velocity.y < 0.0:
        velocity.y = -0.1

    var desired_velocity := Vector3.ZERO
    if _navigation_is_ready and _has_target:
        if agent.is_navigation_finished():
            _has_target = false
        else:
            var next_path_position := agent.get_next_path_position()
            var direction := global_position.direction_to(next_path_position)
            direction.y = 0.0
            if direction.length_squared() > 0.0001:
                direction = direction.normalized()
                desired_velocity = direction * move_speed
            _emit_path_if_changed()

    var current_horizontal := Vector3(velocity.x, 0.0, velocity.z)
    desired_velocity = current_horizontal.move_toward(
        desired_velocity, acceleration * delta)

    if agent.avoidance_enabled and _navigation_is_ready:
        agent.velocity = desired_velocity
    else:
        _on_velocity_computed(desired_velocity)

Keep get_next_path_position() in the physics loop. Calling it from signals like waypoint_reached can retrigger path updates and recurse on you.

The ramp that ate an evening

The first version of this starter had a route that was completely valid and completely unwalkable. The navmesh connected the floor to the upper platform, the path line drew a clean cyan arc up the ramp, and the capsule walked to the bottom of the ramp and stopped.

Nothing was wrong with the pathfinding. The baked route approached the vertical side face of the ramp collider, and no combination of floor_snap_length, gravity, or floor_max_angle was going to get a CharacterBody3D up a wall. Making both ramp transitions physically flush is what fixed it.

A valid path is not a promise that the body can execute it. When movement stalls and the path looks correct, stop reading navigation code and go inspect the collider.

The other tuning result worth stealing: path_desired_distance = 0.65. Smaller values made this particular accelerated body overshoot each waypoint and then curve back toward it, forever. Derive that number from your controller's speed and stopping behaviour rather than copying mine.

Avoidance changes velocity, not the path

The moving obstacle in the starter is a NavigationObstacle3D that publishes its velocity every physics frame so the avoidance server can predict it:

func _physics_process(delta: float) -> void:
    var previous_position := global_position
    _phase = fmod(_phase + TAU * cycles_per_second * delta, TAU)
    var next_position := _spawn_position + travel_axis.normalized() \
        * sin(_phase) * travel_distance
    last_reported_velocity = (next_position - previous_position) / maxf(delta, 0.0001)
    navigation_obstacle.velocity = last_reported_velocity
    global_position = next_position

The player sends its desired horizontal velocity through agent.velocity, and velocity_computed hands back a locally safer one:

func _on_velocity_computed(safe_velocity: Vector3) -> void:
    velocity.x = safe_velocity.x
    velocity.z = safe_velocity.z
    move_and_slide()

While all of that happens, the cyan path line doesn't move. That's correct behaviour, and it surprises people. Avoidance doesn't rebake the mesh, doesn't pick a new route, and doesn't know your physics collider exists. It nudges velocity and nothing else.

Which also means avoidance can pin an agent against a wall if you park a moving obstacle in a narrow corridor. If an object is supposed to make a route illegal, you need an actual navigation change, not steering.

Symptom table

Symptom	Check first
First path comes back empty	Wait for map and region data to synchronize
Path computes, character doesn't move	`NavigationAgent3D` doesn't move its parent; call your controller
Body clips or sticks at a doorway	Compare `CollisionShape3D` against the baked `agent_radius`
A moving object gets ignored	Enable avoidance and supply the obstacle's velocity
Character stops short of the click	Compare the request with `get_final_position()` and `is_target_reachable()`
Path crosses the ramp, body stops at its foot	Inspect the collider for a vertical lip or side-face approach
Body circles a waypoint	Raise `path_desired_distance`, or retune speed and acceleration
Path line changes when you only expected steering	Something is assigning a new target. Avoidance alone doesn't reroute

When AStar3D is the right answer

Reach for it when the legal positions and edges are explicit game data:

A voxel world where each block position can be occupied or disabled
A dungeon built from stacked tile layers
Fixed 3D waypoints with one-way or authored connections
A flying or swimming lattice with discrete neighbours
Turn-based 3D movement with exact per-node costs

You own that graph completely. Add each point, connect the legal pairs, disable and reconnect points when the world changes, then move the actor along the returned point path. Nothing discovers it for you.

Run the verified starter

The download is the exact authored scene and scripts from this article, MIT-licensed: Godot 4.7.1 source project, 13,833 bytes, SHA-256 bcfb590993cfd025b810f745bf0303d39061cdf6c177f0c27bf66be637104d1c.

Beside it is a machine-readable verification receipt: 21 named checks, 21 passed, 0 failed, on Godot 4.7.1-stable (official, engine hash a13da4fe). It records the ZIP hash, per-file hashes, a clean import of the extracted project, and a scene smoke test that reports 27 navmesh polygons and 26 vertices from the saved bake.

Honest boundary, straight from the receipt: this is deterministic tutorial correctness. It makes no claim about FPS, throughput, crowd capacity, path optimality, production-readiness, or dynamic blockers. If you want a number for "how many agents can I run," you'll have to profile your own project.

The full version is on vav-labs.com, and it embeds the scene as a playable web export so you can click around before downloading anything. It also carries the FAQ and the links out to the related guides.

If any of this doesn't match what you're hitting in your own scene, I'd genuinely like to hear about it. The failure modes here are more varied than one post can cover.

Why NavigationAgent2D Lags With Hundreds of Units

Vav Labs — Wed, 15 Jul 2026 15:05:59 +0000

Originally published on vav-labs.com. Everything here is against Godot 4.7 stable, and there's a runnable source project with a verification receipt at the end.

If your game runs fine with a dozen units and then hitches the moment you box-select a hundred and click "move," the instinct is to blame the pathfinding algorithm. Usually it isn't the algorithm.

It's how many path requests you started in one physics tick.

This one's in the docs, and people still hit it constantly (me included, the first time I built an RTS selection). Setting NavigationAgent2D.target_position requests a new path. Do that for 100 selected units in a single frame and you've just queued 100 path queries in that frame. One query is cheap. A hundred of them landing on the same tick is a scheduling problem wearing an algorithm costume.

So before you change anything, count.

First, confirm navigation actually owns the hitch

Profile before you theorize. If the profiler says the frame time is going to physics or rendering or a gameplay script, none of the fixes below apply. Nail the attribution first.

Once you know it's navigation, the next question is whether it's the request side (too many queries starting at once) or the search side (one query that's genuinely expensive). They have different fixes, so don't guess.

What you see	Likely cause	First action
One hitch when a group gets a move order	Same-tick request burst	Update groups or a per-tick request budget
Steady stutter while units chase a moving target	Per-frame `target_position` resets	Distance + time repath thresholds
Lag only where the crowd bunches up	`path_max_distance` recalculations	Measure deviation, tune tolerance, freeze arrivals
Every query is slow, even for one unit	Search-side polygon/edge count	Optimize the nav mesh — scheduling isn't the fix
A squad is smooth but hundreds share one goal badly	Per-agent paths hit their ceiling	Move to a shared field

One thing worth internalizing: path-search cost tracks navigation-mesh polygons and edges, not the physical size of your world. And an unreachable target can force a much longer search. If a single unit is already slow, that's a mesh problem, and no amount of request scheduling will save you.

Count the requests before you tune them

Don't tune budgets and thresholds blind. Add a few custom monitors and watch real numbers in the Debugger's Monitor tab:

# Battle-scene wiring. The receipt covers the governor, not this glue.
func _ready() -> void:
    Performance.add_custom_monitor("repath/requests_per_tick",
        func(): return _requests_this_tick)
    Performance.add_custom_monitor("repath/queue_depth",
        func(): return _governor.queue_depth())
    Performance.add_custom_monitor("repath/oldest_request_ticks",
        func(): return _governor.oldest_request_age_ticks(
            int(Engine.get_physics_frames())))

What each one tells you:

Requests per physics tick — a one-frame group-order burst shows up here.
Requests per unit per second — sustained every-tick target resets show up here.
Queue depth and oldest-request age — tells you your budget is too tight for acceptable response latency.

One caveat: path_changed fires with no reason payload, so you can't ask the engine why it repathed. Track your own reasons where you queue the request (GROUP_ORDER, TARGET_DRIFT, PERIODIC_REFRESH), and only infer "probably knocked off-path" when the target and map revision both stayed fixed but the agent drifted past its tolerance.

Cause A: one click, a hundred requests

This is the common one. The fix is the explicit version of Godot's own "split agents into update groups" advice: route every target change through a single governor that dispatches a budgeted number of live requests per tick.

The nice thing is you can predict the latency before you even run the game. With N pending requests and a budget of B per tick, draining takes ceil(N / B) ticks. At 60 Hz, 500 requests with B = 8 means the last unit gets its path about a second after the order. If that's too slow, raise the budget for small groups, prioritize the visible/player units, or stop issuing one path per unit entirely.

The dispatch loop is bounded two ways — a query ceiling and a separate scan ceiling, so that cleaning up cancelled or superseded entries can't itself blow the tick:

func drain(
    run_query: Callable,
    is_alive: Callable,
    current_map_revision: int,
    now_tick: int
) -> Array[Dictionary]:
    var dispatched: Array[Dictionary] = []
    var scanned := 0
    var query_limit: int = maxi(0, queries_per_tick)
    var scan_limit: int = maxi(0, max_entries_scanned_per_tick)

    while dispatched.size() < query_limit and scanned < scan_limit:
        var entry := _take_next_raw_entry()
        if entry.is_empty():
            break
        scanned += 1
        # ...skip stale/dead entries, then run the query and record it...

A few properties that matter once you're at scale:

Latest target wins. A repeated request for a unit still in the queue updates its target in place, instead of piling on more work.
Dead and cancelled units stop before the callback. Their queued entries never reach the agent.
Request and scan budgets are separate. Stale cleanup can't quietly consume an unbounded tick.

Two small gotchas: keep the governor on the controller that owns the unit registry (one queue per agent just recreates the burst with more objects), and don't reach for Array.pop_front() on a big queue — it shifts every remaining index. Head cursors are cheaper.

Cause B: the target moved one pixel

A chasing unit tends to reset target_position every time its target moves, and every reset is a new path request. The docs even attribute the classic "unit dances between two spots" bug to path updates that are too frequent.

Gate it. Ignore drift smaller than a distance threshold, and refresh a slowly-moving target on a time threshold instead of every frame. Long intervals are fine at range; tighten them near the destination. And treat arrival as a hard stop — an arrived unit requests nothing and stops calling get_next_path_position().

static func repath_reason(
    planned_target: Vector2,
    live_target: Vector2,
    repath_distance: float,
    now_tick: int,
    next_repath_tick: int,
    arrived: bool
) -> StringName:
    if arrived:
        return REASON_NONE
    var drift := planned_target.distance_to(live_target)
    var threshold := maxf(0.0, repath_distance)
    if drift > 0.0 and (threshold == 0.0 or drift >= threshold):
        return REASON_TARGET_DRIFT
    if now_tick >= next_repath_tick:
        return REASON_PERIODIC_REFRESH
    return REASON_NONE

Cause C: avoidance pushes, path_max_distance pulls

path_max_distance is how far an agent is allowed to stray from its ideal path. Godot documents that crossing it triggers a recalculation — including when collision avoidance is what shoved the agent out there.

At crowd scale that chains: avoidance nudges one agent past its tolerance, its new route shifts the local pressure, a neighbor crosses its tolerance, and so on. Before you blame this, correlate the path_changed signal with an unchanged target and map revision plus measured deviation. Otherwise you're guessing.

Three things help, in order:

Tune from measured deviation. Raise path_max_distance just enough that normal steering stays inside it, then recheck that a genuinely lost agent still recovers.
Freeze arrivals. Units sitting inside their destination tolerance stop consuming path updates, so avoidance can't shove them into another recalculation.
Keep steering separate from planning. A momentary avoidance offset doesn't need a brand-new target assignment.

Avoidance and pathfinding are separate systems, and avoidance has its own cost knobs (neighbor_distance, max_neighbors). That's a deeper rabbit hole than this post.

Run the proof yourself

There's a standalone Godot 4.7 project with the full assembled governor, a runnable scene, a verifier, README, and license: source ZIP here. Its machine-readable receipt reports 20/20 named checks, zero failures.

The checks cover both ceilings, FIFO within a priority, high-priority preemption without starving the normal queue, coalescing and promotion, dead/cancelled entries, the threshold policies, arrival freeze, and current-revision dispatch. The scene smoke stands up a real NavigationServer2D region, gets both direct and NavigationAgent2D paths, and drains ten requests as 3, 3, 3, 1 under a three-query budget. The ZIP is 11,641 bytes, SHA-256 5c58b4a53df42cf9b8aa81a0a75758bc64656435344fc0d44db36e92e6f94bef.

Honest boundary: this is scheduling-correctness and scene-integration evidence. It is not an FPS, throughput, memory, or supported-unit-count benchmark. If you want a number for "how many units can I run," you'll have to profile your own project.

Debug order, short version

Profile — confirm the hitch is navigation, not physics/rendering/scripts.
Record requests per tick, per-unit rate, your own reasons, queue depth, oldest age.
GROUP_ORDER spikes → Cause A. Sustained TARGET_DRIFT → Cause B.
Unexplained path_changed with a stable target/map + measured deviation → Cause C.
Check whether arrived units are still consuming path updates.
Change one budget/threshold/tolerance, then re-measure the same counters.
Requests minimal but one query slow → it's the mesh, not scheduling.
Still need separate routes to one shared goal for a huge crowd → shared field.

Fix the cause you measured, not the one you assumed. If any of this doesn't match what you're seeing in your own project, I'd genuinely like to know — the failure modes are more varied than one post can cover.

The full version, with the complete governor code and the internal links to the related failure-mode guides, is on vav-labs.com.

Tower Defense Path Validation in Godot

Vav Labs — Wed, 24 Jun 2026 15:15:50 +0000

In a tower defense, a player can drop one tower that walls off the path and softlocks the wave. The fix isn't to place it and hope pathfinding recovers — it's to validate first: treat the tower as a temporary blocker, ask if a route still exists, revert if it doesn't, and only then commit.

I built a playable Godot 4.7 demo for it: place towers, watch the path reroute, try to seal it and get rejected. The guide also measures the cheap vs expensive way to run that check, with a runnable project.

https://vav-labs.com/blog/tower-defense-path-validation-in-godot/

Godot's NavigationObstacle2D has two modes (and other NavigationServer2D gotchas)

Vav Labs — Tue, 23 Jun 2026 09:42:09 +0000

Godot's NavigationServer2D is powerful and quietly confusing. Most of the pain isn't the API — it's a handful of distinctions that look similar and behave nothing alike. The ones that eat afternoons:

NavigationObstacle2D has two modes, and people conflate them. avoidance_enabled makes your agents steer around an obstacle, but the path query still runs straight through it — so your tower-defense blocker doesn't block the route. affect_navigation_mesh is the other one: it carves the obstacle into the navmesh at bake time, and then the path reroutes.
The empty path. A query returns nothing even though the scene looks walkable — usually because the navmesh was never baked. It's the NavigationServer2D version of forgetting AStarGrid2D.update().
Map-sync timing. NavigationServer changes apply at the end of the physics frame. Query in _ready() or right after editing nav data and you get a stale or empty result — then blame the agent.
NavigationAgent2D isn't the map. The agent is a node-level helper that consumes navigation data; it doesn't make the map valid by itself.

So I wrote the full guide — regions, agents, direct path queries, both obstacle modes, links, and the map-sync trap — checked every claim against the docs and the C++ source, and built an interactive playground for the gotchas. (It's a browser illustration of how the system behaves, not the engine running, and there's no benchmark here — it's a guide, not a measurement.)

Full guide + playground: https://vav-labs.com/blog/navigationserver2d-godot-complete-guide/

If any of it's wrong or out of date for your version, tell me — the navigation API has moved across Godot 4.x, and I'd rather fix it than leave you debugging my mistake.

AStarGrid2D in Godot 4: the gotchas, and an interactive sandbox

Vav Labs — Sun, 21 Jun 2026 23:20:15 +0000

Godot's AStarGrid2D is a ten-minute read and a month of gotchas. The API page is small, you skim it, and then your path comes back empty, your units cut through wall corners, or your weighted swamp gets ignored. None of it is a bug. It's the gap between knowing the method names and knowing which handful of settings actually decide the behavior.

The five that get almost everyone:

You forget update(). Change the region or cell size, skip the rebuild, and you get an empty array with no error.
update() wipes your point data. It clears every solid cell and weight, so you have to set those after you call it.
Diagonal corner-cutting. DIAGONAL_MODE_ALWAYS lets units squeeze diagonally between two walls. You usually want ONLY_IF_NO_OBSTACLES.
jumping_enabled silently ignores weight scale. Turn on JPS and your weighted terrain stops mattering. It's in the docs. People still lose an afternoon to it.
Manhattan overestimates with diagonals. On an 8-direction grid it counts a diagonal as two steps, so your "shortest" path isn't. Reach for Octile.

So I wrote the reference I actually wanted (every property and method, the gotcha attached to each, version-honest across Godot 4.0 → 4.7, checked against the official docs and the C++ source), and built an interactive sandbox for the parts you have to see: drag the goal, paint solid and weighted cells, flip diagonal modes, toggle jumping, and watch the path recompute live. (It's a browser illustration of how AStarGrid2D behaves, not the engine itself running in a tab.)

Full reference and the sandbox: https://vav-labs.com/blog/astargrid2d-complete-reference/

If any of it's wrong or out of date for your version, tell me. The API moved across Godot 4.x, and I'd rather fix it than leave you debugging my mistake.

Moving 10,000 agents in Godot without the frame spike

Vav Labs — Tue, 16 Jun 2026 15:08:59 +0000

I kept reading that Godot pathfinding falls apart with a lot of agents, so I actually measured it. 500 agents each calling AStarGrid2D.get_id_path() every frame gave me a 670 ms median frame on an 8-year-old desktop — a slideshow. Swap those 500 per-agent queries for one shared field the whole crowd reads, and the same agents drop to ~2 ms, nothing over the 16.6 ms budget. The fix was the shape of the work, not a faster solver — and the same approach holds 10,000 agents at 77 FPS in a browser tab, pure GDScript.

Full write-up with the measured ladder out to 20,000 agents, a playable demo (drag the goal, flip naive vs scheduled, push the count yourself), and the benchmark JSON for every count: https://vav-labs.com/blog/moving-10000-agents-in-godot/