Log inGet started
World

Lantern Depths: Find the Shade Dash, Slay the Thorn Knight

Branchmain
Branchesmain
Commitda5ac13948

README.md

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.

The slash sheet: side, up and down arcs and the hit spark

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:

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):

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:

DeviceAttack
KeyboardX, H (J stays dash, K jump)
Mouseleft button
Gamepadright trigger, or left shoulder
TouchATTACK, 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:

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"))

CallWhat
Slash.addTarget(entityId, opts) -> handleMake 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) -> connEvents 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) -> schemeA 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.VERSIONHelpers.

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

FieldDefaultWhat
actionattackcontrolsKit action that swings.
damage1Damage passed to onHit.
cooldown0.33Seconds between swings.
reach, width1.8, 1.3Hitbox in tiles: side = reach wide x width tall; up/down = width wide x reach tall.
active0.12Seconds a swing can land hits (each target once per swing).
pogoSpeed15Bounce speed (tiles/s) on a down-slash hit; 0 = off. Refills the dash.
recoil0.4Tiles you are pushed back on a side hit (stops at walls).
hitStop, shake0.055, 0.12Hit-stop seconds (juiceKit hitstop, real time, cannot stick) and camera shake (twoDKit Camera2D) on your own hits.
useSchemetrueSwitch Player2D's platformer scheme to platformerSlash.
hitVitals, vitalsDamagetrue, 20Hit SecondWind Vitals and how much.
vitalsHalfW, vitalsHalfH0.5, 0.6Box used for a Vitals entity (centred vitalsHalfH above its position).
hitPlayersfalseAlso hit other players' Vitals (PvP).
effectstrueDraw and play sounds on this peer.
swing, hitFxSynced, 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.