# 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.