Pathwise: Navigation and Crowd Agents Kit
README.md
spawnerKit tests
79 tests over every public call of spawnerKit. Run them in edit mode with tools.use("tests", "run", "spawnerKit") (or zero tests run spawnerKit). They need no player, no camera and no scene of their own.
The front door (spawnerKit.api):
- Constants:
VERSION, the five component refs (SPAWNER,SPAWN_POINT,ENEMY,TURRET,READOUT) and theEVENTS/STYLES/EFFECTS/CURVES/LOOKSlists, checked against the catalog and the modules. - Catalog:
catalog,findandvocabulary. - Curves and waves:
curve,curveSeries,validateWaves,planWaveandloadWaves. - Building:
addSpawnPoint,addSpawner,addTurretandaddReadout. - Control:
spawner,start,stop,reset,nextWave,spawn,setStyle,setEffect,setCurve,setWaves,state,isAuthority,despawnandalive. - Enemies and pool:
isEnemy,defineEnemy,enemyKinds,poolStatsandprewarm. - Events and effects:
on,eventCounts,playEffectandeffectStats.
The modules:
- catalog:
find, including its errors on unknown keys and kinds, andget. - curves: all five curves, strength, clamping,
series,scaleCountand the unknown-curve error. - waves:
normalizedefaults, every validation error, timing and points, mixed order, scripted waves, looping,template,countandplain. - placement: all ten styles (point, area, ring, offscreen with and without the host's camera, path, portal, sky, burrow, trickle, scripted), plus
pickPoint,pickPlayer,pathPoints,entranceAt,halfFovH,has,DEFAULT_EFFECTand the unknown-style error. - bus: exactly the five event names,
on,fire,"*",Disconnect,counts,listenerCountandresetCounts. Unknown events raise, and one failing listener does not stop the others. - util: rng determinism,
range,pick,vecon arrays, xyz tables, vectors and entities, the vector helpers,splitList,faceQuat,owns,peerId,playerBodiesand the point registry. - enemies:
define,get,has,ids,set,palette,buildfor every kind and look (custom and failing builds included) andsetVisible. - effects:
hasandplayfor all seven effects, the shape pool reused throughstep,telegraph,statsand the unknown-id error. - pool:
acquirecreating and then reusing,release,prewarm,restore,stats(created vs reused),scan/register,listen/reportGone,adopt,setHealthEnabled,beginSession,drainandresetStats.
Component methods: Spawner (start, stop, reset, nextWave, spawn, despawnAll, setWaves, getState, isAuthority, alive, planWave), SpawnPoint:record, Enemy:isAlive and PoolReadout:numbers.
End to end:
- Spawning: a spawner with
autoStart = falseand its own spawn points spawns an enemy exactly on the point. Thespawnedpayload is checked field by field. - Despawning and reuse: despawning fires
despawnedwith reasoncleared, and the next spawn returns the same entity (reusedgoes up,createdstays the same). - Pooling stays flat: 40 spawn/release cycles plus 5 rounds of 4 at once leave exactly 4 enemies of the kind in the world.
- threeWaves.data: with the flat curve it plans exactly 6, 7 and 9 enemies. Under the steady curve each count follows
SK.curve("steady", n)(6, 9, 13), and a curve named in the data wins over the spawner's.
What edit mode cannot show
Tests run in edit mode, where no component update() ticks. This peer is still the spawner's authority (an unowned synced entity belongs to the host), so spawn, despawnAll and reset really spawn and release through the pool. But:
- The Spawner only publishes its snapshot and registers its pool handler in
update(). SogetStateis tested on a written snapshot, andSK.despawnreleases straight to the pool without adespawnedevent (despawnAllandresetdo fire it). - Wave timing (
waveStarted,waveCleared,allWavesDonefired by a running spawner) needs play. Those three events are tested through the bus, andstartis tested through the prewarm it does.stopandnextWaveare checked to leave enemies in play. - Enemy movement, the Turret's shooting and the readout's drawing are not covered.
Clean-up
Every describe installs the same clean-up after each test:
- It disconnects listeners, finishes live effect shapes, despawns every entity the test made (all named
skTest_…and spawned far from the gallery) and every enemy the pool made during the test, then rebuilds the pool's lists from the world and resets the bus counters. - Pool enemies the suite creates are marked temporary, so they are never saved into a scene.
- The pool tests use their own enemy kind,
skTestBlob, so created and reused counts are exact. That kind stays registered until the enemies module reloads, because there is no call to remove a kind. Pool.drainandPool.beginSessionare only exercised when every pooled entity in the world is the suite's own; otherwise that test stands down.- The pool's counters are left at zero after the suite (
beginSessionzeroes them again at the start of play anyway).