Log inGet started
World

Pathwise: Navigation and Crowd Agents Kit

Merged

navKit 1.5.2: agents stop writing an unchanged pivot every frame; visualXYZ()

#10
Author
claude-code @ auraAgent
Opened
Nov 17, 2026
From
contrib-pjqgbfz0
Into
main
Merged
Nov 17, 2026

What: NavAgent's per-frame visual step did work that changed nothing for the common case.

  • The pivot (and, with look = "none", the entity's own children) is written only when its offset from the synced transform changes. On the peer that moves an agent the body is the transform, so the offset is zero every frame and nothing is written; a standing agent elsewhere writes nothing either.
  • The children of a look = "none" agent are listed once a second instead of every frame (getChildren() plus a pcall closure per child each frame before).
  • The per-frame target table and the 'before' table in update() are gone (reused fields / two numbers).
  • New agent:visualXYZ() answers the drawn position as three numbers, for callers that ask every frame (visualPosition() still returns a fresh table, unchanged).

Why: townsfolkKit draws 40 townsfolk on look = "none" agents. Profiling Mirage Wells (40 agents) showed NavAgent.update at about 3.3 ms a frame with applyVisual a large share of it, almost all of it writing an empty pivot to the same place. With this change NavAgent x40 measured about 1.5-3 ms a frame on the same (heavily loaded, shared) machine.

Behaviour: unchanged. Smoothing, snapping on jumps/teleports (vis = nil still snaps on the next frame), the grow-in after a teleporter and the child offsets follow exactly the same maths; only writes that would leave a value as it is are skipped.

Tests: navKit suite 81/81 on 1.5.1 + this change (desktop, 2026-11-17). Version 1.5.2 in README, package.yaml and NK.VERSION, changelog entry added.

Source world: 5c8cf408-970f-49b4-8b44-9ed6c609de9d Contributed paths:

  • navKit.package/NavAgent.component/init.luau
  • navKit.package/README.md
  • navKit.package/api.module/init.luau
  • navKit.package/package.yaml
  • navKit.package
  • navKit.package/NavAgent.component
  • navKit.package/api.module
  • gallery/CrateDrop.component/init.luau
  • gallery/Patrol.component/init.luau
  • gallery/SyncProbe.component/init.luau
  • gallery/crowd.module/init.luau
  • gallery/platformProbe.module/init.luau
  • gallery/syncProbe.module/init.luau
  • navKit.package/ClickToMove.component/init.luau
  • navKit.package/navKit.testSuite/init.luau
  • scenes/main.scene/build.luau
  • scenes/main.scene/scene.json

9 files changed

  • ChangednavKit.packageFolderBeforeAfter
  • ChangednavKit.package/NavAgent.componentFolderBeforeAfter
  • ChangednavKit.package/NavAgent.component/init.luau14.3 KB → 15.9 KBBeforeAfter
  • ChangednavKit.package/README.md57.2 KB → 58.7 KBBeforeAfter
  • ChangednavKit.package/api.moduleFolderBeforeAfter
  • ChangednavKit.package/api.module/init.luau15.8 KB → 15.8 KBBeforeAfter
  • ChangednavKit.package/maps.moduleFolderBeforeAfter
  • ChangednavKit.package/maps.module/init.luau36.9 KB → 37.2 KBBeforeAfter
  • ChangednavKit.package/package.yaml1.6 KB → 1.6 KBBeforeAfter

Checks

No checks have been posted.

Reviews

No reviews yet.

Conversation

  1. claude-code @ auraAgentNov 17, 2026

    Added 1.5.3 to this pull request: the string-pull after a path search (map:smooth) now gives the crowd's planner the same chance to pause as the search itself, before each clear-line check and every 32 steps along a long line (Maps.searchTick, only set inside the planner, so NK.findPath / clearLine callers outside it are unchanged). Why: townsfolkKit's browser readings showed crowd frames over 33 ms, and smooth always ran to the end in the frame the search finished. Measured over 312 townsfolk routes in Mirage Wells (counted as work, since wall timings on the loaded test machine were swollen by preemption): the straightening was at most ~2.2 ms on a desktop (0.3 ms typical); with this change the longest route (7,892 floor lookups) has 298 pause points, a few microseconds of work apart. Tests: navKit 81/81, townsfolkKit 15/15. Version 1.5.3 in README, package.yaml and NK.VERSION, changelog entry added.

Sign in to comment or review.