Hold the Line: Tower Defense Kit with Paths, Towers, Waves and a 10-Wave Map
README.md
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 splitlings 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:
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):
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:
Creeps.setSpawnerStyle(spawnerName, style): that spawner's creeps (a pooled creep restyles if another spawner reuses it).Creeps.setStyle(style): every creep ("auto", the default, skips this step).- The spawner's spawnerKit
lookthroughCreeps.mapLook(look, style): by defaultneondrawsscifi. - turretsKit's world style (
TK.setStyle), when turretsKit is installed, so creeps match the towers. 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
hitslist (["ground"],["air"]; empty = both, which is every stock turret); - skips hidden targets unless the turret
detects(within itsdetectRange); - 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:
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/maxShielddrive the bubble; the host replicates a few small named values on each creep entity (ck_revrevealed,ck_phaseboss phase,ck_pulse/ck_healNheal pulses,ck_split/ck_splitNthe split) at 10 Hz, and every peer follows them through value subscriptions. Looks are built locally from spawnerKit's syncedkindandlook, 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").