# sideScrollerKit.api
The kit's front door for a scene's build.luau: `MV.world` (theme, masks, saving), `MV.room` (a room on the grid from text), `MV.boss` (a pixelBosses boss and its arena), `MV.player` (the twoDKit player template with a slash2D attack and Trapline masks), `MV.gate` / `MV.shrine` / `MV.savePoint` (pieces by hand) and `MV.setTheme` (in play).
# demo.gallery
Builds the Hall of Echoes in Lantern Depths: every sideScrollerKit gate, shrine and save point in all five looks on labelled shelves, the three pixelBosses bosses, and pads that play each room transition, show every map style and switch the world theme. Called from the main scene build.
# sideScrollerKit.Gate
One ability gate; every kind takes the same fields, so swapping `kind` or `look` never breaks a level. Kinds: `crystal` (dash through), `smash` (slam through), `door` (key), `bars` (opened by the switch named in `link`), `switch`, `bossDoor` (seals while the player fights the arena named in `link`), `grip` (wall-jump wall), `sign` (shows `ability`). Looks: pixel, fantasy, scifi, cartoon, minimal, or `theme`. The entity's position is the bottom-left corner; `w`, `h` in tiles; `gateId` is what the player's progress remembers; `display` makes it a gallery piece. Per player: each peer keeps the collision of gates its own player has not opened, on temporary entities. Needs sideScrollerKit.art (sprites) and twoDKit's Player2D on the player. Rooms build these from their text; `MV.gate` places one by hand.
# BossSpawn
Puts one networked pixelBosses boss in a scene, the same one on every peer. Put it on a plain entity in a scene build (not `entity.spawnSynced`): its position is where the boss's feet stand, and its fields say which boss and its arena. It needs no sibling components; the boss it spawns is a separate entity carrying a `pixelBosses.Boss2D`.
```lua
local s = entity.spawn("BossSpawn_lair", { position = { 18, 1, 0 } })
s.component.add("pixelBosses.BossSpawn", { bossName = "Boss_lair", kind = "thornKnight",
arenaMinX = 1, arenaMinY = 1, arenaMaxX = 23, arenaMaxY = 11, maxHealth = 12 })
-- in play, on any peer:
local id = s.component.get("pixelBosses.BossSpawn"):bossId() -- or require("pixelBosses.api").byName("Boss_lair")
```
- **Spawn once**: in play, after the room answers this peer's join and `settle` seconds pass, each peer looks for the boss by `bossName`. If the room already holds it, that is the boss. If not, the lowest peer id in the room spawns it with `entity.spawnSynced` and adds the Boss2D, so its synced state, health and moves reach every peer. A peer further down the order waits `settle + rank * Bosses.SPAWN_STAGGER` seconds before spawning, in case the lowest peer never does. If two ever exist, the owner of each one but the lowest id despawns its own.
- **Late joiners** receive the existing boss from the room. **The owner leaving** hands it to a peer that stays (the engine's ownership handover), with its health kept. **Re-entering play** finds the boss the room still holds, or spawns a fresh one when the room is empty: never a duplicate.
- **Edit mode**: shows and spawns nothing.
- **Why**: a boss spawned with `entity.spawnSynced` inside a scene build reached a peer that entered play second without a replication record, so its fight never synced there.
Fields (all per peer, not synced): `bossName` (empty = this entity's name + `_boss`), `kind`, `arenaMinX`, `arenaMinY`, `arenaMaxX`, `arenaMaxY`, `maxHealth` (0 = the kind's default), `settle`. Methods: `bossId()` (nil until the boss exists on this peer), `boss()` (its Boss2D), `name()`. The decision itself is `pixelBosses.api` `_spawnPlan`, a pure function the tests drive.
# sideScrollerKit.Shrine
An ability shrine: walk into it to gain its `ability` (dash, wallJump, doubleJump, slam, or your own id), with a fanfare, hit stop and a NEW ABILITY card. The orb stays for players who have not taken it. Fields: `ability`, `look`, `shrineId`, `display`. `a` in room text (the room's `shrine` ability), or `MV.shrine`.
# sideScrollerKit.Metroidvania
The world's metroidvania rules, one per scene (`MV.world` adds it). On every peer, for its own player: applies the `theme` (gate, shrine and save looks, save style, map style, transition, boss plate, masks), loads the player's progress from saveKit and resumes them at their last save point, gives the controller the abilities they own, tracks which room they are in (transition, map, tried exits, room titles), runs masks and respawns (hazards: back to safe ground; last mask: back to the save point), registers the `metroidvania` controlsKit scheme (attack and map added) and draws the HUD and map (M / Tab / Select / MAP button). Fields: `theme`, `mapStyle`, `transition`, `minimap`, `masks`, `masksLook`, `cellW`, `cellH`, `useSave`, `resumeAtSave`.
# Slash2D
A Hollow Knight style sword slash for a twoDKit platformer player. Put it on the player's body next to `twoDKit.Player2D` (and `twoDKit.Sprite2D`): `players.body.component.add("Slash2D", {})` after `PP.player()`. Pressing the controlsKit `attack` action swings forward, up (up held) or down (down held in the air) with a 0.33 s cooldown; hits on `slash2D.api` targets and SecondWind Vitals give hit-stop, a spark, a clank, recoil, and a pogo bounce with dash refill on a down hit. It switches Player2D's scheme to `platformerSlash` so the attack button exists. The owner peer reads input and tests hits; the synced `swing` and `hitFx` fields let every peer draw every swing and spark. Fields and API: the package README.
# demo.GalleryPad
A pad in the Hall of Echoes (Lantern Depths demo). Step on it to play one sideScrollerKit room transition, show every map style side by side, or switch the whole world theme. Needs sideScrollerKit.
# sideScrollerKit.Room
One room of the world, on the same entity as a twoDKit `Level2D` (`MV.room` adds both). Reads its `text` (twoDKit's legend plus the kit's letters: x crystal, s smash, d door, k key, b bars, w switch, | boss door, a shrine, R save point, Z boss start, g grip, j/u/y/v signs), hands the level part to Level2D and builds the kit's pieces on temporary children, registers the room (grid cell, size, exits found from the gaps in its border) for the map and room tracking. Fields: `roomId`, `name`, `kind`, `gx`, `gy`, `cw`, `ch`, `text`, `shrine`, `look`, `saveStyle`, `bossLink`.
# sideScrollerKit.BossArena
A boss room's fight, per player. Sits on a boss room's entity (beside its `Room`; `MV.boss` adds it) and points `spawner` at the entity holding the pixelBosses `BossSpawn` that puts the boss in play (or `boss` at an entity with a `Boss2D` placed by hand). Walk `margin` tiles in and the room's boss doors (`|`) seal behind you, the boss wakes and its health plate shows (barsKit, look from the theme); at half health the boss changes attacks; beat it and the doors open, the room's bars open the way on and the win is kept in your save. Lose your last mask and the doors open; once no living player is left in the arena the boss resets to full health. A boss hit costs one mask with knockback (it replaces `Bosses.hurtPlayer`). Fields: `arenaId`, `roomId`, `spawner`, `boss`, `sealStyle`, `margin`, `resetAfter`.
# sideScrollerKit.SavePoint
A save point: bench, campfire, statue, terminal or crystal (`style`), drawn in any look. Stand at it and press Interact or Up: your masks refill, it becomes where you wake after losing your last mask, and your progress is saved to your saveKit profile. Per player. Fields: `style`, `look`, `roomId`, `display`. `R` in room text, or `MV.savePoint`.
# sideScrollerKit: make a metroidvania in Zero
The genre glue that turns a 2D pixel platformer into a **metroidvania** in the Hollow Knight / Super Metroid mould: a world of rooms on a grid joined by exits with a room transition, **ability gates** you only get past once you have found the right power, **ability shrines**, a **room map that fills in as you explore**, **save points** that heal you and keep your progress across sessions, and **boss arenas** that seal behind you. Every piece comes in **six looks** (pixel, fantasy, sci-fi, cartoon, minimal, gothic), and **one `theme` word switches the whole set** together. It is multiplayer: every friend in the world keeps their own abilities, map, opened gates and save.
The kit only holds the metroidvania part. Everything else is installed from ZeroMind with it (see [Installed packages](#installed-packages)): the platformer (twoDKit), the sword (slash2D), the bosses (pixelBosses, whose decisions run on aiKit's behaviour tree and whose health is a SecondWind pool), hazard respawn (safeGround2D), masks and respawn (Trapline on SecondWind health), saves (saveKit), locked doors, keys, the switch and bars (interactKit), abilities and the ability bar (abilitiesKit), moving and crumbling platforms (platformsKit), the room map, toasts and room titles (navUiKit), room transitions (screenWipes), the boss bar (barsKit), shake and hit stop (juiceKit), music and ambience (Soundstage), the frame look of each theme (styleKit with starterBlocks, toonBlocks, inkBlocks and paperBlocks), controls (controlsKit), and pixel art and 8-bit sound (pixelPaint, pixelSprites, pixelParallax, chipSfx). About 86% of the code the game runs comes from those installed parts.

## Install and use
1. In the engine shell: `zero zeromind installAsset f1eb8e7f-1cf9-4e02-8f86-5d46ba9fd86b` (or search ZeroMind for **sideScrollerKit** and install it). The dependencies take two to three minutes to arrive (engine issue #21420 on GitHub).
2. Replace your scene's `build.luau` (a new world's is `scenes/main.scene/build.luau`) with this and press **Play**:
```lua
local MV = require("sideScrollerKit.api")
function content()
MV.world({ theme = "pixel" })
MV.room({ id = "hollow", name = "Mossy Hollow", at = { 0, 0 }, kind = "start", shrine = "dash", text = MV.sample("hollow") })
MV.room({ id = "gallery", name = "Crystal Gallery", at = { 1, 0 }, kind = "save", text = MV.sample("gallery") })
MV.room({ id = "lair", name = "Thorn Lair", at = { 2, 0 }, kind = "boss", text = MV.sample("lair") })
MV.boss({ room = "lair", kind = "thornKnight", maxHealth = 12 })
MV.player()
end
```
You start in the Mossy Hollow. Climb the two ledges to the shrine to learn the **Shade Dash**, walk right into the Crystal Gallery, rest at the bench (Interact or Up) and dash (Shift) through the crystal wall. Walk on into the Thorn Lair: the way back seals, and the Thorn Knight attacks. Beat it with your sword (X) and the boss door opens. Open the map with **M** (Tab, gamepad Select, or the MAP button). Quit and come back: you are at the bench, with the dash and your map.
`MV.sample` returns the text of three ready-made rooms (`hollow`, `gallery`, `lair`). Your own rooms are text too: see [Rooms](#rooms).
Controls (controlsKit): move A/D or arrows, jump Space/K, dash Shift/J, attack X/H/left mouse, interact L, map M/Tab. Gamepad: stick or d-pad, south jump, right shoulder or north dash, right trigger or left shoulder attack, Select map. Phone: the on-screen stick and buttons, with MAP in the corner.
## Rooms
`MV.room({ id, name, at = { gx, gy }, size = { cw, ch }, kind, text, theme, shrine, seal, look, saveStyle })` places a room on the grid. A cell is 24 x 14 tiles (one screen; `MV.world({ cellW, cellH })` changes it), so a room is `cw * 24` tiles wide and `ch * 14` tall, and `gy` grows upward. **Exits** are gaps in a room's outer wall; put the gap where the neighbouring room's gap is. The map draws every exit and marks the ones you have not gone through.
`kind` (`start`, `save`, `boss`, `shrine`, `normal`) is what the map marks. `theme` is the twoDKit level theme (tiles and parallax background) of that room.
The text is twoDKit's level legend (`#` ground, `=` one-way ledge, `^` spikes, `P` start, `o` gem, `M`/`V` moving platforms, `T` spring, ...) plus the kit's letters:
| Letter | Piece | Gets past it |
|---|---|---|
| `x` | crystal wall | dash into it |
| `s` | cracked floor | slam onto it (down in mid-air) |
| `g` | grip wall (solid) | marks a wall-jump shaft: climb it with the wall jump |
| `t` | thorn wall | strike it with your sword |
| `q` | ability seal | walk up holding the room's `seal` ability (default `doubleJump`; any id works) |
| `h` | drop-through hatch | hold down on it (or slam onto it) to drop through; solid from below, so it is one way |
| `d` | locked door | walk up carrying a key (`k`) |
| `b` | bars | hit the room's switch (`w`); in a boss room, beat the boss |
| `\|` | arena seal | open; seals behind you while you fight the room's boss |
| `a` | ability shrine | grants the room's `shrine` ability |
| `R` | save point | rest: heal, save |
| `Z` | where the boss stands | |
| `y` `j` `u` `v` | sign: dash, wall jump, double jump, slam | |
Double-jump ledges and wall-jump shafts are geometry: a ledge higher than one jump (with a `u` sign) needs the double jump, a shaft too tall to jump (with `g` walls and a `j` sign) needs the wall jump. The player only gets those moves from a shrine.
## Abilities
`dash`, `wallJump`, `doubleJump` and `slam` turn on twoDKit's Player2D `canDash`, `canWallJump`, `airJumps` and `canSlam` for the player who has them. Your own ids work too: `MV.Progress.grant("lantern")`, `MV.Progress.has("lantern")`, and a `q` seal opens for them.
Every ability is an **abilitiesKit** ability (`mv.<id>`, a passive one: it is held, never cast). The player's body carries an abilitiesKit Character whose loadout is what they hold, synced to every friend, and that loadout is what turns the moves on. abilitiesKit's ability bar shows it at the bottom of the screen as a row of coloured pips, styled by the theme (pixel, fantasy, sci-fi, cartoon, minimal; gothic wears fantasy's). What a player holds is saved in their own saveKit profile.
## Doors, keys, the switch and bars
Locked doors (`d`), keys (`k`), the switch (`w`) and bars (`b`) are **interactKit** (Open Sesame) devices, drawn as the kit's pixel sprites in the six looks: a door is a device with interactKit's key Lock (it uses the key up), a key is an interactKit Item, and the switch opens its bars through interactKit's wiring. Walk into a door with a key, or press Interact (E) at it; interactKit's prompt says Locked / Unlock, in a style that follows the theme (pixel, tooltip, glyph, ring, dot).
They are **per player**: every device sits on an entity of each player's own, so each friend decides only for themselves, and the kit hands interactKit that player's progress as its state store and key inventory. A friend's opened doors, thrown switch and carried keys are theirs alone and are still theirs next session.
## Platforms
Moving platforms in room text (`M` side to side, `V` up and down) are platformsKit platforms, through twoDKit. `MV.platform({ room, kind, at = { x, y }, length })` places any other **platformsKit** kind in a room (crumble, fall, elevator, pingpong, spring, conveyor, ...), drawn as the room's own pixel planks: `at` is the left edge and the height of its top, in the room's tiles. The Crystal Gallery has two crumbling ledges up to its gem.
## Music and ambience
**Soundstage** plays each player's room: the theme picks the music set (pixel chiptune, fantasy, sci-fi, cartoon, synthwave for minimal, horror for gothic), explore while you wander (calmer in save rooms), action the moment a boss arena seals, the intense take when the boss reaches its second phase, and back to explore once it falls. Each room has an ambience bed under the music, picked from its level theme (cave, forest, wind, station, shore). `MV.room({ music = "western", ambience = "rain" })` sets either per room. Music is local to each player, since friends can be in different rooms. The kit's own effects (gates, shrines, saves, the boss) stay 8-bit chipSfx clips: they belong with the pixel art, where Soundstage's recorded takes would stand out.
Camera shakes and hit stops for the kit's moments (a crystal shattering, a floor smashed, a boss slamming its seal, the phase roar, the win) play through **juiceKit**; twoDKit's own moments (jump, land, dash) keep twoDKit's feel.
## Gates, shrines and save points by hand
Anything typed in text can also be placed by hand, at any size: `MV.gate({ kind, at = { x, y }, size = { w, h }, look, id, link, ability })`, `MV.shrine({ ability, at })`, `MV.savePoint({ at, style })`. Every gate kind takes the same fields, so changing `kind` or `look` never breaks a level.
## Bosses
`MV.boss({ room = "lair", kind = "thornKnight", sealStyle = "theme" })` puts a pixelBosses boss in a boss room and makes the room its arena. Walk in and the arena seals behind you, the boss roars and its health bar shows. At half health it grows furious and switches to its second set of attacks. Hit it where you see it: a hit lands on the boss's body wherever it has moved. Beat it and the arena opens, the room's bars (`b`) open the way on, and the win is kept in your save. Lose your last mask and you wake at your save point; once nobody is left fighting, the boss resets to full health. A boss hit costs one mask and knocks you back. Every player in the room fights the same boss, including one who joins mid-fight: the scene holds a pixelBosses `BossSpawn`, and in play one player's game spawns the boss for everyone (`MV.boss` returns that spawner; `:bossId()` on it gives the boss once it is there).
## Coming back
Rest at a save point and your position, abilities, map, opened gates and beaten bosses are saved to your own account (saveKit). When you join again, the kit waits for your save and for the bench's room to be built, makes the bench your respawn point, puts you there and checks that you are standing on it.
## Styles
One `theme` sets every row below at once: `MV.world({ theme = "scifi" })`, or live with `MV.setTheme("cartoon")`. Each part can also be set on its own (a room's `look` / `saveStyle`, a gate's `look`, `MV.boss({ sealStyle })`, `MV.world({ mapStyle, transition })`); the value `"theme"` means "follow the world theme".
The theme also picks a whole-frame art style: a styleKit stack of published look blocks from the Style Cookbook (styleKit, starterBlocks, toonBlocks, inkBlocks, paperBlocks), plus the kit's own `crtScanlines` and `ditherPalette` blocks in `blocks/` where nothing published does the job, listed in the last column. `MV.setTheme` swaps the stack with the rest of the set; `MV.world({ look = "gothic" })` keeps one look for every theme, `look = "none"` leaves the scene's own stack alone. From code: `require("sideScrollerKit.looks").apply("scifi")`, and `Looks.byId` holds the stacks to tune. The stack lives on the scene's synced StyleStack entity, so every player sees the same look; screen UI (HUD, map, toasts) is drawn after it and is never touched. Sprites, tiles and particles are alpha cards that write no depth, so depth lines ink only the painted parallax silhouettes and never the player or a sprite's rectangle; mesh-hull outlines (toonOutline, toonFarLine) draw nothing on cards and are not used. The first swap to a look in a session shows a blank frame for about a second while the engine builds its shaders. Undo with `Looks.apply("none")` or `StyleKit.clear()`. `docs/themes.png` shows the six looks on the Crystal Gallery (top row pixel, fantasy, scifi; bottom row cartoon, minimal, gothic).
| theme | looks | save point | map | transition | arena seal | boss bar | masks | frame look (styleKit) |
|---|---|---|---|---|---|---|---|---|
| `pixel` | pixel | bench | pixel | pixelate | portcullis | pixel | pixel hearts | ditherPalette (kit), chunkyPixels on the art grid, vignette (starterBlocks) |
| `fantasy` | fantasy | statue | parchment | fade | thorns | ornate | potions | inkNibLine brown (inkBlocks), paperParchment (paperBlocks), warm vignette, softGrain (starterBlocks) |
| `scifi` | scifi | terminal | holo | wipe | energy | hologram | pips | crtScanlines (kit), cool vignette, softGrain (starterBlocks) |
| `cartoon` | cartoon | campfire | cartoon | iris | rubble | bubbly | hearts | celFill (toonBlocks), bold depthLine (styleKit) |
| `minimal` | minimal | crystal | minimal | blinds | energy | line | pips | celPoster, calm colour (toonBlocks) |
| `gothic` | gothic | statue | gothic | fade | runes | ornate | candles | inkPool, inkPenLine (inkBlocks), duotone bone and crimson (styleKit), heavy vignette, softGrain (starterBlocks) |
Every variant, with its tags:
| Kind | Variant | Tags |
|---|---|---|
| look (gates, shrine, save points) | `pixel` | retro, 8-bit, chunky outlines |
| look | `fantasy` | stone, gold, warm, storybook |
| look | `scifi` | metal, neon, glow, tech |
| look | `cartoon` | bold outlines, bright, rounded |
| look | `minimal` | flat, clean, few colours |
| look | `gothic` | cathedral stone, bone, crimson glow, dark |
| gate | `crystal` | dash, breakable, ability |
| gate | `smash` | slam, floor, breakable, ability |
| gate | `grip` | wall jump, shaft, ability |
| gate | `thorns` | sword, cut, breakable |
| gate | `seal` | any ability, custom, magic |
| gate | `drop` | one way, hatch, floor, no ability |
| gate | `door` | key, lock |
| gate | `bars` | switch, boss reward |
| gate | `bossDoor` | arena, seals during the fight |
| shrine | one per look | ability pickup, pedestal |
| save point | `bench` | rest, cozy, Hollow Knight |
| save point | `campfire` | rest, warm, animated fire |
| save point | `statue` | rest, holy, fantasy |
| save point | `terminal` | save, sci-fi, screen |
| save point | `crystal` | save, magic, glow |
| map (navUiKit room map) | `pixel` | retro, 8-bit, dark |
| map | `parchment` | fantasy, hand-drawn, light |
| map | `holo` | sci-fi, neon, dark |
| map | `cartoon` | playful, bold, light |
| map | `minimal` | clean, flat, dark |
| map | `gothic` | gothic, ornate, dark |
| transition (screenWipes) | `fade` | classic, soft |
| transition | `iris` | cartoon, retro |
| transition | `wipe` | sci-fi, directional |
| transition | `pixelate` | pixel, 8-bit |
| transition | `blinds` | minimal, stylish |
| arena seal | `portcullis` | iron, castle, slams down |
| arena seal | `thorns` | vines, nature, grows |
| arena seal | `energy` | laser, sci-fi, crackling |
| arena seal | `rubble` | rocks, cave, crashes down |
| arena seal | `runes` | magic, glyphs, glowing |
| boss (pixelBosses) | `thornKnight` | melee, charge, thorns, two phases |
| boss | `hiveQueen` | flying, swarm, minions, two phases |
| boss | `ironWarden` | heavy, shockwaves, armour, two phases |
| theme | `pixel` `fantasy` `scifi` `cartoon` `minimal` `gothic` | sets all of the above together |
The **Hall of Echoes** in the Lantern Depths world shows every one of them side by side, labelled: a shelf per look with all nine gates, the switch, the signs, a shrine and the five save points; a shelf of the five arena seals; the three bosses; and an alcove where the five map styles and the five transitions play next to each other.
## Multiplayer
Every peer builds the same rooms and tests only its own player against gates, shrines, keys and save points, so each friend opens their own way. Progress lives in each player's own saveKit profile (`metroidvania` field), so it follows the account. Bosses are shared: friends in the arena fight the same boss together, and each one in the fight when it falls gets the win.
## What is in the package
- Modules: `api` (front door), `samples` (three ready-made rooms), `themes`, `rooms` (grid, text, exits), `gates` (who gets past which gate), `arena` (the boss fight's seal, win and reset), `progress` (abilities, map, gates, saves), `player`, `respawn` (back to your bench), `map` (this world's rooms and this player's progress fed to navUiKit's room map), `hud` (abilities, map button, hints, prompts, boss bar; toasts through navUiKit, transitions through screenWipes), `fx` (8-bit sounds, shake), `art` and `artgen` (the sprites, painted in code with pixelPaint).
- Art: one painted sprite-sheet texture per sprite and look under `art/<look>/`. There are no material assets: pixelSprites builds each sprite's material from its texture when the game runs, so the package ships the art and nothing generated from it.
- Components: `Metroidvania` (one per scene), `Room`, `Gate`, `Shrine`, `SavePoint`, `KeyPickup`, `BossArena`.
- Tests: `zero tests run sideScrollerKitTests` (room text, themes, art and sound, per-player progress, gates refusing and opening, the boss fight, live theme swaps).
- Guides: **How to make a metroidvania** and **Example: a second area with a double-jump gate and a save room**.
- `docs/reuse-review.md`: every installed part rated from 1 to 5 for how well it served a 2D metroidvania, and how much of the kit comes from installed parts. `docs/themes.png` shows the six looks.
## Installed packages
A fresh install of sideScrollerKit 1.4.12 brings these:
| Package | Version | What the kit uses it for |
|---|---|---|
| twoDKit | 1.3.4 | the platformer: player movement and feel, tiles from text, parallax backgrounds, camera, landing dust, dash trails |
| slash2D | 1.0.10 | the sword: side, up and down strikes, pogo, hit stop through juiceKit, a target registry the boss and thorn walls use |
| pixelBosses | 1.2.3 | the three bosses with their attacks and second phase; decisions on aiKit's behaviour tree, health as a SecondWind pool |
| aiKit | 1.2.5 | the behaviour tree the bosses decide with (its 3D Brain is not used; navKit comes with it) |
| safeGround2D | 1.0.2 | spikes and pits put you back on the last safe ground you stood on |
| screenWipes | 1.0.1 | the room transitions, in five styles |
| navUiKit | 1.3.3 | the room map (its `roomGrid` minimap and map screen, side view, each player's own rooms), toasts, room titles and NEW ABILITY cards |
| Trapline | 1.5.7 | masks (lives), checkpoints and respawn; its lives are SecondWind health underneath |
| SecondWind | 1.4.5 | health, damage and death underneath Trapline and slash2D (every player body carries SecondWind Vitals) |
| interactKit | 1.6.2 | locked doors, keys, the switch and bars: devices, key locks, items and wiring, per player with kept state |
| abilitiesKit | 1.1.3 | each player's abilities (passive abilities in a synced loadout) and the ability bar |
| soundstage | 2.1.3 | music per room and boss fight (sets, states, intensity) and ambience beds |
| Lifeline | 1.0.4 | respawn placement underneath Trapline |
| MatchFlow | 1.3.2 | comes with Trapline; not used directly |
| saveKit | 1.3.9 | each player's save on their own account |
| menusKit | 1.3.11 | comes with saveKit; not used directly |
| barsKit | 1.4.6 | the boss health bar |
| juiceKit | 1.2.10 | camera shake and hit stop for the kit's own moments |
| controlsKit | 1.2.8 | keyboard, gamepad and phone controls, with Attack and Map added |
| platformsKit | 1.6.1 | moving platforms in room text (`M`, `V`) through twoDKit, and any platformsKit kind with `MV.platform` |
| pixelPaint | 1.0.1 | paints every sprite of the kit in code |
| pixelSprites | 1.1.0 | draws the sprite sheets, building each sprite's material from its texture |
| pixelParallax | 1.0.3 | the parallax backgrounds, through twoDKit |
| chipSfx | 1.0.1 | the 8-bit sounds |
| styleKit | 1.4.18 | the frame look of each theme, as a stack of look blocks |
| starterBlocks | 1.0.32 | chunkyPixels, vignette and softGrain blocks |
| toonBlocks | 1.1.27 | celFill and celPoster blocks (cartoon, minimal) |
| inkBlocks | 1.0.18 | ink line and ink pool blocks (fantasy, gothic) |
| paperBlocks | 1.1.19 | the parchment paper block (fantasy) |
| toonMaterials | 1.0.11 | comes with toonBlocks: the cel-shaded surface its blocks draw with |
| materialLibraryKit | 1.4.3 | comes with toonMaterials; not used directly |
| lookbookKit | 1.0.32 | comes with styleKit: its look previews; not used directly |
## Known limits
- **Two sessions of one account count as one player** (engine issue #14448 on GitHub, open). Friends on two accounts each get their own abilities, gates, map and save; the same person in two windows shares one save.
- **The first switch to a theme's frame look in a session shows a blank frame for a moment** while the engine builds that look's shaders (1 to 8 s on a desktop, longer while the editor is busy). Later switches are instant.
- **The boss is spawned while you play, not stored in the scene.** A boss built into a scene as a synced entity never reaches a friend who enters play after the first player (engine issue #23921 on GitHub, open), so `MV.boss` places a pixelBosses `BossSpawn` and the lowest peer in the room spawns the boss once. In edit mode you see the spawner, not the boss.
- **Trapline fails some of its own packaging tests in your world.** Its test suite reads its own files at `/source/Trapline.package/...`, so installed under `/source/deps/` 10 of its 69 tests fail (README, guide and version checks). The game is unaffected, and this kit's suites, pixelBosses, slash2D, MatchFlow and barsKit all pass. **Running tests in a shared editing room changes the scene for everyone else in it** (engine issue #23636 on GitHub, open): run them when you are alone in the world.
- **A full test run touches barsKit's `Showcase` component inside your installed copy** (barsKit's own tests rewrite it with the same bytes), so `zm status` can show it as changed. `zm restore` that file before you commit.
- **Installs can fail right now** with "was not materialized 300 seconds after its record was written" (platform issue #24341, open); try the install again later. **Installs with many dependencies take a few minutes** (engine issue #21420 on GitHub, open), and an install brings each dependency's newest release, not the one this kit's world held. If something behaves differently after an install, `zero tests run sideScrollerKitTests` is the first check.
- **One installed copy still carries long dashes in its comments:** the engine library's own shadows shader module (owned by the engine team) has them in every release, so the copy pinned here does too. It does not change how anything plays.
- **On the web**, meshes and previews can take longer to appear (engine issue #22778 on GitHub, open). The ZeroMind page can show the previous release's description for a while after a push (#19258).
## Changelog
- **1.4.12**: the installed-packages table lists slash2D 1.0.10, pixelBosses 1.2.3, safeGround2D 1.0.2 and screenWipes 1.0.1, which now each carry their one-line install. No code change.
- **1.4.11**: Known limits drop the two web issues that are fixed (#22751, #20750); the web line keeps only #22778. No code change.
- **1.4.10**: documentation and version only. The art and guide READMEs say six looks (gothic was missing), the how-to guide gives the real install time, the reuse review lists the releases a fresh install brings, `MV.VERSION` reads the release again (it still said 1.4.8), and Known limits name what is true now (Trapline's packaging tests, barsKit's Showcase file, the one remaining long-dash copy, test runs in shared rooms, the install timeouts of #24341). Built on slash2D 1.0.9.
- **1.4.9**: one controlsKit release, 1.2.8, throughout: the kit, slash2D 1.0.8, twoDKit 1.3.4, saveKit 1.3.9, menusKit 1.3.11, interactKit, abilitiesKit and navUiKit all read the same build, so the controls, the sword and the map never land in different copies.
- **1.4.8**: every test passes in a fresh install. When the kit's own controls build cannot take the `metroidvania` scheme, it runs on controlsKit's `platformer` scheme (move, jump, dash, interact) and reads map and attack from their default buttons, retrying the scheme every two seconds; the control tests now check that the controls always have move and jump and that Space, K, D, Shift, X and M all read. Built on twoDKit 1.3.3.
- **1.4.7**: the sword and the map key work in a fresh install. Inside one installed package, controlsKit's `controls` and `schemes` modules can come from different builds, so the `metroidvania` scheme could land where the controls never see it: walking and jumping worked through twoDKit's fallback, but X and M read nothing. The sword (slash2D 1.0.7) and the kit now read attack and map from their default buttons whenever the live scheme lacks them. Checked by installing 1.4.6 into a brand-new world and pasting the example: walk, jump on Space and K, the dash, the crystal wall all worked; the sword did not, which this release fixes. A new test switches the controls to a scheme without map or attack and checks M and X still read.
- **1.4.6**: you can jump in a fresh install. 1.4.5 registered the `metroidvania` control scheme in one controlsKit build while the player body read another, so the player body stayed on controlsKit's twin-stick default: walking worked, jumping did not. The new `scheme` module registers the scheme in the kit's controls build, twoDKit's (`PP.registerScheme`, twoDKit 1.3.2) and slash2D's (`Slash.useScheme`, slash2D 1.0.6), and twoDKit 1.3.2 falls back to its platformer controls whenever a scheme is missing, so a player can always run and jump. New tests press Space, K, D, X and Shift and check what the controls read, and feed a pressed jump to the player's motor and check it lifts the body. The Hall of Echoes bosses can be woken, hit and beaten for practice.
- **1.4.5**: checked by installing the kit in a brand-new world and pasting the example above word for word: the player walks, jumps, takes the dash at the shrine, is stopped by the crystal wall and dashes through it, and the sword lands on the Thorn Knight. A fresh install can still hold several controlsKit builds side by side; the player body and the sword switch to the kit's scheme on the build they read, and the kit's own switch now retries once and warns at most once instead of filling the log every frame.
- **1.4.4**: the room map keeps your visited rooms in a published game: when you come back to your save, the map shows the rooms you had explored (navUiKit files a player's rooms under a key the published game only learns once you are known, so the kit hands them over again whenever that key changes or the map lacks a room your save has). The sprites ship as their painted textures only: pixelSprites 1.1.0 builds each sprite's material when the game runs, so the package carries no material assets and no generated preview pictures. The reuse review moves into the package (`docs/reuse-review.md`). The README example plays in a fresh world again: every part that reads input (twoDKit 1.3.1's player, the kit, slash2D, abilitiesKit, interactKit) now reads one controlsKit build, 1.2.4. A fresh install of 1.4.3 brought twoDKit reading controlsKit 1.2.3 beside them, two input loops kept resetting each other, the kit's `metroidvania` control scheme landed in one build while the player read the other, and the player never moved.
- **1.4.3**: checked against the example guide in a brand-new world. Changing the theme word on a built scene no longer trips the scene rebuild (theme listeners wait until the build finishes), and coming back at your bench no longer flashes the start room's name first. The example guide warns about the dead-end exit in step 2 and says where the Bell Tower goes in step 4.
- **1.4.2**: the ten-line README example gives its Thorn Knight 12 health (checked in a brand-new world: at the full 24 a first fight is too long for a three-room taste).
- **1.4.1**: boss fights sync for every player. `MV.boss` used to build the boss into the scene as a synced entity, and a player who entered play after the first never got its state: the boss stayed dormant at full health on their screen while the first player fought it. The boss is now spawned at runtime by exactly one player's game through pixelBosses 1.2.0's `BossSpawn`; `BossArena` finds it through its new `spawner` field (`boss` still takes a hand-placed boss). `MV.boss` takes the same options; it returns the spawner entity.
- **1.4.0**: built on more published kits. Locked doors, keys, the switch and bars are interactKit devices, locks, items and wiring, still per player and saved (interactKit 1.6.0 added kept device state and items you draw yourself for this). Abilities are passive abilitiesKit abilities in each player's synced loadout, shown on abilitiesKit's ability bar (abilitiesKit 1.1.0 added passive abilities for this). Music and ambience from Soundstage, per room, with combat music and its intense take in boss fights. The kit's shakes and hit stops through juiceKit. `MV.platform` places any platformsKit kind; the Crystal Gallery gets two crumbling ledges. Rooms take `music` and `ambience`. `MV.setLook` and a world `look`.
- **1.3.3**: the room map is navUiKit's (1.3.0): its `roomGrid` minimap and map screen in side view, fed with this world's rooms and each player's own visited rooms, used exits, beaten boss and taken shrines. The roomMap2D package is gone (navUiKit took over everything it did). A sixth map style, `gothic`, which the gothic theme now uses. With the minimap on, a tap on it opens the map; with it off, the MAP button stands in the corner.
- **1.3.2**: renamed from metroidvaniaKit to **sideScrollerKit** (same ZeroMind package; saves are kept). Bosses take hits where you see them (pixelBosses 1.0.4, slash2D 1.0.3): before, only swings at the boss's starting spot counted. Coming back puts you at your bench on a published world too: the kit waits for the bench's room, makes the bench your respawn point first, then checks you are standing there. A ninth gate, the one-way **drop-through hatch** (`h`). Five **arena seal** styles of their own (portcullis, thorns, energy, rubble, runes), picked by the theme or `MV.boss({ sealStyle })`. The room map is its own package, **roomMap2D**; the room transitions are **screenWipes**; toasts, room titles and ability cards are **navUiKit** toasts. `MV.sample` and a ten-line example. Tests for gates refusing and opening, the boss fight sealing, winning and resetting, and live theme swaps. The Hall of Echoes shows the map styles, transitions and seals side by side.
- **1.3.1**: a Known limits section.
- **1.3.0**: polish. The HUD fits a phone (ability tags wrap, a smaller minimap with the MAP button under it, the full map and titles fit the screen). Footsteps while running, and a roar, shake and hit stop when the boss changes its attacks at half health.
- **1.2.1**: the README example's second ledge is wider, so two ordinary jumps reach the shrine.
- **1.2.0**: the safe-ground hazard respawn became its own package, **safeGround2D**. Every dependency pinned by its ZeroMind guid. A test suite ships with the kit.
- **1.1.1**: preview pictures for the gothic, thorn wall and ability seal art.
- **1.1.0**: thorn wall (`t`) and ability seal (`q`) gates; a sixth look and theme, `gothic`; `cut` and `seal` sounds. A gate placed with `MV.gate` and no id no longer closes again the moment it opens.
- **1.0.5**: every piece reads the player once per frame.
- **1.0.4**: a player with no save starts with nothing.
- **1.0.3**: built on twoDKit 1.3.0 as published (double jump, down-slam, joined rooms).
- **1.0.2**: cover picture.
- **1.0.1**: bosses spawn synced so friends fight the same boss; the boss name shows over the health bar.
- **1.0.0**: first release.
# 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.bt` behaviour 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.pool` health record on the boss's authority (its damage rules, death), mirrored into the synced `health` field.
- **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
```lua
-- 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:
```lua
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`
```lua
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:
```lua
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 `move` field.
- 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`, `activate` and `reset` called on another peer are sent to the authority, which applies them; `health`, `phase` and `state` replicate 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 the `pixelBosses.damage` channel; 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 with `entity.spawnSynced` inside 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 with `entity.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.spawnSynced` plus a Boss2D works the same way; a plain `entity.spawn` boss 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' `sprite` shader: 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: `Brain` adds a navKit `NavAgent` and moves with `actions.moveTo` on a 3D navmesh, turns by yaw, senses through 3D sight cones (`senses`) and reads health from SecondWind `Vitals` (`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**: `BossSpawn` component: a boss placed in a scene now reaches every player. Bosses built with `entity.spawnSynced` inside 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 is `Bosses._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.get` always 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.
# slash2D: a Hollow Knight style sword slash for 2D platformers
Give a **twoDKit** platformer player a nail slash in one line. Press attack and a crisp, four-frame pixel slash arcs out where you face; hold **up** to slash upward, hold **down in the air** to slash downward. A hit freezes the game for a beat (hit-stop), shakes the camera, bursts a pixel spark and plays an 8-bit clank; a side hit pushes you back a little, and a **down-slash hit pogos you** upward and refills your dash, so you can bounce across spikes and enemies. Every player sees every other player's swings and sparks.
Anything can be hit: register an entity with `Slash.addTarget` and you get an `onHit` call with the damage and direction. Entities with **SecondWind** `Vitals` (health) are hit automatically through SecondWind's own multiplayer-safe damage, so existing enemies and training dummies work with no code.

## Install
In the engine shell: `zero zeromind installAsset 37cb0d20-956d-46d3-b41f-697f4ba888b7` (or search ZeroMind for "slash2D" or "2D sword slash"). It needs twoDKit (which brings controlsKit, pixelSprites, pixelPaint, chipSfx, Trapline and SecondWind).
## Use it (works as written)
In a scene's `build.luau`:
```lua
local PP = require("twoDKit.api")
function content()
PP.level({ theme = "cave" })
local players = PP.player({ character = "knight" })
players.body.component.add("Slash2D", {})
PP.hud()
end
```
Press Play and attack with **X**, **H** or the **left mouse button**, the pad's **right trigger** (or left shoulder), or the **ATTACK** touch button beside jump.
Make something hittable (in a component, or a scene's `entrypoint.luau` `onLoad`, on every peer):
```lua
local Slash = require("slash2D.api")
local dummy = entity.find("Dummy")
local handle = Slash.addTarget(dummy.id, {
halfW = 0.4, halfH = 0.6, offsetY = 0.6, -- a box around its feet position, in tiles
onHit = function(hit)
print("hit for", hit.damage, "from", hit.attacker, "dir", hit.dirX, hit.dirY)
return true -- false refuses the hit (no spark, no pogo)
end,
})
-- later: Slash.removeTarget(handle)
```
## Controls
Slash2D switches its body's `Player2D.scheme` from `platformer` to **`platformerSlash`** when play starts (set `useScheme = false` to leave it). `platformerSlash` is controlsKit's `platformer` plus `attack`:
| Device | Attack |
|---|---|
| Keyboard | `X`, `H` (J stays dash, K jump) |
| Mouse | left button |
| Gamepad | right trigger, or left shoulder |
| Touch | ATTACK, in the right-hand diamond beside jump (crouch moves to a small button above it) |
Directions come from `move`: up held = up slash; down held while airborne = down slash; otherwise the way you face.
Another kit can extend the scheme:
```lua
local Slash = require("slash2D.api")
local CKSchemes = require("controlsKit.schemes")
local s = Slash.schemeWithAttack("platformer")
s.actions.map = { kind = "button", label = "Map", keys = { "KeyM", "Tab" }, pad = { "back" } }
CKSchemes.register("metroidvania", s)
-- then set Player2D.scheme = "metroidvania" and Slash2D.useScheme = false
```
## API (`local Slash = require("slash2D.api")`)
| Call | What |
|---|---|
| `Slash.addTarget(entityId, opts) -> handle` | Make an entity hittable on this peer. `opts`: `halfW`, `halfH` (half extents, tiles), `offsetX?`, `offsetY?` (box centre from the entity's position), `box?() -> { x, y, halfW, halfH }?` (a live box that replaces the entity-based one, for a target drawn away from its entity; nil = not hittable now), `onHit(hit) -> boolean?`. `hit = { damage, dirX, dirY, attacker, x, y }` (attacker = the body's entity id, x/y = where the boxes overlap). Return `false` to refuse; `true` or `nil` counts the hit. |
| `Slash.removeTarget(handle)` | Stop it being hittable. |
| `Slash.on("swing" \| "hit" \| "*", fn) -> conn` | Events on every peer. `swing`: `{ player, dir, dirX, dirY, x, y, isLocal }`. `hit`: `{ player, target, damage, dir, dirX, dirY, x, y, isLocal, pogo }`. `conn:Disconnect()`. |
| `Slash.schemeWithAttack(baseName) -> scheme` | A fresh copy of a controlsKit scheme with `attack` added (keys, pad, touch), for you to extend and register. |
| `Slash.SCHEME` | `"platformerSlash"`. |
| `Slash.targets()`, `Slash.isTarget(id)`, `Slash.overlaps(...)`, `Slash.VERSION` | Helpers. |
**How hits travel.** Targets are registered on every peer. The attacking player's own peer tests the swing against each target's box at the entity's *current* position and calls `onHit` **on that peer**, so the target's code routes damage to whoever owns the target (a synced field, a message, or `SecondWind.api`'s `damage`, which does that for you). The swing and the spark reach every peer through two synced fields on Slash2D.
## Slash2D fields
| Field | Default | What |
|---|---|---|
| `action` | `attack` | controlsKit action that swings. |
| `damage` | `1` | Damage passed to `onHit`. |
| `cooldown` | `0.33` | Seconds between swings. |
| `reach`, `width` | `1.8`, `1.3` | Hitbox in tiles: side = reach wide x width tall; up/down = width wide x reach tall. |
| `active` | `0.12` | Seconds a swing can land hits (each target once per swing). |
| `pogoSpeed` | `15` | Bounce speed (tiles/s) on a down-slash hit; 0 = off. Refills the dash. |
| `recoil` | `0.4` | Tiles you are pushed back on a side hit (stops at walls). |
| `hitStop`, `shake` | `0.055`, `0.12` | Hit-stop seconds (juiceKit hitstop, real time, cannot stick) and camera shake (twoDKit Camera2D) on your own hits. |
| `useScheme` | `true` | Switch Player2D's `platformer` scheme to `platformerSlash`. |
| `hitVitals`, `vitalsDamage` | `true`, `20` | Hit SecondWind Vitals and how much. |
| `vitalsHalfW`, `vitalsHalfH` | `0.5`, `0.6` | Box used for a Vitals entity (centred `vitalsHalfH` above its position). |
| `hitPlayers` | `false` | Also hit other players' Vitals (PvP). |
| `effects` | `true` | Draw and play sounds on this peer. |
| `swing`, `hitFx` | | Synced, read-only: the last swing and hit. |
Methods: `swingNow(dir?)` (owner; swing now), `hitbox()`, `counts()`.
## What is inside
- `Slash2D.component`: the attack. `api.module`: targets, events, schemes. `schemes.module`: `platformerSlash` and `withAttack`.
- `art/slash.texture` + `slash.material`: the 4 x 4 sheet (side, up, down slash, hit spark), painted by `painter.module` with pixelPaint; drawn with pixelSprites.
- `sounds/`: `swing`, `hit`, `pogo`, synthesised with chipSfx by `sfx.module` (they follow chipSfx's volume and mute).
- Guide: **How to add a sword slash attack to a 2D platformer** (`slash2D.package/how-to-add-a-sword-slash-attack-to-a-2d-platformer`).
## Changelog
- **1.0.10**: the description and README give the one-line install with this package's id. No code change.
- **1.0.9**: `Slash.VERSION` names the release again (1.0.8 still read 1.0.7).
- **1.0.8**: states controlsKit 1.2.8, the release every part of sideScrollerKit now shares (no code change).
- **1.0.7**: the sword always swings. When the live controlsKit scheme in the build Slash2D reads has no `attack` action (a world can hold several controlsKit builds, and a game's own scheme can land in another one), Slash2D reads the attack's default buttons straight from the engine's input: X, H, left mouse, the pad's right trigger or left shoulder. New `Slash.attackDown()`.
- **1.0.6**: `Slash.useScheme(name, scheme)`: a game that gives the player its own scheme (with an `attack` action) registers it in the controlsKit build slash2D reads and switches that build to it, so the attack button reads even when the world holds several controlsKit builds.
- **1.0.5**: the slash sheet ships as a texture only; pixelSprites 1.1.0 builds its material at runtime, so the package carries no material asset and no generated preview picture. The sword plays exactly as before.
- **1.0.4**: the hit stop on your own hits is juiceKit's (`juiceKit.hitstop`: one keyed time-scale hold with a real-time watchdog, so it can never stay stuck after a scene swap, which twoDKit's freeze could). Regression test for live target boxes. New dependency: juiceKit.
- **1.0.3**: a target can give a live hit box (`box` in `Slash.addTarget`, read with `Slash.targetBox`), so something drawn away from its entity, like a moving boss, is hit where it is seen.
- **1.0.2**: dependencies pinned by guid; a test suite (`zero tests run slash2DTests`).
- **1.0.1**: preview images; runs on twoDKit 1.3.0.
- **1.0.0**: first release.