Log inGet started
World

Pathwise: Navigation and Crowd Agents Kit

README.md

spawnerKit 1.1.3

Enemy spawners, waves and pooling for any multiplayer game: put a Spawner on a synced entity, give it waves as a data file, and enemies arrive in one of 10 spawn patterns (the pattern setting) with one of 7 effects, get harder along one of 5 curves, and are reused from a pool instead of piling up.

Version 1.1.3 (SK.VERSION). The version, this README and package.yaml move together.

Guides

Two guides ship inside this package, so every install has them:

  • How to spawn waves of enemies (guide path spawnerKit.package/how-to-spawn-waves-of-enemies, file how-to-spawn-waves-of-enemies.guide/guide.md): what the kit's parts are and how they fit, spawners and spawn points, waves and schedules, budgets and difficulty curves, spawning items and pickups (not only enemies), despawning, limits and pooling, and who spawns what in multiplayer (the host decides, every player sees the same enemies).
  • Build a wave survival arena where every wave brings more and tougher enemies (guide path spawnerKit.package/build-a-wave-survival-arena-with-increasing-difficulty, file build-a-wave-survival-arena-with-increasing-difficulty.guide/guide.md): from an empty world to a wave survival game, with spawnerKit for the waves, aiKit for enemies that chase and attack, and SecondWind for health, damage, death and respawn, all three installed from ZeroMind. Followed step by step in a brand-new world before release.

Open one by its guide path: zero guides read spawnerKit.package/how-to-spawn-waves-of-enemies in the shell, the guides tool with that path, or the Docs panel (select the guide in the asset browser and press Open in Docs in its Inspector). Use the whole guide path, package folder and guide name together (see Known limits). The guides point on to aiKit's two guides (aiKit.package/how-to-give-npcs-a-brain, aiKit.package/how-to-make-enemies-that-patrol-chase-and-attack), which open once aiKit is installed, and SecondWind's two (SecondWind.package/how-to-add-health-and-damage-to-your-game, SecondWind.package/build-a-small-arena-game-with-health-bars-hit-markers-and-respawn), which arrive with spawnerKit's install.

Install

One call brings everything spawnerKit builds on: SecondWind (health, damage, death), Lifeline (health bars, under SecondWind), MatchFlow (rounds) and juiceKit (effects).

zeromind_install guid=866b48e5-deed-4e7f-84a8-94ec29134c81 at=/source

(or search ZeroMind for "spawnerKit" and install spawnerKit.package). spawnerKit lands in /source/spawnerKit.package and the four kits under /source/deps/, and require("spawnerKit.api") and require("SecondWind.api") both work from your own scripts. If your world already has one of those kits, spawnerKit uses it. While the install lands, the log can show a burst of module ... has no root to resolve against lines for the kits under deps; they stop once the files are in.

Checked in a brand-new world: this one call, then the example below, word for word, ran all three waves (6, 9 and 13 enemies, every one cleared, all waves done in 51 s).

Use it

Replace your scene's build.luau with this whole file (it makes its own ground, so nothing of the default scene is needed). It makes four spawn points around an arena, a spawner that plays three waves from a data file, a turret that shoots them, the pool readout, and a player whose body has SecondWind health so the enemies can hurt it.

local SK = require("spawnerKit.api")
local HK = require("SecondWind.api")

function content()
	local ground = entity.spawn("ground")
	ground.component.add("Model", { model = asset.resolve("@builtin::meshes.cube", "mesh"),
		material = asset.resolve("@builtin::materials.lit_checkerboard", "material") })
	ground.component.add("BoxCollider", {})
	ground.localPosition = { 0, -0.1, 10 }
	ground.localScale = { 60, 0.2, 60 }

	-- SecondWind's world rules: one per scene, on a synced entity.
	local rules = entity.spawnSynced("HealthRules")
	rules.component.add(HK.RULES, { preset = "arcadeShooter", playerDeathStyle = "timed" })

	-- Spawn points: plain entities (only the host reads them).
	local A = { 0, 0, 20 }
	local dirs = { ArenaNorth = { 0, 9 }, ArenaSouth = { 0, -9 }, ArenaEast = { 9, 0 }, ArenaWest = { -9, 0 } }
	for name, d in dirs do
		local p = entity.spawn(name, { position = { A[1] + d[1], 0, A[3] + d[2] } })
		SK.addSpawnPoint(p, { group = "Arena", kind = "portal" })
	end

	-- The spawner: on a SYNCED entity, playing the waves in arenaWaves.data.
	local spawner = entity.spawnSynced("Arena", { position = A })
	SK.addSpawner(spawner, {
		pattern = "portal", effect = "auto", curve = "steady",
		waves = asset.resolve("arenaWaves", "data"),
		maxAlive = 10, behavior = "chase", aggroRadius = 13, prewarm = 6,
	})

	-- A turret in the middle of the arena that reaches every portal, and the readout.
	SK.addTurret(entity.spawn("ArenaTurret", { position = A }), { range = 12, only = "Arena" })
	SK.addReadout(entity.spawn("PoolReadout"), { spawner = "Arena", corner = "topLeft" })

	-- The player, with a SecondWind body (as in the gallery).
	local setups = entity.spawn("PlayerSetups")
	local prototype = entity.spawn("Player", { parent = setups })
	prototype:setParticipation("PrototypeOnly")
	local body = entity.spawn("body", { parent = prototype })
	body.component.add("Asset", { source = asset.resolve("@builtin::avatars.humanoid", "avatar") })
	HK.attach(body, { team = "players" })
	local rig = entity.spawn("CameraRig", { parent = prototype })
	rig:setNetworkScope("OwnerOnly")
	rig.component.add("Camera", { behavior = asset.resolve("@builtin::controller.orbital_follow", "component") })
	rig.localPosition = { 0, 2.2, -4.5 }
	rig.localRotation = { 0, -0.9961332, -0.0878564, 0 }
	prototype.component.add("PlayerPrototype", { body = body, camera = rig })
	-- The player starts inside the arena, in the turret's reach.
	local spawn = entity.spawn("Start", { parent = entity.spawn("Spawns"), position = { A[1], 0, A[3] - 6 } })
	spawn.component.add("PlayerSpawn", { prototype = prototype })
end

Then make the waves: a folder /source/arenaWaves.data holding this values.yaml (word for word the kit's own threeWaves.data), plus a .metadata with a description and tags. The point names match the spawn points above. The data leaves curve empty on purpose, so the Spawner's curve = "steady" decides how much harder each wave gets.

contract: spawnerKit.waveTable
values:
  curve: ""
  loop: false
  waves:
    - name: Scouts
      delay: 3
      gap: 1.0
      points: [ArenaNorth, ArenaSouth]
      enemies:
        - { kind: grunt, count: 4 }
        - { kind: runner, count: 2, gap: 0.5 }
    - name: Pincer
      delay: 4
      gap: 0.7
      points: [ArenaEast, ArenaWest]
      order: mixed
      enemies:
        - { kind: grunt, count: 4 }
        - { kind: flyer, count: 3 }
    - name: The Brute
      delay: 5
      gap: 0.6
      points: [ArenaNorth, ArenaEast, ArenaSouth, ArenaWest]
      enemies:
        - { kind: runner, count: 6, gap: 0.3 }
        - { kind: brute, count: 1 }
        - { kind: spitter, count: 2 }

Press play: after 3 s the Scouts come out of the north and south portals, then the Pincer out of east and west, then the Brute out of all four. On the steady curve the three waves bring 6, 9 and 13 enemies (as written they are 6, 7 and 9; steady adds 15% a wave, rounded up per entry).

To react to what happens, listen in code that runs while the game plays, such as the scene's entrypoint.luau (a build.luau runs while you author, not in play). Events fire on every peer, so every player's screen can react:

local SK = require("spawnerKit.api")
local conns = {}

function onLoad()
	table.insert(conns, SK.on("waveStarted", function(e)
		print(`{e.spawnerName}: wave {e.wave} of {e.waves}, "{e.name}", {e.total} enemies`)
	end))
	table.insert(conns, SK.on("despawned", function(e)
		if e.reason == "killed" then print(`a {e.kind} went down`) end
	end))
	table.insert(conns, SK.on("allWavesDone", function(e)
		print(`all {e.waves} waves done in {e.seconds} s: {e.killed} killed, {e.escaped} escaped`)
	end))
end

function onUnload()
	for _, c in conns do c:Disconnect() end
end

Swap one setting

Every choice is one field. Nothing else needs to change.

-- In the build: a different arrival, effect, curve or look.
SK.addSpawner(spawner, { pattern = "sky", effect = "impact", curve = "breather", look = "neon", waves = ... })

-- While playing (on the host, see Multiplayer):
SK.setPattern("Arena", "burrow")  -- next spawn rises out of the ground
SK.setEffect("Arena", "beam")     -- "auto" goes back to the pattern's own effect
SK.setCurve("Arena", "steep")
  • A pattern change applies from the next spawn. With effect = "auto" the effect follows the pattern (see the Patterns table).
  • pattern is the setting's name. style is its older name and still works: style = "sky" in SK.addSpawner options sets the pattern, SK.setStyle is SK.setPattern, and a pattern id written straight into the Spawner's style field is used instead of pattern (leave style empty to let pattern decide).
  • Swapping the curve changes the waves. In the Use it example, change curve = "steady" to curve = "steep" in the build and the same three waves bring 6, 10 and 17 enemies instead of 6, 9 and 13, with more health and a faster pace; breather gives 6, 9 and 14, and flat or stepped give 6, 7 and 9 (stepped's first step up comes at wave 4). SK.setCurve while playing applies from the next wave that starts. SK.planWave(t, n, { curveOverride = "steep" }) shows a wave's plan on any curve without playing it.
  • A curve named in the wave data wins over the Spawner's curve field: a wave's own curve, then the table's curve, then the field. That is why the example data (like the kit's threeWaves.data) leaves curve empty (""): the Spawner's curve field and SK.setCurve decide. Write a curve into the data only when that table should always use it, and then neither of them changes its waves.
  • Unknown ids are refused with an error that lists the known ones.

Catalog

Everything the kit offers is labelled. SK.catalog() returns it all; SK.find(query) filters it:

SK.find({ kind = "pattern", genre = "towerDefense" })  -- point, path, burrow, trickle, scripted
SK.find({ kind = "effect", tag = "zombies" })          -- dirt
SK.find({ kind = { "pattern", "effect" }, genre = "bulletHell" })
SK.vocabulary()   -- the kinds, families per kind and genres the labels use

Query keys are kind (pattern, effect, curve, enemy, look; the entries of the pattern list carry kind = "style", and kind = "style" finds them too), family, genre, tag and id; each takes one value or a list (any of them matches), and every key given must match. An unknown key or kind is an error. Genres: waveShooter, hordeMode, towerDefense, arena, survival, bulletHell, platformer, roguelike, coop, boss.

Spawn patterns (pattern)

idlabelfamilywhat it doeseffect on autosettingstagsgenres
pointSpawn pointplacedEach enemy appears exactly on one of the spawner's spawn points, picked in turn or at random.smokepoints, pointOrderclassic, predictable, doorswaveShooter, arena, towerDefense, hordeMode, coop
areaRandom in areaplacedEach enemy appears at a random spot inside a spawn point's box (sizeX by sizeZ), so a field fills up unevenly.sparklepointsscattered, organichordeMode, survival, arena, roguelike
ringRing around playeraroundPlayerEnemies appear on a circle of ringRadius metres around a player and close in from every side.smokeringRadius, targetsurrounded, pressure, vampire-survivorshordeMode, survival, bulletHell, roguelike
offscreenJust off screenaroundPlayerEnemies appear just beyond the edge of the target player's view and walk in, so nobody sees them pop in.noneoffscreenMargin, targetendless, seamless, never-seen-appearinghordeMode, survival, bulletHell, roguelike
pathAlong a pathrouteEnemies enter at the start of a path and walk a smooth curve through the spawn points of one group, in order, to the end: a Catmull-Rom spline from the engine's spline module (@builtin::modules.spline), drawn on the ground on every peer (showPath).nonepoints, pathSpread, showPathlanes, conveyor, marching, curvedtowerDefense, platformer, arena
portalOut of a portalentranceA swirling portal opens on a spawn point and each enemy steps out of it, growing from nothing.portalpointsmagic, rift, gatearena, waveShooter, boss, roguelike
skyDrop from the skyentranceA shadow marks the spot, then the enemy falls from skyHeight metres and lands with an impact.impactskyHeight, pointsdrop-pod, airborne, telegraphedarena, waveShooter, survival, coop
burrowBurrow up from the groundentranceThe ground bulges, dirt bursts out and the enemy rises out of the floor from burrowDepth metres down.dirtburrowDepth, pointszombies, underground, creepyhordeMode, survival, arena, towerDefense
trickleEndless trickletimingNo waves: one enemy every 1/rate seconds, forever (or until total), never more than maxAlive at once. Difficulty climbs every trickleStep spawns.smokerate, maxAlive, total, trickleStependless, steady-stream, no-wavessurvival, hordeMode, towerDefense
scriptedScripted wave tabletimingEvery spawn is written down: in each wave's script list, the second it happens, the enemy and the spawn point. Nothing is random.beamwavesauthored, exact, set-piecewaveShooter, towerDefense, boss, arena

How they enter: point, area, ring, path, trickle and scripted grow in over 0.35 s; portal grows over 0.8 s; sky falls (for 0.85 s from the default 9 m); burrow rises over 1.1 s; offscreen simply walks in. area, sky and burrow pick a random spot in a spawn point's box when it has a sizeX/sizeZ. With no spawn points at all, ring, trickle and path fall back to a ring around a player, and the others use the spawner's own position.

Spawn effects (effect)

Each effect is juiceKit presets plus, for some, a few pooled shapes of the kit's own.

idlabelfamilywhat it doesjuiceKit presetstagsgenres
smokePuff of smokeclassicA round puff of smoke and a pop-in squash.vfxSmoke, popIncartoon, ninja, poofarena, waveShooter, platformer, coop
portalPortal swirlmagicA purple ring spins open on the ground, magic sparks burst out, and the enemy grows out of it.vfxMagic, popInmagic, purple, swirlarena, roguelike, boss
beamSci-fi beam-inscifiA tall cyan beam of light drops onto the spot, crackles, and the enemy materialises inside it.vfxZap, popInteleport, cyan, energywaveShooter, arena, bulletHell
dirtDirt burstgroundClods of dirt and dust burst up out of the ground where the enemy surfaces.vfxDust, jellyWobbleearth, rubble, zombieshordeMode, survival, towerDefense
impactLanding impactimpactA dust ring, a ground shockwave and a short shake that nearby players feel.landingHardheavy, shockwave, shakearena, survival, boss, coop
sparkleSparkle popmagicA bright pop with a burst of magic sparkles, juiceKit's own spawn combo.spawncute, friendly, lightplatformer, arena, coop
noneNo effectnoneEnemies simply appear. Cheapest, for very large hordes.nonequiet, performancetowerDefense, survival, bulletHell

sky and burrow also telegraph: a shadow grows where a drop will land, a mound of dirt rises before a burrow, and the effect plays when the enemy arrives.

Difficulty curves (curve)

idlabelfamilywhat it doestagsgenres
steadySteadylinearEvery wave a little harder than the last: +15% enemies, +12% health, +6% pace per wave.gentle, fair, predictablewaveShooter, towerDefense, coop, arena
steepSteepexponentialGrows by a percentage each wave (x1.32 enemies, x1.28 health), so wave 8 is a wall.brutal, runaway, short-runshordeMode, survival, roguelike, bulletHell
steppedStepped plateaussteppedThree waves at the same level, then a big jump: room to learn each tier before the next.tiers, chapters, learnabletowerDefense, arena, waveShooter
breatherWith breather wavesrhythmClimbs a little faster than steady, but every fourth wave is a breather: half the enemies at a gentle pace.pacing, rest, intensecoop, hordeMode, waveShooter, survival
flatFlatflatEvery wave exactly as written in the data. For hand-tuned tables.exact, tuning, teststowerDefense, boss, arena

Sample enemies (kind)

idlabelfamilywhat it doeshealth / speed / damage / sizetagsgenres
gruntGruntmeleeThe everyday foot soldier: walks at the nearest player and hits on contact.40 / 2.6 / 10 / 0.9basic, walkerwaveShooter, hordeMode, arena, towerDefense
runnerRunnerfastSmall and quick: twice as fast as a grunt with half the health.20 / 5.2 / 6 / 0.6fast, fragile, swarmhordeMode, survival, arena
bruteBruteheavyBig, slow and hard to put down: five grunts' worth of health and a heavy hit.200 / 1.5 / 25 / 1.6tank, slow, bigarena, towerDefense, boss, coop
flyerFlyerflyingHovers two metres up and swoops at players, ignoring the ground.30 / 3.6 / 8 / 0.7hover, airborne, dronewaveShooter, bulletHell, arena, survival
spitterSpitterrangedStops eight metres away and lobs damage at the nearest player every two seconds.35 / 2.2 / 7 / 0.85ranged, keeps-distancewaveShooter, arena, survival

Melee enemies hit once a second on contact (physical damage, knockback 4); the spitter hits every 2 s from 8 m (poison damage). The flyer's body is drawn raised and bobs, but like every enemy it moves on the spawner's ground height (see Known limits).

Your own kinds: SK.defineEnemy("goblin", { health = 30, speed = 4, damage = 5, size = 0.8, label = "Goblin", build = function(root, look) ... return parts end }). Leave build out to borrow the grunt's look, or spawn local (temporary = true) children under root and return them. Every peer builds looks locally and checks wave data against the known kinds, so call defineEnemy in code that runs on every peer in play (a module your components require, or the scene's entrypoint.luau), not in build.luau.

Looks (look)

idlabelwhat it doestagsgenres
toyToyBright plastic shapes with big round eyes.bright, plastic, friendlyplatformer, arena, coop, towerDefense
neonNeonDark bodies with glowing edges and eyes, readable at night and on dark arenas.glowing, dark, synthwavewaveShooter, bulletHell, arena, survival

The Spawner's look can also be mixed (alternating toy and neon); a wave entry's or script line's look overrides it.

Waves as data

Waves live in a .data file of the spawnerKit.waveTable contract, given to the Spawner's waves field (asset.resolve("<name>", "data")). The same shape works as a Lua table through SK.setWaves(sp, t) or the Spawner's waveTable field (used when waves is empty); in Lua a bare list of waves is accepted too. Check a table with SK.validateWaves(t) and see exactly what a wave will do with SK.planWave(t, n) or sp:planWave(n).

Fields

fielddefaultmeaning
curve"" (none)Difficulty curve for the whole table: steady, steep, stepped, breather, flat. Beats the Spawner's curve.
loopfalseAfter the last wave, start over from wave 1, harder each time (the wave number and so the curve keep climbing). The Spawner's loop field forces it on.
waves[]requiredThe waves, in order. At least one.
waves[].name"Wave <n>"Shown in events and the readout.
waves[].delay2Seconds of waiting before this wave starts (see below for when the wait begins).
waves[].gap0.8Seconds between two spawns of this wave, divided by the curve's pace.
waves[].pointsspawner's pointsSpawn point names (or group names) the wave's spawns cycle through, in turn.
waves[].orderinOrderinOrder: all of the first entry, then all of the next. mixed: one of each entry in turn.
waves[].curve""A curve for this wave only; beats the table's and the Spawner's.
waves[].maxAlive0 (use the Spawner's)Most of this spawner's enemies alive at once while this wave spawns; above 0 it replaces the Spawner's maxAlive.
waves[].enemies[].kindrequiredEnemy kind id: grunt, runner, brute, flyer, spitter or one you defined.
waves[].enemies[].count1How many; multiplied by the curve's count and rounded up (never below 1 when above 0).
waves[].enemies[].gapthe wave's gapSeconds before each of this entry's spawns (divided by pace).
waves[].enemies[].pointsthe wave's pointsSpawn points for this entry only.
waves[].enemies[].lookthe Spawner's looktoy or neon.
waves[].enemies[].health1A multiplier on the kind's health (on top of the curve and healthScale).
waves[].enemies[].speed1A multiplier on the kind's speed (on top of the curve and speedScale).
waves[].script[].at0Seconds after the wave starts (after its delay). Not scaled by the curve's pace.
waves[].script[].kindrequiredEnemy kind id.
waves[].script[].pointthe wave's points, in turnSpawn point name (or group name).
waves[].script[].lookthe Spawner's looktoy or neon.

A wave needs enemies or a script. When a wave has a non-empty script, it is played instead of enemies, whatever the pattern, and the curve does not change its count or timing (it still scales health, speed and damage). Unknown keys, unknown kinds or curves, negative delays and gaps, and counts that are not whole numbers are errors that name the wave and field. A Spawner whose table is missing or invalid reports the error on the component (and in SK.state(sp).error) and runs an endless trickle of its enemy instead.

How delay, gap, advance and maxAlive work together

  1. start() (or autoStart, or the MatchFlow round starting) waits wave 1's delay, then wave 1 begins and fires waveStarted.
  2. The wave's spawns happen on a timetable: the first at 0 s, each next one a gap later (the entry's gap if it has one), divided by the curve's pace.
  3. maxAlive caps how many of this spawner's enemies are alive at once (the wave's own maxAlive replaces it while that wave spawns; 0 means no cap). When the cap is reached the wave's clock holds at the next spawn until one is gone, so the remaining spawns shift later and keep their gaps.
  4. When the last spawn is out, advance decides when the next wave's delay starts counting:
    • cleared (default): once every enemy of this wave is gone. Waves never overlap.
    • timer: right away. Waves can overlap; each still fires its own waveCleared when its enemies are gone.
  5. A wave is cleared when all its spawns are out and none of its enemies is alive; that fires waveCleared (and calls MatchFlow's clearWave() when matchEntity is set). Clearing the last wave fires allWavesDone.
  6. How many waves run: the table's length, or wavesToRun when it is above 0. A looping table with wavesToRun = 0 is endless (its waves count is 0 in events and allWavesDone never fires).
  7. After allWavesDone, restartDelay (≥ 0) starts the spawner again from wave 1 after that many seconds; -1 never does. With a matchEntity, the MatchFlow round restarts it instead.

Difficulty curves

A curve turns a wave number into five multipliers: count (each entry's count, rounded up), pace (gaps are divided by it), speed, health and damage (each enemy's), plus rest = true on a breather wave. With n = (wave - 1) × curveStrength:

curvecountpacespeedhealthdamage
steady1 + 0.15n1 + 0.06n1 + 0.04n1 + 0.12n1 + 0.05n
steep1.32^n1.12^n1.06^n1.28^n1.15^n
stepped (level L = floor((wave - 1) / 3) × strength)1 + 0.6L1 + 0.25L1 + 0.12L1 + 0.5L1 + 0.2L
breather, normal wave1 + 0.2n1 + 0.08n1 + 0.05n1 + 0.15n1 + 0.06n
breather, every 4th wave (rest)0.5 + 0.05n0.710.9 + 0.08n1
flat11111

Limits: count and pace stay within 0.1 to 12, speed 0.1 to 4, health 0.1 to 24, damage 0.1 to 12.

Count multiplier per wave at strength 1 (health in brackets):

wavesteadysteepsteppedbreatherflat
11.00 (1.00)1.00 (1.00)1.00 (1.00)1.00 (1.00)1
21.15 (1.12)1.32 (1.28)1.00 (1.00)1.20 (1.15)1
31.30 (1.24)1.74 (1.64)1.00 (1.00)1.40 (1.30)1
41.45 (1.36)2.30 (2.10)1.60 (1.50)0.65 (1.14) rest1
51.60 (1.48)3.04 (2.68)1.60 (1.50)1.80 (1.60)1
82.05 (1.84)6.98 (5.63)2.20 (2.00)0.85 (1.46) rest1
102.35 (2.08)12.00 (9.22)2.80 (2.50)2.80 (2.35)1

curveStrength scales how hard any curve bites (0 = flat, 2 = twice as steep). The trickle pattern uses level 1 + floor(spawns / trickleStep) as its wave number. On top of the curve, the Spawner's healthScale, speedScale and damageScale multiply every enemy. Read any curve with SK.curve(name, wave, strength) or SK.curveSeries(name, waves, strength).

Pooling

Enemies are made once and reused. Each spawn takes an enemy of that kind out of the pool; when it dies, escapes, expires or is cleared, it goes back: hidden on every peer, parked underground at y = -400, its health components switched off so it costs nothing while it waits. A new entity is only created when the pool has no free enemy of that kind; every other spawn is reused, revived and healed to its new maximum by SecondWind.

So the entity count stays flat: it settles at the most enemies of each kind that were ever alive together (plus any prewarm), and wave 20 makes no more entities than wave 2. One synced entity per enemy is all that crosses the network; its look (one entity per shape) is built locally on each peer as temporary children. Effect shapes come from a small local pool too, so effects never grow the entity count either. The pool is shared by every Spawner in the scene and keyed by enemy kind.

  • Prewarm: the Spawner's prewarm field makes that many enemies of the first wave's first kind (or the trickle's enemy) when it starts, so the first wave reuses instead of creating. SK.prewarm(kind, n, look) tops the free pool of a kind up to n, on the host.
  • Counters: SK.poolStats() gives { created, reused, released, active, pooled, peakActive, entities } on this peer; the host's are the real ones, and every peer reads them from SK.state(sp).pool.
  • The readout: SK.addReadout(e, opts) shows, in a screen corner, how many enemies were created versus reused and the share of spawns reused, how many are in play and pooled, the scene's entity count (with its range over the last 30 s), script memory, each spawner's wave (wave 2/3 next in 4s, all 3 waves done) and, with match, the MatchFlow round. It reads the Spawners' synced snapshots, so every player sees the host's numbers.

Events

local conn = SK.on("waveCleared", function(e) print("cleared", e.name) end)
SK.on("*", function(name, e) print(name, e.wave) end)   -- every event: fn(name, payload)
conn:Disconnect()

Exactly five events, plus "*" for all of them. An unknown name is an error. Every payload carries spawner (the Spawner's entity id) and spawnerName (its entity name).

eventwhenpayload keys
waveStartedA wave began.spawner, spawnerName, wave, waves, name, total, rest, scale (scale = { count, pace, speed, health, damage })
waveClearedEvery enemy of a wave was spawned and is gone.spawner, spawnerName, wave, waves, name, killed, escaped, seconds
spawnedAn enemy appeared.spawner, spawnerName, enemy, kind, look, pattern, style (the same as pattern), effect, wave, position, reused
despawnedAn enemy left play and went back to the pool.the spawned keys plus reason: killed, escaped, expired, cleared or reset
allWavesDoneThe last wave was cleared.spawner, spawnerName, waves, killed, escaped, seconds
  • enemy is the enemy's entity id; position is where it appeared ({x, y, z}), in despawned too; reused is true when it came from the pool; wave is 0 for a trickle or a manual spawn.
  • waves is the number of waves the spawner will run, 0 for an endless one. seconds is from the wave's start (or, in allWavesDone, from start()) to the clear.
  • In waveCleared, escaped counts every enemy of the wave that was not killed. In allWavesDone, killed and escaped are the run's totals (escaped there counts escaped and expired enemies).
  • Events fire on every peer. The host fires them as it decides. Other peers fire the wave events when the Spawner's synced snapshot says so, and spawned/despawned when an enemy's synced spawn counter or active flag changes. A player who joins later does not get a replay of what already happened.
  • SK.eventCounts() tells how often each fired on this peer and the last 40.

Multiplayer

  • One peer is in charge of each spawner: the owner of its synced entity (normally whoever created it; this README calls it the host). Only it runs the waves, picks positions with its seeded random stream and spawns. Put the Spawner on an entity made with entity.spawnSynced; SK.addSpawner warns when it is not.
  • Enemies are synced entities owned by the host. The host moves them, applies their damage and decides when they die. Every peer builds each enemy's look locally from its synced kind and look, shows or hides it from active, and plays the spawn effect locally (juiceKit scope = "local") when the enemy's spawn counter seq changes, so every player sees the same effect at the same spot without an extra message. Turrets aim and draw their zaps locally on every peer; only the host's damage counts.
  • The snapshot: the host publishes what each spawner is doing (phase, wave, counts, pool, last events) in its synced snapshot field whenever something changes and at least twice a second. SK.state(sp) reads it, the same on every peer.
  • Calls from any peer: start, stop, reset, nextWave and spawn called on a peer that is not in charge are sent to the host on the channel spawnerKit:<entityId> (the Spawner's entity id) and carried out there. despawnAll, SK.despawn and SK.prewarm act only on the host; the setters (setPattern, setStyle, setEffect, setCurve, setWaves) write the Spawner's synced fields and are not forwarded, so call them where SK.isAuthority(sp) is true.
  • Host migration: every other peer checks the spawner's owner twice a second. When the owner has left (or nobody owns it), the lowest remaining peer claims the entity after 0.5 s (any peer after 4 s). The new host adopts the enemies it now owns from the pool and carries on from the snapshot: the same wave, the next spawn in the plan, the same kill counts.
  • What the kit does against duplicate or missing enemies: exactly one peer spawns. An entity no peer owns yet counts as the room host's (multiplayer.isHost()), so even then only one peer acts on it. Enemies are real synced entities, so every peer is meant to see the same set, and looks and effects come from their synced fields rather than from messages that could be lost. A new host resumes the current wave at the spawn after the last one the snapshot recorded; the one gap is a spawn made in the frame between the old host's last snapshot and its leaving. No duplicate enemy was ever seen in testing. Earlier releases saw new enemies reach a second player late; the engine issue behind that (#19353) is fixed. SK.syncReport() and the readout show, on every screen, whether the players see the same enemies (see Two-player check).

Two-player check

To see for yourself whether two machines show the same thing: open the world on two machines signed in to two different accounts, press Play on both, and read SK.syncReport() on each (the readout shows the same verdict on both screens). Every 2 s the host sends every other player a digest of its enemies and spawners, and each player compares it with its own view and counts missing, extra, duplicate, spawnSpot, drift, wave and peerSpawned problems. A difference counts only when it shows in two digests in a row, and the readout turns red only for a difference that is still there (a duplicate or a non-host spawn at once). multiplayer.explain(enemyId, "spawnerKit.Enemy", "active") says why a value is not arriving.

  • 1.1.0: checked on one machine only. The agent that prepared this release had one engine, cannot open a browser copy of the world (#20946), and a second engine on the same account joins as the same player (#14448). On that machine the README example played 6, 9 and 13 enemies in a brand-new world, and the kit's sync check reported no other player.
  • 1.0.0 (two machines, the desktop app and a browser tab): in every session only the host created enemies and no duplicate was ever seen. In the best session (the arena alone, three waves from threeWaves.data), the other player saw the same enemies with the same ids at the same spawn spots, live positions 0.1 to 0.6 m apart on average (worst 1 m, about one network update), and the same wave counters: 6, 9 and 13 on the steady curve. A browser tab running the full gallery at 6 to 10 fps fell a few seconds behind on reused enemies. Two kit bugs those sessions found are fixed: a player who was not in charge prewarmed pool enemies of their own when a MatchFlow round started, and a reused enemy could flash at its previous place on the other screen.

MatchFlow

Set the Spawner's matchEntity to the name of an entity carrying MatchFlow (format waves fits best) and the spawner plays inside its rounds:

  • the waves start when the round enters playing (with autoStart on);
  • each cleared wave calls the match's clearWave(), so a waves round with waves = 3 ends in victory when the third wave is cleared;
  • when the round leaves playing, the spawner resets: every enemy back to the pool (despawned with reason reset), ready for the next round. restartDelay is ignored.
  • If no peer runs the MatchFlow (its entity is owned by nobody and not in charge anywhere), the host plays the waves without it after 5 s and logs a warning.
local match = entity.spawnSynced("Match")
match.component.add("MatchFlow", { format = "waves", waves = 3, roundSeconds = 0, minPlayers = 1 })
SK.addSpawner(entity.spawnSynced("Arena", { position = A }), { waves = asset.resolve("arenaWaves", "data"), matchEntity = "Match" })

Give the readout match = "Match" to show the round's phase and cleared waves, and SecondWind's Rules matchEntity = "Match" so its round ends with MatchFlow's.

SecondWind

Health, damage and death are SecondWind's. Every enemy gets SecondWind.Vitals (and Lifeline's health) through HK.attach with model hitPoints, death style stay, team enemies and no fall damage; on every spawn its maximum health is set to kind health × curve × healthScale × the entry's health. So:

  • Hurt enemies with SecondWind: HK.damage(enemyEntity, 25, { by = attacker, type = "fire" }) from your weapons. A killed enemy lies there for 0.7 s, then goes back to the pool (despawned, reason killed). HK.explode, traps and SecondWind's hit effects all work on them.
  • Enemies hurt players with HK.damage (contact hits, the spitter's shots) and only chase players SecondWind says are alive, so give player bodies health: HK.attach(body, { team = "players" }), and one synced SecondWind.Rules entity in the scene.
  • healthBars draws Lifeline's bar over each enemy.

juiceKit

The spawn effects are juiceKit presets (see the Effects table) played with scope = "local" on every peer, plus the kit's own pooled shapes. The turret's sparks are local too; the spitter's shot plays juiceKit's vfxZap at the player it hits. juiceKit's global intensity and reduce-motion settings apply to all of them. Play an effect yourself, on this peer only, with SK.playEffect("portal", { x, y, z }, { size = 1.5 }).

Reference

Spawner component (on a synced entity)

All fields are synced.

fielddefaultmeaning
patternpointThe spawn pattern, how enemies arrive: point, area, ring, offscreen, path, portal, sky, burrow, trickle or scripted. Swap it and nothing else changes.
style""Older name for pattern. Empty lets pattern decide; a pattern id here is used instead of pattern. SK.addSpawner, SK.setPattern and SK.setStyle always write pattern and leave this empty.
effectautoSpawn effect every player sees: smoke, portal, beam, dirt, impact, sparkle or none; auto picks the pattern's own.
curvesteadyDifficulty curve: steady, steep, stepped, breather or flat. A curve named in the wave data wins.
curveStrength1How hard the curve bites: 1 as designed, 0 flat, 2 twice as steep.
wavesnoneA .data file of the waveTable contract: the waves this spawner plays.
waveTable{}Waves as a Lua table (set by SK.setWaves); used when waves is empty.
wavesToRun0How many waves to play: 0 = every wave in the table (endless when it loops).
loopfalseAfter the last wave, start the table over, harder each time (the curve keeps climbing).
enemygruntEnemy kind for a trickle, and for manual spawns that name none.
enemies""A trickle's mix: comma list of kinds it picks from in turn (empty = enemy).
looktoyHow the enemies look: toy, neon, or mixed (alternating).
points""Spawn points this spawner uses: comma list of point names or group names. Empty = the points whose group is this spawner's name, else every point.
pointOrdercycleWhen a spawn names no point: take the points in turn, or at random.
targetnearestWhom ring and offscreen spawn around: nearest, random, each (in turn), or the name of an entity.
rate1Trickle: spawns per second.
maxAlive12Most enemies of this spawner alive at once; a spawn waits until one is gone. 0 = no limit.
total0Trickle: stop after this many spawns (0 = endless).
trickleStep10Trickle: the difficulty curve goes up one level every this many spawns.
advanceclearedWhen the next wave's delay starts: once this wave is cleared, or once it has finished spawning.
autoStarttrueStart by itself when play begins (or when the MatchFlow round starts); when false, call start().
restartDelay-1Seconds after the last wave is cleared before the spawner starts again from wave 1; -1 = never (a MatchFlow round restarts it instead).
behaviorchaseWhat spawned enemies do: chase players, wander near where they appeared, march (path pattern), or hold still.
aggroRadius0Enemies only chase players within this many metres of the spawner; 0 = any distance.
wanderRadius4How far a wandering enemy roams from where it appeared, in metres.
goal""Name of a spawn point (or any entity) enemies head for when nobody is in reach; reaching it counts as escaping.
lifetime0Seconds an enemy stays before leaving by itself (reason 'expired'); 0 = never.
healthBarstrueDraw Lifeline's health bar over each enemy.
healthScale1Multiplies every enemy's health, on top of the curve.
speedScale1Multiplies every enemy's speed, on top of the curve.
damageScale1Multiplies every enemy's damage, on top of the curve.
ringRadius9Ring pattern: distance from the player, in metres.
offscreenMargin4Offscreen pattern: how far past the edge of the view, in metres.
offscreenDistance14Offscreen pattern: distance from the player, in metres.
skyHeight9Sky pattern: drop height, in metres.
burrowDepth1.6Burrow pattern: how deep they start, in metres.
pathSpread0.6Path pattern: sideways jitter so a column does not walk in single file, in metres.
showPathtruePath pattern: draw the smooth curve the enemies walk on the ground, on every peer (small local dots, rebuilt when the pattern or the points change).
prewarm0Make this many enemies of the first kind into the pool before the first spawn.
seed1Seed for every random choice the host makes.
matchEntity""Name of an entity with MatchFlow: waves start when its round starts, each cleared wave calls clearWave(), and a round ending resets the spawner.
snapshot{}Written by the host only: what the spawner is doing, for every other peer. Read it through getState().

Enemies that wander roam around the spot where they appeared; chase enemies measure aggroRadius from the spawner, head for goal when nobody is in reach, and wander when there is no goal. The path pattern always makes its enemies march their route; reaching the end counts as escaping.

Spawner methods

methodwhat it does
sp:start()Start from wave 1 (or start the trickle). On a peer that is not in charge the request goes to the host.
sp:stop()Stop spawning; enemies already out stay.
sp:reset()Stop, send every enemy of this spawner back to the pool (reason 'reset') and go back to before wave 1.
sp:nextWave()Skip the wait before the next wave.
sp:spawn(kind?, opts?) -> entity?Spawn one enemy now with this spawner's pattern and effect. opts: { point, look, health, speed }. Returns the entity on the host, nil elsewhere (the host spawns it).
sp:despawnAll(reason?)Send every enemy of this spawner back to the pool now (default reason cleared). Host only.
sp:setWaves(t) -> (ok, errors)Put waves in as a Lua table (the same shape as the waveTable data), replacing the data file. Takes effect at the next start().
sp:getState()What this spawner is doing, the same on every peer: phase (idle, waiting, spawning, clearing, trickle, done, stopped), running, wave, waves, name, spawned, total, alive, waveAlive, killed, escaped, spawnedTotal, nextIn, pool, entities, memoryKb, pattern, style (the same), curve, effect, host, error and the last event payloads.
sp:isAuthority() -> booleanWhether this peer is the one deciding and spawning for this spawner.
sp:alive() -> { id }The entity ids of this spawner's enemies in play.
sp:planWave(n)The wave plan this spawner would follow for wave n (who, when, from where), without spawning anything.

SpawnPoint component (on any entity; not synced)

Its transform is the spot. Every peer has the same scene and only the host reads it.

fielddefaultmeaning
group""Group name. A Spawner's points can name a group instead of single points; the points of one group, sorted by order, make a path.
order0Position along its group's path (lowest first).
kindpointWhich marker it draws: a pad, an area outline, a standing portal ring or a path dot. Every pattern can use every kind.
sizeX0Width of the area in metres (patterns area, sky and burrow pick a random spot inside); 0 = a single spot.
sizeZ0Depth of the area in metres.
showMarkertrueDraw the marker in play as well as in the editor.
colororangeColour of the marker.

Method: point:record() returns { name, pos, sizeX, sizeZ, yaw, group, order, kind }, what the placement maths reads.

Turret component (on any entity; not synced)

fielddefaultmeaning
range10How far the turret reaches, in metres.
interval0.7Seconds between shots.
damage15Damage per shot (SecondWind damage).
damageTypeelectricSecondWind damage type (physical, fire, ice, electric, poison), which picks the hit effect.
only""Only shoot enemies of this spawner (its entity name); empty = any enemy.
colorcyanColour of the turret's head and zap.

PoolReadout component (on any entity; local)

fielddefaultmeaning
spawner""Name of one Spawner to show; empty shows every spawner in the scene.
cornertopLeftWhich corner of the screen it sits in (topLeft, topRight, bottomLeft, bottomRight).
titlespawnerKit poolHeading of the readout.
maxSpawners4Most spawner rows to list.
match""Name of a MatchFlow entity whose round to show (phase and wave); empty shows none.

Method: readout:numbers() returns what it shows: { created, reused, active, pooled, entities, memoryKb, peer }.

Enemy component (added by the pool; you don't add it)

All fields are synced and written by the host.

fielddefaultmeaning
kindgruntEnemy kind id (grunt, runner, brute, flyer, spitter, or one a game defined).
looktoyHow it looks: toy or neon.
activefalseWhether it is in play; false means it is waiting in the pool, hidden.
seq0Bumped by the host each time this entity is spawned; every peer plays the spawn effect when it changes.
uses0How many times this entity has been spawned; above 1 means it was reused from the pool.
spawner""Entity id of the Spawner that spawned it.
spawnerName""Name of that Spawner, for events.
wave0The wave it belongs to (0 for a trickle).
stylepointThe spawn pattern that placed it (the field keeps the older name).
effectsmokeThe spawn effect every peer plays when it appears.
entrance{}How it enters: { pos, from, entrance, duration }.
route{}For the path pattern: the points of the smooth curve it walks, about 0.6 m apart.
behaviorchaseWhat it does once in play: chase players, wander near where it appeared, march its route, or hold still.
speed2.6Walking speed in metres per second (already scaled by the wave's difficulty).
damage10Damage per contact hit (or per shot for a spitter).
aggroRadius0Only chase players within this many metres of home; 0 = any distance.
home{}Centre of the area it guards or wanders in ({x, y, z}).
wanderRadius4How far from home a wandering enemy roams, in metres.
goal{}Where it heads when it has nobody to chase; reaching it counts as escaping ({x, y, z}, empty for none).
lifetime0Seconds before it leaves by itself (reason 'expired'); 0 = never.
goneReason""Why it last left play: killed, escaped, expired, cleared or reset.

Method: enemy:isAlive(), whether it is in play and alive.

spawnerKit.api (local SK = require("spawnerKit.api"))

Wherever a function takes a spawner (sp), it accepts the Spawner's entity, its entity name, or the component.

functionwhat it does
SK.addSpawnPoint(e, opts?) -> SpawnPointMake an entity a spawn point. opts: group, order, kind (point/area/portal/path), sizeX, sizeZ, showMarker, color.
SK.addSpawner(e, opts?) -> SpawnerMake an entity a spawner. Use a SYNCED entity (entity.spawnSynced). opts are any Spawner fields.
SK.addTurret(e, opts?) -> TurretAdd a defence turret that zaps enemies through SecondWind. opts: range, interval, damage, damageType, only, color.
SK.addReadout(e, opts?) -> PoolReadoutAdd the on-screen pool readout. opts: spawner, corner, title, maxSpawners, match.
SK.spawner(x) -> Spawner?The Spawner component of an entity, an entity name, an id or a component; nil when there is none.
SK.start(sp)Start a spawner from wave 1 (asks the host when called elsewhere).
SK.stop(sp)Stop a spawner; enemies already out stay.
SK.reset(sp)Reset a spawner: every enemy back to the pool, back before wave 1.
SK.nextWave(sp)Skip the wait before a spawner's next wave.
SK.spawn(sp, kind?, opts?) -> entity?Spawn one enemy now from a spawner, with its pattern and effect. opts: { point, look, health, speed }. The entity on the host, nil elsewhere.
SK.setPattern(sp, pattern)Swap a spawner's spawn pattern; takes effect from the next spawn.
SK.setStyle(sp, pattern)Older name of SK.setPattern; does the same.
SK.setEffect(sp, effect)Swap a spawner's spawn effect ("auto" follows the pattern).
SK.setCurve(sp, curve)Swap a spawner's difficulty curve.
SK.setWaves(sp, t) -> (ok, errors)Give a spawner waves as a Lua table (replacing its data file); takes effect at its next start.
SK.state(sp)What a spawner is doing (the same on every peer).
SK.isAuthority(sp) -> booleanWhether this peer decides and spawns for a spawner (the host).
SK.despawn(enemy, reason?) -> booleanSend an enemy back to the pool now. reason: "killed", "escaped", "expired" or "cleared" (default). Host only; returns false elsewhere.
SK.alive(sp?) -> { id }The ids of enemies in play: of one spawner, or of every spawner when sp is nil.
SK.isEnemy(e) -> booleanWhether an entity (or id) is a spawnerKit enemy (pooled or in play).
SK.validateWaves(t) -> (ok, errors)Check a wave table (Lua table or resolved waveTable data). Unknown enemy kinds are errors.
SK.planWave(t, n, opts?)Plan wave n of a table without spawning: { wave, name, delay, total, duration, rest, spawns = { { t, kind, point, look, index } }, scale }. opts: { curve = "steady", strength = 1, points = { "North" } }.
SK.loadWaves(ref)Read a waveTable .data asset (from asset.resolve("<name>", "data") or a Field.dataRef) into a plain table.
SK.curve(name, wave, strength?)A difficulty curve's multipliers for one wave: { count, pace, speed, health, damage, rest, level }.
SK.curveSeries(name, waves, strength?)A curve's multipliers for waves 1..n, for graphs.
SK.defineEnemy(id, def)Register an enemy kind for wave data. def: { health, speed, damage, size, hover, range, label, build = function(root, look) -> parts }.
SK.enemyKinds() -> { id }Every enemy kind id, sorted.
SK.poolStats()The pool's counters on this peer: { created, reused, released, active, pooled, peakActive, entities }.
SK.prewarm(kind, n, look?)Make enemies of a kind into the pool ahead of time, until n wait there. Host only.
SK.on(name, fn) -> connListen to a kit event on this peer; conn:Disconnect() stops it.
SK.eventCounts()How many times each event fired on this peer, and the most recent ones.
SK.catalog()Everything the kit offers, labelled: patterns (styles), effects, curves, enemies, looks, events, vocabulary and version.
SK.find(query?) -> { entry }Catalog entries matching labels. Keys: kind, family, genre, tag, id; each a value or a list.
SK.vocabulary()The words the catalog's labels use: kinds, families per kind, genres.
SK.playEffect(id, pos, opts?)Play a spawn effect on this peer at a point. opts: { size, target }.
SK.effectStats()Effect counters on this peer: played, shapes made, shapes reused, live, pooled.
SK.syncReport()Whether every player sees the same enemies. On a non-host peer, its own verdict against the host's latest digest; on the host, the verdict each other peer sent back. Counts missing, extra (duplicates included), duplicate, spawnSpot, drift, wave and peerSpawned problems, each once, with the last few as text.
SK.syncCheck(opts)Tune the cross-peer check: { enabled = true, interval = 2, grace = 1.5, tolerance = 1.5 }.

Constants: SK.VERSION ("1.1.3"), the component assets SK.SPAWNER, SK.SPAWN_POINT, SK.ENEMY, SK.TURRET, SK.READOUT, and the id lists SK.EVENTS, SK.PATTERNS (also SK.STYLES), SK.EFFECTS, SK.CURVES, SK.LOOKS. The pure modules are reachable as SK.waves, SK.curves, SK.placement, SK.pool and SK.util.

Tests

The kit's test suite is spawnerKit (91 tests, every public call). Run it in edit mode from the shell with zero tests run spawnerKit, or from Luau with:

tools.use("tests", "run", { suite = "spawnerKit" })

For 1.1.3 it passed 92 of 92 on the engine of 2026-11-03.

Known limits

Open engine and platform issues spawnerKit is affected by:

  • Testing two players from one account (OrigoZero/zero#14448). Two engines signed in to the same account collide as one player. To see what a second player sees, join with a second account.
  • Frame rate with many synced things (OrigoZero/zero#20750). In a multiplayer session the frame rate drops as the number of synced entities grows, and every enemy (pooled ones included) is one synced entity. Keep maxAlive and prewarm modest, most of all for a browser tab.
  • Shared enemies after a lost connection (OrigoZero/zero#19490). When both players lose their connection, pressing Play again does not rebuild the scene's shared objects (spawners, MatchFlow, health rules), so no spawner runs. The gallery guards against it: its entrypoint has the room's host recreate any missing shared objects at play start (galleryShared), and a game that builds its spawners with entity.spawnSynced in a scene build can do the same.
  • Long waits on test runs (OrigoZero/zero#19849). A call that waits on the test suite can be handed back as a background task to wait on.
  • Browser builds are not checked by an agent (OrigoZero/zero#20946). An agent cannot open its own copy of the world in a browser, so this release's checks ran in the desktop app.
  • Slow installs (OrigoZero/zero#21420). spawnerKit brings four kits with it, and an install with several dependencies takes a while; "waiting for content" and has no root to resolve against lines while it lands settle by themselves.
  • ZeroMind description one release behind (OrigoZero/zero#19258). The description ZeroMind shows for the package can lag a release behind package.yaml; the package itself is current.
  • Guides not in library search yet (OrigoZero/zero#22181, ZeroMind#3099). The two guides arrive with every install and open by their guide path, but a ZeroMind library search does not find them until this is fixed.
  • Guides by their whole path (OrigoZero/zero#22286). A package guide opens by its package folder and guide name (spawnerKit.package/how-to-spawn-waves-of-enemies), not reliably by its short name.
  • Searching guides from a script (OrigoZero/zero#22291). From Luau the search takes q (tools.use("guides", "search", { q = "spawn waves" })), where the guides tool and the guide panel take query. Reading one by its path is the same everywhere: tools.use("guides", "read", "spawnerKit.package/how-to-spawn-waves-of-enemies").
  • Guides in a search of this world only (OrigoZero/zero#22315). A guides search limited to the world's own content (from = "bound") misses the guides inside its packages; search everything, or open them by path.

Limits of spawnerKit's own design:

  • Offscreen knows only the host's own camera. Other players' cameras live on their own machines and are never sent. When the target is the host's own player, the offscreen pattern uses the host's real camera (its direction, field of view and aspect). For any other target (another player, or a named entity) it assumes a 60-degree, 16:9 camera looking along the target's facing, so with a free-orbiting camera an enemy can now and then appear inside that player's view. Raise offscreenMargin for more room, or use the ring pattern.
  • Cost per live enemy. SecondWind's Vitals costs roughly 0.05 to 0.3 ms per live enemy per frame on desktop. On the engine of 2026-11-01 the full gallery (23 spawners, about 30 enemies in play, 52 labels) ran at a median of about 46 ms a frame on desktop, with SecondWind's Vitals the largest single script cost. Pooled enemies have their health components switched off and cost nothing. Keep maxAlive modest, especially in a browser tab.
  • Simple movement. Enemies move kinematically on the spawner's ground height: no physics, no gravity, no pathfinding around walls. Use open arenas, path curves through gaps, or behavior = "hold" with your own movement. A path curve passes through every one of its points and swings round sharp corners; space the points out for gentle bends.
  • Damage numbers are all or nothing. Lifeline draws floating damage numbers for every enemy on screen or for none (its HUD's showNumbers); a number can drift across a 3D label behind it. The gallery turns them on only while you are inside the arena, so the station labels stay clear.
  • Bandwidth. The gallery, with 23 spawners and 30 to 40 enemies in play, sends about 110 KB/s and 43 messages a second from the host. Most of that is moving enemies' positions and Lifeline's one message per hit (a limit of the health kit, see SecondWind's README); the live curve pens keep their enemies standing still and their turrets slow to keep their share small. A game with one or two spawners and fewer enemies sends far less. Each Spawner publishes its state at most 5 times a second, and otherwise every 2 s.
  • Small screens. From the gallery's start position, the label titles are readable on a phone held sideways, but the one-line subtitles and the live lines under the curve boards are only a few pixels tall there; walk towards a row to read them. On a desktop window every label is readable from the start, below MatchFlow's timer and wave banner.
  • MatchFlow's screens cover the middle between rounds. In the gallery, when the arena's third wave is cleared, MatchFlow's results screen and then its "next match in" panel fill the middle of the screen for about 10 s (its resultsSeconds and breakSeconds), then the next round starts. Set showUi = false on your MatchFlow to draw your own from its state.
  • Web browser. The gallery runs in a browser tab: the models and labels are built and running there, the same as on desktop, and the tab was the host of the two-player session. It runs much slower (about 10 fps against 30 to 40 on desktop with the full gallery), so keep maxAlive modest on the web. In the editor, the Scene view's camera menu must read Active camera in play: if it is set to the editor camera, play keeps drawing from the editor's fly camera and the gallery appears to be empty.
  • Scene rebuilds and old entities. When a build re-places an entity whose component values were changed outside the build, the scene builder can keep the old values or refuse the add. SK.addSpawner, SK.addSpawnPoint, SK.addTurret and SK.addReadout update a component that is already there. If a rebuild still reports already has a 'spawnerKit.…' component, rename that entity in your build.

Version history

  • 1.1.3: A player who joins sees each enemy with its own look. A peer that receives an enemy before its game has defined the enemy's kind (a player joining a running game) built the fallback (grunt) look and kept it for good, so a kind with a look of its own, or none, showed four green blocks there and not on the host. An enemy now rebuilds its look whenever its kind's definition changes, a definition that arrives late included, in play and while authoring. Found with navKit's Pathwise gallery, whose pedestrians are a kind with no body. A test for it (92 tests).

  • 1.1.2: The wave survival guide, corrected again after a player followed it. When you fall, every enemy of the old run now vanishes. Before, enemies still walking when the run reset were written back into the arena by navKit (aiKit's movement) and stood there frozen, some getting counted again in the next run. The guide's step 6 now tells navKit whenever spawnerKit moves an enemy (syncWalker, on spawned and despawned), the same way aiKit moves a character home. Checked three times in a row: falling with 10 enemies alive left none standing or counted, and every enemy of the new wave 1 came out of a portal. The guide now names the controls (W, A, S, D to move, Shift to run, Space to jump, right mouse button and drag to turn, F to shoot), says the readout appears once you press Play, and describes the brute as it really fights: it charges and smashes above 60% health, roars and backs off to shoot volleys from 8 to 14 m between 60% and 30%, and roars again and goes berserk below 30%. Everything that already worked (the shot, the wave sizes, the clean paste) is unchanged. Tests: 91 of 91, twice in a row. SK.VERSION is "1.1.2".

  • 1.1.1: The wave survival guide, corrected after a player followed it. Your gun is now the guide's own level shot: F fires from your chest straight ahead the way your camera faces (left and right only; tilting the camera changes nothing), so gunners 6 to 11 m away and the big brutes are hit as easily as a raider next to you. Before, the shot followed the camera's downward tilt and fell short of anything past about 6 m. The guide now says that wave 3 brings two brutes (the data asks for one; the steady curve's x1.3 on wave 3 rounds it up to 2) and how aiming works, and step 4 no longer adds an aiKit import the build never uses, so the pasted files check clean. Followed again step by step in a brand-new world. Tests: 91 of 91, twice in a row. SK.VERSION is "1.1.1".

  • 1.1.0: Two guides in the package: How to spawn waves of enemies (spawners and spawn points, waves and schedules, budgets and difficulty curves, items and pickups, despawning, limits and pooling, multiplayer) and Build a wave survival arena where every wave brings more and tougher enemies (with aiKit and SecondWind, followed step by step in a brand-new world). Install is now one call: spawnerKit brings SecondWind, Lifeline, MatchFlow and juiceKit with it (the engine fixed the install problems behind the old three-call order and repair steps). The README example now says to replace the scene's build.luau, which is how it was always checked. Known limits name only open issues. One fix: every Spawner counted all of the scene's entities on its own every 2 s for its snapshot, all on the same frame; the count is now taken once every 2 s and shared, which took the gallery from a median of about 135 ms a frame to about 46 ms on desktop. Tests: 91 of 91, twice in a row, after that fix. SK.VERSION is "1.1.0".

  • 1.0.0: First release: 10 spawn patterns picked with the Spawner's pattern setting (style is its older name and still works), the path pattern walking a smooth curve built with the engine's spline module, 7 spawn effects, 5 difficulty curves, 5 sample enemies in 2 looks and custom kinds, waves as spawnerKit.waveTable data, a shared enemy pool with prewarm and the created-vs-reused readout, five events on every peer, host-authoritative multiplayer with host migration, turrets, and MatchFlow, SecondWind and juiceKit integration. A gallery world shows every pattern, effect and curve live, with a live pen per curve and an arena playing three waves inside a MatchFlow round with its screens on.