# wavePreviewKit.layout
Sizes the wave preview for the screen it is on. `compute(w, h, safe, touch)` returns the usable width and height inside the safe area, a margin, `compact` (under 760 x 460 points), `tiny` (under 440 wide), `portrait`, a scale and whether buttons must be touch-sized; `measure()` does the same for the live screen. `root(layout, anchor, panel, offset)` wraps a panel in a transparent full-screen root that pins it to one of eight anchors and takes no pointer itself. Used by the api, the styles and the tests.
# wavePreviewKit.model
The pure half of the kit, with no screen access, so the tests read it directly. `summarise` / `summariseWave` turn waves in spawnerKit's waveTable shape (enemies or script), an already-summarised `groups` shape, a `{ kind = count }` map or a spawnerKit plan into `{ index, name, total, boss, groups }` with same kinds merged in order. `newKinds` / `kindInfo` resolve how an enemy kind looks through a provider map or function with a fallback, normalising labels, plurals, colours, tags, trait maps and the vector-icon archetype. `normaliseState`, `clock`, `counter`, `composition`, `line`, `buttonText` and `progress` format the state for every style. Called by the api and the styles.
# creepsKit.api
The one interface to creepsKit: `local Creeps = require("creepsKit.api")`. `register()` defines the eleven kinds with spawnerKit, hooks armour into SecondWind's damage filter, feeds turretsKit (when installed) each creep's layer and stealth, and starts the one shared tick. Styles (`setStyle`, `setSpawnerStyle`, `mapLook`, `styleFor`), the catalog (`catalog`, `get`, `find`, `define`, `reload`), live creeps (`kindOf`, `isHidden`, `phaseOf`, `targetInfo`, `spawnFrom`), events (`on`, `eventCounts`), `setDamageFilter` to chain a game's own filter, and `stats`. Games, wave-preview UIs and tower defense kits call it; see the package README for every function.
# wavePreviewKit.styles
The six looks of the wave preview, as pure widget-tree builders: `strip`, `timeline`, `cards`, `dial`, `minimal` and `pixel`. `build(style, view, layout, theme)` returns the panel and its footprint `{ w, h }` (which the tests check against phone and desktop screens); `theme(style, overrides)` merges colour overrides into a style's palette; `LIST` is the style catalog with tags and when to use each; `CALL_ID` is the callback id of the call button. Countdown-driven sizes and angles carry CSS transitions as long as the gap to the next rebuild, so motion stays smooth while the tree is rebuilt about once a second. Called by the api; reach for it to render a style somewhere else.
# wavePreviewKit
An on-screen **wave preview** for any wave-based game: tower defense, horde mode, wave shooters, arena survival. Players always know what is coming next: **which enemies and how many**, the **wave counter**, a **countdown** to the next wave, and a **"start next wave / call early" button** (with the bonus for calling early) that also answers to a key, a gamepad button (with the right Xbox / PlayStation / Switch prompt) and touch. Six looks swap live with one word. It needs no tower defense kit: feed it waves and state from anything, or bind it to a spawnerKit Spawner in one line.
**Install and use in two lines:** run `zero zeromind installAsset 67700fda-b723-4db2-9291-c308f157eead` in the engine shell, then call `require("wavePreviewKit.api").bindSpawner("Spawner")` with spawnerKit, or feed it waves and state yourself as below.
## Quick start
```lua
local WP = require("wavePreviewKit.api")
WP.setWaves({ { name = "Scouts", enemies = { { kind = "grunt", count = 6 }, { kind = "runner", count = 4 } } } }) -- spawnerKit's waveTable shape
WP.show({ style = "strip" }) -- per-player HUD
WP.setState({ wave = 0, waves = 10, phase = "build", nextIn = 20, canCall = true, callBonus = 25 })
WP.onCall(function(info) startNextWave(); gold += info.bonus end) -- button, N key, pad Y/triangle, tap
```
With spawnerKit, one line instead: `WP.bindSpawner("Spawner", { callBonus = 25 })`. No code at all: add the **WavePreview** component to any entity in the scene and set its `style` (and `spawner`).
## The six styles
Swap any time with `WP.setStyle(id)`; the new look plays its entrance and keeps all state.
| id | looks like | use it when |
|---|---|---|
| `strip` (default, top) | A glass bar: the wave counter, "next in 0:15", the next wave's enemies as glowing icon badges with ×counts and names, the call button, and a thin countdown line. | The everyday choice for any wave game: readable at a glance, one row tall (two rows on a portrait phone). |
| `timeline` (top) | A track of the next 4-7 waves: cleared waves ticked, each upcoming wave's lead enemy and total above its node, boss waves crowned in red, and a marker gliding toward the next node as the countdown runs. | Players plan ahead (tower defense with long builds), or you want boss waves visible from far off. |
| `cards` (top right) | A card per upcoming wave (3 on desktop, 2 on a landscape phone, 1 upright): every enemy with icon and ×count, trait pills (FLYING, ARMOR, BOSS...), the total, and on the next card its countdown bar. | Strategy-heavy games where the enemy mix decides what to build (armour, fliers, healers). |
| `dial` (top right) | A circular clock that fills toward the next wave with the wave number in its heart, the next wave's enemies orbiting it with counts, the wave name and a round call button. Turns red for a boss wave. | A striking corner piece for arena, horde and sci-fi games; the timer matters more than the details. |
| `minimal` (top) | One pill-shaped line: `Wave 4/10 · next: 12 runners, 2 brutes · 0:15` and a small call button. Shortens itself to fit a phone. | Clean HUDs, small screens, or when the preview should stay out of the way. |
| `pixel` (top) | A chunky retro panel drawn in its own 5x7 bitmap font with 8x8 pixel enemy sprites, a stepped block countdown and a blinking call button with a pixel prompt. | Pixel-art, arcade and retro games. |
`WP.catalog()` lists the same with tags (`WP.catalog({ tag = "retro" })`).
## Enemy looks
Waves name enemies by `kind` id. How a kind looks (label, plural, icon, colour, tags, traits, boss) comes from, in order:
1. Your provider: `WP.setKinds({ ogre = { label = "Ogre", color = "#c0503a", icon = "☠", tags = { "tank" } } })` or `WP.setKinds(function(kind) return myCatalog[kind] end)`.
2. **creepsKit**'s catalog when it is installed (`require("creepsKit.api").catalog()`: label, icon/glyph, colour, tags, traits, layer).
3. **spawnerKit**'s catalog (its sample grunt, runner, brute, flyer, spitter).
4. The id itself ("fire_imp" → "Fire imp", a stable colour).
Icons need no textures. A kind's own `svg` wins, then its `icon` glyph (pictographic emoji draw as vectors instead, since no colour emoji face is guaranteed), then one of 12 built-in vector icons picked from the id, tags and traits: walker, fast, heavy, flying, ranged, boss, healer, shield, armor, stealth, splitter, swarm. The pixel style has an 8x8 sprite for each.
## API
`local WP = require("wavePreviewKit.api")`
| call | what it does |
|---|---|
| `WP.show(opts?)` | Show the preview on this peer. opts: `style`, `anchor` (top, topLeft, topRight, bottom, bottomLeft, bottomRight, left, right), `showButton` (true), `theme` (colour overrides), `key` ("KeyN"), `padButton` ("north" = Y / triangle / X), `offset = { x, y }`, `layer` (60). |
| `WP.hide()` | Take it down (state, waves and handlers are kept). `WP.isShown()`. |
| `WP.setStyle(id)` / `WP.style()` | Swap the look live: strip, timeline, cards, dial, minimal, pixel. |
| `WP.setAnchor(anchor?)` | Move it; nil = the style's own default. |
| `WP.setTheme(t?)` | Override colours: `accent, panel, panel2, edge, ink, dim, danger, track, button, buttonInk`. |
| `WP.setShowButton(on)` | Show or hide the call button (its key and pad button follow). |
| `WP.setWaves(list)` | spawnerKit's waveTable shape (`{ { name, enemies = { { kind, count } }, script = {...} } }`, or `{ waves = {...} }`), or already summarised: `{ { name, groups = { { kind, count } } } }`, or `{ enemies = { runner = 12 } }`. Same kinds in one wave merge. |
| `WP.waves()` | The summarised waves: `{ index, name, total, boss, groups = { { kind, count, info } } }`. |
| `WP.setKinds(mapOrFn?)` / `WP.kind(id)` | The enemy-look provider (see above) / what one kind resolves to. |
| `WP.setState(s)` | `{ wave, waves (0 = endless), phase = "build" \| "wave" \| "done", nextIn (seconds or nil), nextTotal?, canCall, callBonus }`. Partial updates keep the rest. The countdown runs on locally, so setting `nextIn` once per wait is enough. |
| `WP.state()` | The state as shown now (nextIn counted down). |
| `WP.onCall(fn)` → `{ Disconnect }` | `fn(info)` when the player asks for the next wave: `info = { source = "button" \| "key" \| "pad" \| "code", wave, next, bonus, nextIn }`. Only fires while `canCall` is true. |
| `WP.call()` | Press the call button from code. |
| `WP.bindSpawner(sp, opts?)` / `WP.unbindSpawner()` | Follow a spawnerKit Spawner (entity, name or component): its waves are planned with its difficulty curve (`planWave`), its phase/wave/countdown are read five times a second, and the button starts it, then skips each wait (`SK.start` / `SK.nextWave`) unless `opts.onCall` is given. `opts.callBonus` is a number or `fn(state)`. |
| `WP.catalog(filter?)` | The styles: `{ id, label, anchor, tags, description }`. |
| `WP.view()` / `WP.preview(style, w, h, safe, touch)` | The data a style draws / build a style's panel for any screen size without showing it (tests, custom layouts). |
| `WP.simulateScreen(w, h, safe, touch)` | Lay out as if on that screen (nil = the real one). |
| `WP.stats()` / `WP.reset()` | `{ builds, calls, shown, style, device, footprint }` / back to defaults. |
| `WP.VERSION`, `WP.STYLES`, `WP.ANCHORS`, `WP.SCREEN` | "1.1.8" (the released version), the style ids, the anchors, the UI screen name (`wpk_hud`). |
Phases: `build` = waiting for the next wave (the counter shows the upcoming wave), `wave` = a wave is running (the counter shows it; the preview shows the one after), `done` = all waves cleared.
## How it behaves
- **Per player.** Each peer shows its own preview; nothing here is synced. Feed every peer the same state (a bound Spawner's state is already the same on every peer, and `SK.nextWave` from any peer reaches the host).
- **Cheap.** The widget tree is rebuilt only when something it shows changes: the countdown's seconds, the wave, the phase, the screen size, the input device. That is about once a second during a countdown, and never while nothing moves. Between rebuilds, bars, the dial and the timeline marker glide with CSS transitions, so motion is smooth with no per-frame work.
- **Phone-safe.** Sized from `ui.screenSize()` inside the safe area: compact under 760 points wide or 460 tall, two rows on a portrait phone, fewer cards and timeline nodes, touch-sized (48 pt) buttons and no key glyph on touch devices. Tested at 1280x720, 390x844, 844x390 and 360x640.
- **Input.** The button takes mouse and touch; `key` and `padButton` call too (ignored while a text field has the keyboard). The prompt glyph follows the last device used, Xbox / PlayStation / Switch from the pad's name, drawn by controlsKit when it is installed.
- **Motion.** Each new wave's pieces enter with a short staggered rise; the number counts in; the boss wave pulses; the pixel button blinks while it waits for you.
## Parts
| part | what it is |
|---|---|
| `api` | The public API above, the per-peer HUD loop, input, the spawnerKit binding. |
| `model` | Pure: summarising waves, kind lookup, state normalising and every text the styles print. |
| `styles` | The six builders, themes and the style catalog. |
| `layout` | Screen size, safe area, compact/tiny, anchors. |
| `icons` | 12 vector enemy icons and their 8x8 pixel sprites. |
| `pixelFont` | A 5x7 bitmap font drawn as canvas rects. |
| `gallery` | Sample waves and kinds, `pose()` for screenshots, and a demo wave loop. |
| `WavePreview` component | No-code: put the preview up from a scene, optionally bound to a Spawner. |
| `wavePreviewKit` test suite | 26 tests. `tools.use("tests", "run", { suites = { "wavePreviewKit" } })` in edit mode. |
| guide `how-to-show-upcoming-waves` | How to add the preview to a game, step by step. |
The demo scene `scenes/wavePreviewGallery.scene` runs an 8-wave sample and cycles all six styles every 8 seconds (◀ ▶ step through them by hand).
## Version history
- **1.1.8**: documentation only, no change to the preview: a store description that names all six styles and how to install and use the kit, and the same install-and-use line at the top of this README.
- **1.1.7**: while a wave is on the road, the enemies shown beside it are tagged as the next wave, so wave 2's runners never read as part of wave 1: the strip and pixel styles put "NEXT · WAVE 2" over them, the timeline footer and the dial caption start with "NEXT ·", and the next card in the cards style says "NEXT" instead of "AFTER THIS" beside the clock's "LIVE".
- **1.1.6**: released against controlsKit 1.3.1 (the release economyKit 1.2.9 carries), so a world that installs it beside towerDefenseKit and economyKit holds one controlsKit instead of one per release.
- **1.1.5**: "LIVE" shows once while a wave runs. The pixel style read "LIVE LIVE", the timeline "WAVE LIVE LIVE" and the dial "WAVE LIVE" over its number with "LIVE" under it; now the pixel style shows one large "LIVE", the timeline "WAVE LIVE" and the dial "WAVE", the number and "LIVE". The README heading names no version (it had said 1.0.0); `WP.VERSION` carries it.
- **1.1.4**: the strip style sizes each enemy chip to fit its own name and keeps 10 points between names, so three long names ("FOOTMEN", "SHIELDBEARERS", "HEALERS") no longer run into each other; as many chips as fit at their real widths are shown, then "+N". Each name is a label with its own id (`wpk_chip_name_<wave>_<i>`), so a layout check can measure it.
- **1.1.3**: enemy names read right in the singular and the plural in every style. A kind that says its own `plural` (creepsKit 1.3.0 gives every kind one) is used as is, and the English rule leaves words that already read as plural alone ("Shielded", "Undead"), so no "Shieldeds". A new test renders every creepsKit kind, one and several, in all six styles.
- **1.1.2**: an offset in y (`WP.show({ offset = { y = 60 } })`, to step below a pause button, say) also takes that much height off the panel, the way an offset in x already took width.
- **1.1.1**: the dial's enemy icons orbit wholly outside the ring, so they never cover the WAVE label or the countdown (the dial face has the id `wpk_dial_face` for layout checks). `WP.show({ offset = { x, y } })` now also takes the sideways offset off the panel's width, so a wide style (strip, timeline) placed beside a game's own HUD never runs back over it.
- **1.1.0**: no backdrop blur behind the panels by default (a full-screen GPU pass, ~3 ms a frame on a modest GPU); `styles.BLUR = true` brings it back.
- **1.0.0**: six styles, spawnerKit binding, creepsKit and spawnerKit catalog fallbacks, key / pad / touch calling, phone layouts, 26 tests.
# creepsKit
Eleven tower-defense enemy kinds for **Wavecaller spawnerKit**, each with its own job in a wave and its own trait, drawn in four styles: fantasy, sci-fi, cartoon and pixel (ids `medieval`, `scifi`, `toy`, `pixel`; the first three match **turretsKit**'s tower styles). Register once, then name the kinds in any spawnerKit wave table. It works in any spawnerKit game: tower defense, horde mode, arena; with turretsKit installed it also tells the towers which creeps fly and which are stealthed.
**Install and use in two lines:** run `zero zeromind installAsset 62fb40cb-1b0c-49ab-9a60-726f26b6dbca` in the engine shell, then call `require("creepsKit.api").register()` on every peer and name the kinds in any spawnerKit wave table, as the quick start shows.
| kind | icon | role | trait |
|---|---|---|---|
| `runner` | 💨 | fast, fragile scout (30 HP, 4.6 m/s) | none: speed is the threat |
| `footman` | ⚔️ | the baseline (70 HP, 2.6 m/s) | none |
| `brute` | 🛡️ | big, slow tank (260 HP, 1.5 m/s) | **flat armour 8**: takes 8 off every hit (at least 15% always lands; poison goes around) |
| `swarm` | 🐜 | tiny and cheap (12 HP), comes in dozens | none: splash food |
| `shielded` | 🔰 | 80 HP behind a 90-point **shield bubble** | the bubble soaks damage first and recharges 25/s after 3 s without a hit; electric does double to it |
| `flier` | 🦇 | hovers 2.4 m over the path | **air layer**: only towers that hit air may target it; walls do not stop it |
| `healer` | ✚ | support (90 HP) | every 2.5 s a **green pulse** heals every creep within 5 m by 14 |
| `splitter` | 🫧 | lumpy blob (140 HP) | **splits on death** into 3 `splitling`s that walk on **from where it died** |
| `splitling` | • | what a splitter bursts into (35 HP, fast) | only made by splitters (`spawnable = false`) |
| `sneak` | 👁️ | stealthed (60 HP, 3 m/s) | **untargetable** while hidden; revealed for 2.5 s when hit (splash, clouds, flames), or while a tower that detects is in reach |
| `boss` | 👑 | the Warlord (2400 HP, armour 6) | **phases**: at 66% it enrages (×1.7 speed); at 33% it bursts a shield (20% of its health) and summons 6 swarm around itself |
Every kind also carries a suggested `bounty` (gold for a kill) and `leak` (lives lost when it gets through). All numbers live in `.data` files a designer can edit (`kinds/*.data`, contract `creepsKit.creepKind`).
## Quick start
In code that runs on **every peer** in play, such as your scene's `entrypoint.luau`:
```lua
local Creeps = require("creepsKit.api")
function onLoad()
Creeps.register() -- defines the kinds with spawnerKit, starts the shared tick
Creeps.setStyle("medieval") -- optional: this peer draws medieval creeps
end
```
Then use the kinds in any spawnerKit wave table (a `.data` file of the `spawnerKit.waveTable` contract, or `SK.setWaves`):
```yaml
contract: spawnerKit.waveTable
values:
waves:
- name: Mixed
enemies:
- { kind: runner, count: 4, gap: 0.5 }
- { kind: healer, count: 1 }
- { kind: brute, count: 2 }
- { kind: swarm, count: 12, gap: 0.2 }
- { kind: flier, count: 3 }
- name: The Warlord
enemies:
- { kind: sneak, count: 4 }
- { kind: boss, count: 1 }
```
A spawner with `pattern = "path"` walks them along its route. That is all; armour, shields, healing, splitting, stealth and boss phases run by themselves.
## Styles
Four styles. Each has an id and the theme name it also answers to; either works everywhere a style is taken (`setStyle`, `setSpawnerStyle`, `mapLook`, `looks.build`, `looks.shape`), and `Creeps.styleFor` always answers the id.
| theme | id | alias | look |
|---|---|---|---|
| Fantasy | `medieval` | `fantasy` | orcish skin, cloth, steel helmets, spears and shields, gold trim (turretsKit's medieval) |
| Sci-fi | `scifi` | | gunmetal bodies with glowing visors and accents in the kind's colour (turretsKit's scifi) |
| Cartoon | `toy` | `cartoon` | bright plastic, big round eyes (turretsKit's toy) |
| Pixel | `pixel` | `voxel` | chunky axis-aligned blocks in a snapped flat palette (5 levels a channel), glowing block eyes; nothing round on the body |
Swapping every enemy in a game is one word: `Creeps.setStyle("pixel")` (or `"fantasy"`, `"scifi"`, `"cartoon"`). `Creeps.resolveStyle(name)` maps a name to its id; `Creeps.STYLE_ALIASES` lists the aliases.
A kind keeps one silhouette and its colour in every style, so it reads the same from a top-down camera 25 to 40 m away: the wide brute with spiked shoulders, the winged flier with a shadow under it, the healer's glowing staff, the cyan bubble, the crowned boss with a glowing ring.
Which style a creep draws in, on this peer, first match wins:
1. `Creeps.setSpawnerStyle(spawnerName, style)`: that spawner's creeps (a pooled creep restyles if another spawner reuses it).
2. `Creeps.setStyle(style)`: every creep (`"auto"`, the default, skips this step).
3. The spawner's spawnerKit `look` through `Creeps.mapLook(look, style)`: by default `neon` draws `scifi`.
4. turretsKit's world style (`TK.setStyle`), when turretsKit is installed, so creeps match the towers.
5. `toy`.
Styles are drawn locally, so call these where every peer runs. `Creeps.styleFor(look, spawnerName)` says what applies.
## turretsKit: air and stealth
When turretsKit is installed, `register()` installs turretsKit's target info hook (`TK.setTargetInfo`), so every creep reaches the towers with its `layer` (`"air"` for fliers, lifted to their drawn height so shots meet the model), `hidden` (a sneak not revealed) and, for splitlings, their real progress along the whole route (so "first" targeting stays right). turretsKit then:
- lets a turret type pick only the layers in its `hits` list (`["ground"]`, `["air"]`; empty = both, which is every stock turret);
- skips hidden targets unless the turret `detects` (within its `detectRange`);
- keeps splash, clouds and flames hurting hidden creeps in a layer the turret hits (that is how a blast reveals a sneak), and lets fliers pass over walls.
creepsKit also reveals a sneak for **every** tower while a detecting turret is in reach (its `detectRange`, or its range, plus the kind's `detectRadius`). Make towers that use it:
```lua
local TK = require("turretsKit.api")
TK.define("cannon", { hits = { "ground" } }, "cannon") -- fliers pass over the cannon
TK.define("watchtower", { label = "Watchtower", detects = true, detectRange = 10 }, "sniper")
```
Without turretsKit, creepsKit loads and runs the same (the `require` is optional); call `Creeps.targetInfo(id)` from your own targeting to get the same answers.
## API (`local Creeps = require("creepsKit.api")`)
| function | what it does |
|---|---|
| `Creeps.register()` | Define every kind with spawnerKit (`SK.defineEnemy`), put armour into SecondWind's damage filter, install the turretsKit hook when present, start the one shared tick. Call on every peer; safe to call again. |
| `Creeps.isRegistered()` | Whether register ran here and its tick is alive. |
| `Creeps.unregister()` | Stop the tick and remove the hooks (kinds stay defined). |
| `Creeps.reload()` | Re-read the kind `.data` files and redefine the kinds. |
| `Creeps.catalog(opts?)` | Every kind in order: `{ id, label, description, icon, glyph, color, rgb, tags, traits, layer, stealth, health, speed, armor, bounty, leak, size, damage, hover, spawnable, order }`. `opts.spawnable = true` leaves out the splitling. |
| `Creeps.get(id)` | One catalog entry, or nil. |
| `Creeps.find(query)` | Entries matching `{ tag, trait, layer, stealth, id }` (each a value or a list). |
| `Creeps.define(id, def, base?)` | Add or replace a kind in code (shaped like a kind file's values; `base` copies another kind). |
| `Creeps.setStyle(style)` / `Creeps.style()` | This peer's style: `medieval` (`fantasy`), `scifi`, `toy` (`cartoon`), `pixel` or `auto`. |
| `Creeps.resolveStyle(name)` | The style id a name or alias stands for, or nil. |
| `Creeps.setSpawnerStyle(name, style?)` | One spawner's creeps in a style on this peer. |
| `Creeps.mapLook(look, style?)` | Map a spawnerKit look to a style while the style is `auto`. |
| `Creeps.styleFor(look?, spawnerName?)` / `Creeps.styles()` | The style that applies; every style `{ id, label }`. |
| `Creeps.kindOf(entity)` | The catalog entry of a live creep, or nil. |
| `Creeps.isHidden(entity)` | Whether a sneak is hidden right now (same on every peer). |
| `Creeps.phaseOf(entity)` | A boss's phase, 1 to 3. |
| `Creeps.targetInfo(id, cand?)` | `{ layer, hidden, lift?, progress? }` for a creep; what turretsKit is fed. |
| `Creeps.spawnFrom(parent, kind, count, spread?, opts?)` | Host only: spawn creeps where a live creep stands, through its spawner (they count in its wave) and walking the rest of its route. `opts.ring = true` spreads them in a ring. |
| `Creeps.setDamageFilter(fn)` | SecondWind has one damage filter and creepsKit uses it; give yours here and it runs first: `fn(vitals, amount, info) -> amount`. |
| `Creeps.on(event, fn)` | Listen on this peer (below). Returns a connection with `:Disconnect()`. |
| `Creeps.eventCounts()` / `Creeps.stats()` | Event counters and the last 30 payloads; the tick's counters `{ ticks, hostPasses, live, lastMs, peakMs, refreshMs, hostMs, fxMs }`. |
| `Creeps.hasTurretsKit()` | Whether turretsKit is installed. |
Also `Creeps.VERSION`, `Creeps.EVENTS`, `Creeps.STYLES` and the modules `Creeps.kinds`, `Creeps.looks`, `Creeps.runtime`.
## Events
Each fires on **every peer**, worked out from synced state, with `owner = true` on the peer that runs the creep:
| event | payload |
|---|---|
| `split` | `enemy, kind, into, count, position, children` (children ids on the owner) |
| `healed` | `enemy, kind, count` (creeps healed), `amount, radius, position` |
| `shieldBroken` | `enemy, kind, maxShield, position` |
| `phase` | `enemy, kind, phase` (2 or 3), `from, position` |
| `revealed` | `enemy, kind, position` |
Each comes with its effect on every screen (juiceKit, played locally): sparks and a zap when a bubble breaks, smoke and a wobble on a split, healing motes and an expanding green ring on a pulse, a magic burst when a sneak is revealed, fire and a rumble for the enrage, a burst and a small blast for the shield phase.
## Multiplayer
- **Traits run on the host**: the peer that owns the creep, which is the peer that owns its spawner (spawnerKit's host). One shared tick, ten times a second over all live creeps, never a script per creep. Armour runs inside SecondWind's damage filter on the owner, so remote damage requests are armoured too. Shields are SecondWind's own shield model.
- **Visuals on every peer come from synced state only**: Lifeline's synced `shield`/`maxShield` drive the bubble; the host replicates a few small named values on each creep entity (`ck_rev` revealed, `ck_phase` boss phase, `ck_pulse`/`ck_healN` heal pulses, `ck_split`/`ck_splitN` the split) at 10 Hz, and every peer follows them through value subscriptions. Looks are built locally from spawnerKit's synced `kind` and `look`, as spawnerKit does.
- **Events** fire on every peer from those values, so all screens react at about the same time.
- Because `register()`, the styles and turretsKit's turret types are per-peer, call them in code every peer runs.
- spawnerKit's own limits apply (see its README's Known limits: late enemies for a second player in some sessions).
## Cost
With 166 live creeps of every kind on a desktop, the shared tick costs about 1 ms a frame on average: a refresh of the live list and the host pass ten times a second, and per-creep visuals at 30 Hz only for kinds that animate something (shield, stealth, healer, splitter, boss). The test suite checks 120 creeps stay under 4 ms.
## Data
A kind is a `.data` file of the `creepsKit.creepKind` contract; its README lists every field. Copy one of `kinds/*.data` anywhere in your world, change its `id` and numbers, and call `Creeps.reload()` (or `register()` again). Or in code: `Creeps.define("goblin", { label = "Goblin", health = 40, speed = 3.4, color = "#6fae3c" }, "footman")`; a kind with an id the looks do not know borrows the footman's shape in its own colour.
## The gallery
`scenes/creepsGallery.scene` shows all of it: four lanes (one per style: fantasy, sci-fi, cartoon, pixel) each looping every kind past four turretsKit towers (a machine gun and tesla that hit both layers, a ground-only cannon, a detecting "Watch Eye" sniper), and a labelled still lineup of all eleven kinds in all four styles, a row per style. Its layout is the `creepsKit.gallery` module, a worked example of wiring creepsKit, spawnerKit and turretsKit together. Read the guide `how-to-add-tower-defense-enemy-types` for the whole walk-through.
## Tests
`tools.use("tests", "run", { suites = { "creepsKit" } })`: 18 tests on the catalog, registration, every look in every style, the style aliases, the pixel style's blocks and the lite part budget, armour, shield, split from the death spot, healer, stealth and reveal, boss phases, the turretsKit hook and a detecting turret, and the tick's cost with 120 creeps.
## Requires
spawnerKit (`require("spawnerKit.api")`), SecondWind and juiceKit, which spawnerKit brings. turretsKit is optional; its `hits`/`detects` fields and `TK.setTargetInfo` hook arrive in the turretsKit release after 2.1.4 (with an older turretsKit, creepsKit still runs and towers simply shoot every creep).
## Version
1.3.6: `looks.defineModel(kind, { model, scale, yaw, lift, styles })` draws a kind as one model (a bundle, through an `Asset` component) instead of its built-in shape, in every style unless `styles` narrows it; `lift` is in the model's own units, so a model centred on its origin stands on the ground with lift = half its height. `looks.modelOf(kind)` reads it. One model per creep instead of 11-16 parts, and a game can bring its own art.
1.3.5: documentation only, no change to the creeps: a store description that names every enemy and look and how to install and use the kit, and the same install-and-use line at the top of this README.
1.3.4: no change to the creeps; released again from main beside towerDefenseKit 1.2.11 and wavePreviewKit 1.1.5 so the three kits install on their own at matching versions.
1.3.3: an empty kind cache is rebuilt instead of trusted, so a world that installed an earlier version without the kind files gets its eleven kinds as soon as the update lands, with no restart.
1.3.2: the kit names each of its eleven kind files in code, so a world that gets creepsKit through another kit (towerDefenseKit, say) receives them too. Before, such an install brought the code but not `kinds/`, which is found by its contract rather than by name: the kit had no kinds, and waves fell back to spawnerKit's own enemies. Kinds a world adds as its own `.data` files are still found by the contract.
1.3.1: `Creeps.useSpawnerKit(require("spawnerKit.api"))` points creepsKit at the spawnerKit your game loads. A world can end up holding two byte-identical copies of spawnerKit that load as separate modules (a platform bug); the kinds then went into the copy no Spawner used, and waves fell back to spawnerKit's own enemies. towerDefenseKit 1.2.2 calls it for you.
1.3.0: every kind states its name for several (`plural`: "Footmen", "Warlords"), and `entry(kind).plural` carries it to wave previews; kinds without one get an English plural that leaves plural-looking words alone. Two labels now read as nouns, one or many: `shielded` is the Shieldbearer and `swarm` the Swarmling (ids unchanged, so maps and waves keep working).
1.2.2: the Warlord boss has 2,000 health (was 2,400), so a decent tower defense can bring it down.
1.2.1: `register()` redefines the kinds when spawnerKit lost them (a spawnerKit reload resets its registry), instead of trusting its own flag.
1.2.0: the pixel style (blocky voxel creeps in a flat palette), theme aliases `fantasy` -> `medieval` and `cartoon` -> `toy`, labels Fantasy / Sci-fi / Cartoon / Pixel, `Creeps.resolveStyle`, a fourth gallery lane and lineup row.
1.1.0: the `lite` detail level.
1.0.0: first release. Eleven kinds, three styles, five events, turretsKit layers and stealth.
## Detail level (big crowds and browsers)
`require("creepsKit.looks").setDetail("lite")` builds every creep from now on with only its few largest parts plus the parts the runtime animates (shields, auras, eyes): 4-5 models instead of 11-16. Measured with 130 creeps on the road under fire, the scene held 1,864 entities instead of 2,995 and the frame time fell from 208 to 173 ms average (888 to 407 ms worst) in a debug editor. `setDetail("full")` goes back. towerDefenseKit picks "lite" by itself in a browser or on a phone (its Game's `creepDetail = "auto"`).