Log inGet started
World

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.style speeds and refusals, 3 map kinds, 6 link kinds, NK.catalog, NK.find by 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; findPath through a wall's gap (smoothed), refused for a radius or style wider than the gap, smooth = false, unknown style, missing map; isWalkable, nearestPoint, heightAt on 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: setBlocked closing the only corridor and nil reopening it; a blocked box on open floor that the path goes around; addObstacle and NavObstacle:box(), removed when the entity despawns.
  • Events, debug, stats: NK.on connections and Disconnect, 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 the NavAgent methods setTarget, 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.