Log inGet started
World

Pathwise: Navigation and Crowd Agents Kit

Merged

navKit 1.5.0: bounded path searches spread over frames; unreachable goals back off

#8
Author
claude-code @ auraAgent
Opened
Nov 15, 2026
From
navkit-1.5.0
Into
main
Merged
Nov 15, 2026

A path search was allowed to expand max(8000, nodeCount) nodes, so on a 160 m town or 200 m dungeon grid an agent whose target could not be reached searched the whole map in one frame (100,800 nodes, 2,734 ms measured on a 160 m grid) and the engine watchdog killed scripts; every 3 s retry did it again.

  • maps.findPath: one search expands at most Maps.maxSearchNodes (default 10000; profile.maxNodes still wins). Hitting the cap returns a partial path to the closest spot found, or unreachable when that spot is the start; the result carries capped = true.
  • crowd: plans run in a coroutine; the map views call Maps.searchTick per expanded node, which yields once the frame's shared planning budget (planBudgetMs, 5 ms) is spent, so a long search carries on next frame instead of holding the frame. One search in flight at a time; an agent being searched is never re-queued, and a goal change during the search queues one fresh plan when it ends. Results are dropped if the agent left or its goal moved meanwhile.
  • Unreachable / partial results back off: retry after 3 s, 6, 12, up to 30 s; a new target resets it.
  • NK.searchBudget(opts?) reads and sets maxNodes, frameMs, plansPerFrame, retryDelay, retryMaxDelay. NK.stats() adds capped and carried. API otherwise unchanged; direct NK.findPath still runs at once, bounded.

Measured on a 160 m grid (102,416 nodes), unreachable target: before 2,734 ms in one call; capped 285 ms in one call; sliced 51 frames of at most 27 ms. Tests: 3 new (search budget describe); navKit suite 80/80.

11 files changed

  • ChangednavKit.packageFolderBeforeAfter
  • ChangednavKit.package/README.md53.8 KB → 55.8 KBBeforeAfter
  • ChangednavKit.package/api.moduleFolderBeforeAfter
  • ChangednavKit.package/api.module/init.luau13.7 KB → 14.8 KBBeforeAfter
  • ChangednavKit.package/crowd.moduleFolderBeforeAfter
  • ChangednavKit.package/crowd.module/init.luau58.9 KB → 61.7 KBBeforeAfter
  • ChangednavKit.package/maps.moduleFolderBeforeAfter
  • ChangednavKit.package/maps.module/init.luau35.5 KB → 36.9 KBBeforeAfter
  • ChangednavKit.package/navKit.testSuiteFolderBeforeAfter
  • ChangednavKit.package/navKit.testSuite/init.luau74.2 KB → 78.2 KBBeforeAfter
  • ChangednavKit.package/package.yaml1.6 KB → 1.6 KBBeforeAfter

Checks

From the author and the world's members

Reviews

No reviews yet.

Conversation

No comments yet.

Sign in to comment or review.