pixelBosses
Drop a boss into any **twoDKit** platformer or metroidvania and get a full Hollow Knight / Super Metroid style boss fight: a big hand-painted pixel sprite (3 to 5 tiles tall) with idle, move, wind-up, attack, hurt, roar, death and special animations, an intro roar, telegraphed at…
pixelBosses: three 2D pixel-art boss fights with phases
Drop a boss into any twoDKit platformer or metroidvania and get a full Hollow Knight / Super Metroid style boss fight: a big hand-painted pixel sprite (3 to 5 tiles tall) with idle, move, wind-up, attack, hurt, roar, death and special animations, an intro roar, telegraphed attacks, a second phase at half health, hit flash and flinch, camera shake on slams, hit-stop on the phase change and a big chain of explosions on death, with 8-bit roars, slams, shots, lasers and booms. It is multiplayer by default and costs no network traffic per projectile.
Version 1.2.3 (Bosses.VERSION). Install in the engine shell: zero zeromind installAsset 8b4bbe69-ddf9-4217-9a00-a1fafbcc969d. A BossSpawn in the scene puts one networked boss in play that every player, late joiners included, shares. Every sword hit lands and counts: from either side or from above (down-slash pogo), in both phases, during every attack (charges, leaps, dives, swoops, hops, lasers) and from the moment the boss wakes (the intro roar counts too), for every player in the room. Built on installed packages where they fit:
- aiKit (Watchful Minds): the boss's decisions are an
aiKit.btbehaviour tree (asleep, finished, dying, phase change by health fraction in aiKit's boss-preset shape, waking, busy, next attack). The 2D moves stay pixelBosses' own (see Notes for why aiKit's Brain does not drive them). - SecondWind: hit points live in a
SecondWind.poolhealth record on the boss's authority (its damage rules, death), mirrored into the syncedhealthfield. - juiceKit: every sword hit bursts juiceKit sparks where the blade met the body on every player's screen; the killing blow adds a flash, a burst and juiceKit's critical hit stop (
pixelBosses.feel).
| Thorn Knight | Hive Queen | Iron Warden |
|---|---|---|
![]() | ![]() | ![]() |
The bosses
Every attack is telegraphed: the boss flashes and winds up for about half a second, and thorns, missiles and lasers show a blinking marker where they will land before they do.
Boss (kind) | Phase 1 | Phase 2 (at or below half health) |
|---|---|---|
Thorn Knight thornKnight "Warden of the Moss" (24 hp) | Walks toward you; charge across the floor to the wall (low lunge: jump it); leaping slam onto where you stand that sends shockwaves both ways along the floor (jump them). | Faster and shorter rests; thorn rain: red markers blink on the ceiling, then thorns fall in two waves (the second wave strikes the gaps of the first); triple dash wall to wall to wall. |
Hive Queen hiveQueen "Mother of the Swarm" (22 hp, flies) | Hovers above you; swoop in a dive through where you stand and up the other side (jump or dash over); fan of 5 slow orbs aimed at you. | Two fans of 7; spiral: flies to the middle and spins three arms of slow orbs for 2.6 s; summons 2-3 stingers that home weakly on their target and die in one hit. |
Iron Warden ironWarden "Engine of the Sunken Vault" (26 hp) | Stands at one side of the arena and hops to the other (landing shakes the room); fist slam: yellow stripes mark the floor, then a piston fist shoots 9 tiles along it (jump it); laser sweep at foot height (jump) or head height (stay on the ground), shown by a blinking red line first. | Missile barrage: crosshairs mark columns on the floor, then missiles fall in two waves (the second strikes the gaps); double laser: one height, then the other. |
Put a boss in your level
-- scenes/<yours>.scene/build.luau
local PP = require("twoDKit.api")
local ROOM = [[
########################
#......................#
#......................#
#......................#
#......................#
#......................#
#......................#
#......................#
#......................#
#......................#
#..P...................#
########################
]]
function content()
PP.level({ theme = "cave", text = ROOM })
PP.player({ character = "knight", lives = 5 })
-- a BossSpawn: in play one peer spawns the boss every player shares (its health, phase and moves replicate)
local spawner = entity.spawn("BossSpawn", { position = { 18, 1, 0 } }) -- the boss's feet on the floor
spawner.component.add("pixelBosses.BossSpawn", {
bossName = "Boss", -- every peer finds the boss by this name
kind = "thornKnight", -- or "hiveQueen", "ironWarden"
arenaMinX = 1, arenaMinY = 1, arenaMaxX = 23, arenaMaxY = 11, -- inside the walls; floor = arenaMinY
})
end
The boss waits, dormant, until something wakes it. From a trigger, a door or your arena kit, in play, on any peer:
local Bosses = require("pixelBosses.api")
local id = Bosses.byName("Boss") -- nil until the boss exists on this peer
local boss = Bosses.get(id) -- the Boss2D component
boss:activate() -- dormant -> intro roar -> fighting
boss:damage(1, playerBody.id, 1) -- 1 damage from a player, knocked right
boss:reset() -- full health, dormant, back at the start, shots cleared
print(boss.health, boss.maxHealth, boss.phase, boss.state, boss:isDefeated())
With slash2D installed, the boss is already a slash target on every peer: hit it with the sword and it takes damage. Any other attack system can test against Bosses.hitbox(id).
API
Boss2D component (pixelBosses.Boss2D)
| Field | Kind | What |
|---|---|---|
kind | enum, synced | thornKnight, hiveQueen or ironWarden. |
arenaMinX, arenaMinY, arenaMaxX, arenaMaxY | numbers, synced | Arena bounds in world units. arenaMinY is the floor the boss and its shockwaves stand on, arenaMaxY the ceiling thorns and missiles fall from. All 0 = 12 units either side of the start and 12 up. Players inside it are the boss's targets. |
maxHealth | number, synced | 0 = the kind's default (24 / 22 / 26 hits of 1 damage); the authority writes the resolved value in play, so reading it gives the real maximum. |
health | number, synced, read-only | Hit points left. |
phase | number, synced, read-only | 1, then 2 once health is at or below half. |
state | string, synced, read-only | dormant, intro, fighting or defeated. |
move | table, synced, read-only | The move it is running (kind, t0, dur, ...): what every peer simulates from. |
contactDamage | bool | Touching the body hurts (default on). |
debugLabel | bool | A small label above the boss with name, health, phase, state and move (this peer). |
sound | bool | Boss sounds on this peer. |
Methods, callable on any peer (they travel to the authority): activate(), reset(), damage(amount, attackerId?, dirX?) -> boolean (false while it cannot be hurt: dormant or defeated; the intro roar can be hit), isDefeated(), hitbox() -> { x, y, halfW, halfH }?, hazards() (every live hurting box on this peer), displayName(), maxHp().
pixelBosses.api
local Bosses = require("pixelBosses.api")
Bosses.list() --> { "thornKnight", "hiveQueen", "ironWarden" }
Bosses.info("thornKnight") --> { id = "thornKnight", name = "Thorn Knight", title = "Warden of the Moss", maxHealth = 24, phases = 2 }
Bosses.all() --> every Boss2D entity id on this peer
Bosses.get(bossEntityId) --> its Boss2D component
Bosses.hitbox(bossEntityId) --> { x, y, halfW, halfH } (centre, world units) or nil while dormant / defeated
Bosses.on("phase", function(bossEntityId, phase) end)
Bosses.on("defeated", function(bossEntityId) end)
Bosses.on("hurt", function(bossEntityId, health, maxHealth) end)
Bosses.on("state", function(bossEntityId, state, previousState) end)
Bosses.on("*", function(eventName, ...) end)
The events fire on every peer, each from the synced fields it sees change (so hurt fires once per frame in which health dropped, however many hits landed in it). Each on returns a connection with :Disconnect().
How a boss hit costs a player: Bosses.hurtPlayer
Every peer tests only its own player (twoDKit's local player body) against the boss body, its projectiles, shockwaves, lasers, fists, missiles and stingers. A hit goes through one function you can replace:
Bosses.hurtPlayer = function(body, info)
-- info = { label = "Thorn Knight", damage = 1, fromX = <x of what hit>, boss = <boss entity id>, kind = <move kind> }
-- default: require("Trapline.api").hit(body, { label = info.label }) (costs a Trapline life)
end
Bosses.INVULNERABLE = 1.0 -- seconds after a boss hit before this player can take another
It runs only on the peer that owns body, at most once per Bosses.INVULNERABLE seconds, so one attack never hits every frame. A metroidvania replaces it with a mask loss plus knockback away from info.fromX instead of Trapline's respawn at the checkpoint.
Multiplayer
- One peer runs the boss: the owner of its entity. It picks targets among the players inside the arena and writes each move once into the synced
movefield. - Every peer computes the same pose, projectiles, telegraphs, sounds and shakes from that move on Trapline's shared clock (
Bosses.now()), so nothing per projectile crosses the network. Stingers are steered on each peer toward their target and their deaths are broadcast. damage,activateandresetcalled on another peer are sent to the authority, which applies them;health,phaseandstatereplicate back and the events fire everywhere. So two players with their own swords both hurt the same boss: the attacker's peer tests its swing against the boss where that peer draws it, flashes the boss at once and sends the damage on thepixelBosses.damagechannel; the authority applies it once (a repeated request is ignored).- Every peer sees every hit: slash2D syncs each counted hit, and each peer flashes the boss and plays the juiceKit sparks from it; the health drop arrives through the synced
health. - Put the boss in a scene with a
BossSpawn(as above), not withentity.spawnSyncedinside the scene build: a build-spawned synced boss reached a peer that entered play after the first with no replication record (its state, health and moves never arrived there; engine report filed). The BossSpawn waits until the room has answered this peer's join, finds the boss by name, and when the room has none the lowest peer id spawns it at runtime withentity.spawnSynced(a peer further down waits longer, in case the lowest never does); a duplicate from a race is despawned by its owner. A late joiner gets the room's boss, the owner leaving hands it to a peer that stays, and re-entering play never makes a second one. In edit mode it shows nothing. - A boss you spawn yourself at runtime with
entity.spawnSyncedplus a Boss2D works the same way; a plainentity.spawnboss still works for one player, but the other players would each fight their own.
What is inside
| Asset | What |
|---|---|
BossSpawn (component) | Puts one networked boss in play on whichever peer should spawn it; bossId(), boss(). |
Boss2D (component) | The boss: AI on the authority, drawing, hazards, hits on this peer's player, events, slash2D registration. |
api (module) | list, info, on, all, get, byName, hitbox, hurtPlayer, now, and the network routing. |
moves (module) | Every attack as a pure function of time: pose, hazards, cues, and the AI plan. Tune the timings in Moves.KNIGHT, Moves.QUEEN, Moves.WARDEN. |
defs (module) | Names, titles, health, sheet layout, body boxes, sound names, and PHASES (the health fractions each phase starts below). |
feel (module) | The juiceKit presets pixelBosses.hit (sparks) and pixelBosses.finish (killing blow); Feel.enabled. |
art (module) | Paints the four sheets in code with pixelPaint: require("pixelBosses.art").generate() repaints them. |
sfx (module) | The 15 boss sounds (chipSfx voices) and bake() to re-bake them; BSfx.volume, BSfx.muted. |
art/ | thornKnight (64 x 64 frames), hiveQueen (80 x 64), ironWarden (64 x 80) and fx (16 x 16) sheets with their materials. |
sounds/ | The baked sound clips. |
| guide | how-to-add-a-boss-fight-to-a-2d-platformer. |
Notes and limits
- Bosses use twoDKit's camera shake and pixel effects, and their own hit-stop (released every frame it is due, so it can never stick).
- The sprites face right and are drawn with pixelSprites'
spriteshader: crisp at twoDKit's pixel-perfect camera. - The Iron Warden stands 2.2 units in from each wall; make the arena at least 16 units wide so its lasers and fist leave room.
- A stinger chases the player the boss targeted; on other peers it may sit a little differently, since each peer steers its own copy.
- Why aiKit's Brain component does not move the bosses:
Brainadds a navKitNavAgentand moves withactions.moveToon a 3D navmesh, turns by yaw, senses through 3D sight cones (senses) and reads health from SecondWindVitals(registry.healthFraction). A side-view boss moves in arcs, charges and swoops on a 2D plane computed from one synced move on a shared clock, and its entity never moves (its sprite does), so Vitals' effects and aiKit's movement would both sit at the spawn spot. aiKit's behaviour tree (aiKit.bt, pure, no navKit) and its boss rule (phases by health fraction, a roar on each new phase) fit, and are what Boss2D uses.
Changelog
- 1.2.3: the description and README give the one-line install with this package's id. No code change.
- 1.2.2: a boss stays a sword target after slash2D reloads during play: once a second each boss checks that slash2D still lists it and registers again (with its hit flash and sparks) when it does not. Before, a reload of slash2D mid-session left every boss unhittable until the scene restarted.
- 1.2.1: the bosses' sprite sheets ship as textures only; pixelSprites 1.1.0 builds their materials at runtime (
Sprites.sheetMaterial), so the package carries no material assets and no generated preview pictures. Nothing changes in a fight. - 1.2.0:
BossSpawncomponent: a boss placed in a scene now reaches every player. Bosses built withentity.spawnSyncedinside a scene build never synced to a peer that entered play second (it read dormant at full health while the first player fought it down). The spawner puts the boss in at runtime from exactly one peer, late joiners get it, a leaving owner hands it on, re-entering play makes no duplicate.Bosses.byName(name); the spawn-once decision isBosses._spawnPlan, covered by tests. - 1.1.0: every sword hit lands and counts: hits during the intro roar now count (they used to be refused, which looked like a miss), checked on all three bosses in both phases at every moment of every move from the left, the right and above (a regression test). The authority decides with an aiKit behaviour tree; health lives in a SecondWind pool; sword hits play juiceKit sparks on every peer and the killing blow a flash and a critical hit stop. Second-player damage path tested (
Bosses._receiveDamage).Bosses.getalways returns the entity's live Boss2D (a proxy kept from before a reload or a re-add took no writes, so every hit and command sent to it was lost), and the network handlers of an earlier copy of the api go quiet after a reload instead of applying a hit twice. New dependencies: aiKit, SecondWind, juiceKit. - 1.0.4: fixed the boss being unhittable where you see it: its sword hit box stayed at the spot where it first appeared instead of following it as it walks, charges and leaps. It now follows the boss on every player's screen, and a swing at the empty spawn spot no longer hurts it. Needs slash2D 1.0.3.
- 1.0.3: dependencies pinned by guid; a test suite (
zero tests run pixelBossesTests). - 1.0.2: preview images; runs on twoDKit 1.3.0.
- 1.0.1: the boss entity is spawned synced by sideScrollerKit; preview images.
- 1.0.0: first release: Thorn Knight, Hive Queen and Iron Warden, two phases each, Boss2D, the api, painted sheets, 8-bit sounds, slash2D hook-up and the guide.
Scoped to this part · feeds back into the world's score.


