Pathwise: Navigation and Crowd Agents Kit
README.md
navKit test suite
Automated tests for the navKit package: every public call of navKit.api
and the public methods of each navKit component.
What it covers
- Constants:
NK.VERSION, the six component type names (NK.AGENT,NK.OBSTACLE,NK.LINK,NK.MAP,NK.CLICK,NK.DEBUG),NK.STYLES,NK.MAP_KINDS,NK.LINK_KINDS,NK.EVENTS,NK.vec. - Catalog: the 8 built-in styles with distinct look colours and shapes
(each shape has a body builder),
NK.stylespeeds and refusals, 3 map kinds, 6 link kinds,NK.catalog,NK.findby kind / tag / family / id (and its errors on unknown keys and kinds),NK.defineStyle(inherits from its base, replaces on redefinition). - Maps and paths: grid, waypoint and layered bakes;
NK.map,NK.maps,NK.mapAt,NK.removeMap;findPaththrough a wall's gap (smoothed), refused for a radius or style wider than the gap,smooth = false, unknown style, missing map;isWalkable,nearestPoint,heightAton an upper floor. - Links:
addLink/links/updateLink(lock, unlock, move) /removeLink; a ladder joining two floors of a layered map for a climber, refused by wheeled and heavy; a link kept to another map is ignored. - Obstacles:
setBlockedclosing the only corridor andnilreopening it; a blocked box on open floor that the path goes around;addObstacleandNavObstacle:box(), removed when the entity despawns. - Events, debug, stats:
NK.onconnections andDisconnect, the*wildcard, unknown event names,eventCounts,NK.debug/debugState,NK.stats. - Agents:
addAgent(options, errors, update in place),agent,agents,isAuthority,setTarget,follow,stop,setStyle,setPaused,state, and theNavAgentmethodssetTarget,followEntity,stop,setStyle,getState. - Components:
NavMap:rebake/getMap,NavLink:linkId/endpoints,addClickToMove+ClickToMove:clickAt(returns nil when no camera ray lands; must not error),NavDebug:toggle.
What it leaves alone
Agents only move in play mode, so the suite checks the fields the commands set on the peer in charge (an unsynced temporary entity counts as that peer), not motion, steering, avoidance or link crossing. Multiplayer command forwarding and the debug drawing's GPU output are not exercised.
Fixtures
Each test builds its own temporary colliders far from the gallery, around
x/z 510..600: a floor cut by a wall with a 2 m gap (centre 550, 550), a
ground floor with a 3 m-high platform (580, 520), and an open floor
(520, 580). Walls are 1 m thick: the bake casts one ray per 0.5 m cell, so
anything thinner can fall between the rays. Every map, link, blocked box and
entity a test makes is removed by Test.registerCleanup, pass or fail.
NK.defineStyle registrations cannot be undone; the suite reuses the one id
navtest_scout, so a re-run replaces it.
Regression test
partial path stops on this side of the wall guards a bug this suite found
before 1.0.0 shipped: when the A* only finds a partial path, the path used to
have its last point moved onto the (unreachable) goal, so its final leg
crossed the wall.
Run it
In edit mode (the runner refuses play mode):
return tools.use("tests", "run", { suite = "navKit" })
or from the shell: zero tests run navKit. Results land in
/source/tmp/test_results.md.