Pixel Ledges: 2D Platformer Kit with Sprites, Tilemaps, Wall Jumps and Dash
README.md
motor
The 2D platformer movement itself as a pure, testable step function: running with acceleration and turn-around, variable-height jump with apex hang, coyote time, jump buffer, wall slide and wall jump, an 8-way dash, ceiling-corner and ledge-lip corner correction, dropping through one-way platforms and riding moving ground. It touches no entities: you hand it a state, a movement feel (twoDKit.feels), this step's input and a collision "world", and it moves the state.
Use it to drive a character with your own collision, or to test level layouts and feels headlessly against a level grid with Motor.gridWorld. It mirrors the motor inside twoDKit.Player2D, which runs the same rules against the engine's physics.
API
Motor.new(x, y, halfWidth, halfHeight) -> State: a body standing with its feet at (x, y); the box is centred at (x, y + halfHeight).Motor.reset(st, x, y): put it at rest at a new point.Motor.step(st, feel, input, dt, world, opts?): one fixed step.input = { x, y, jumpHeld, jumpPressed, dashPressed, down }(x, y in -1..1; passjumpPressed/dashPressedonly on the step the button went down).opts.canDash/opts.canWallJump = falseturn those moves off.opts.airJumps(default 0) allows that many jumps in mid-air, refilled on the ground and on a wall like the dash: a buffered jump in the air that is neither a coyote jump nor a wall jump spends one, resets the vertical speed to a jump offeel.airJumpHeight or feel.jumpHeight * 0.85tiles and adds"airJump".opts.canSlam(default false) turns a fresh press ofinput.downin the air (not while dashing) into a slam:vx = 0,vy = -(feel.slamSpeed or 30), no gravity or steering until grounded; it adds"slam", then"slamLand"on the ground withst.slamGround = st.groundIdandst.slamAt = st.clock. Down + jump on a one-way platform is still a drop (that starts grounded).Motor.anim(st, moveX, canWallJump?) -> (anim, facing): the animation to show: idle, run, jump, fall (also while slamming), wallSlide, dash or land, and the facing (wall slides face the wall's side).Motor.move(st, world, axis, d),Motor.probe(st, world, dx, dy, dist): the collision helpers the step uses.Motor.gridWorld(grid, ox?, oy?): a world over atwoDKit.levelgrid (solid and one-way cells) placed at (ox, oy).Motor.jumpVelocity(height, gravity),Motor.SKIN.
State fields include x, y, vx, vy, grounded, groundId, wallDir, coyote, buffer, dashes, dashTimer, facing, airJumpsLeft, slamming, slamGround, slamAt. Each step appends what happened to st.events ("jump", "airJump", "walljump", "dash", "drop", "slam", "slamLand", "land"); clear it when you have read it.
The world
A table answering collision for the state's box:
world.cast(st, hx, hy, dx, dy, dist) -> hit?: sweep a box of half size (hx, hy) along (dx, dy);hit = { distance, id?, oneWay?, normalY?, surfaceVX? }.world.groundPos(id) -> (x, y)?: optional: where a ground entity is now (moving platforms carry the body).world.dropThrough(st, id): optional: called when the body starts dropping through a one-way platform.
local Motor = require("twoDKit.motor")
local Feels = require("twoDKit.feels")
local Level = require("twoDKit.level")
local grid = Level.parse("......\n......\n######")
local world = Motor.gridWorld(grid)
local st = Motor.new(1.5, 1, 0.3125, 0.625)
local feel = Feels.get("tight")
Motor.step(st, feel, { x = 0, y = 0, jumpHeld = true, jumpPressed = true, dashPressed = false, down = false }, 1 / 60, world)
for _ = 1, 30 do
Motor.step(st, feel, { x = 1, y = 0, jumpHeld = true, jumpPressed = false, dashPressed = false, down = false }, 1 / 60, world)
end
print(st.x, st.y, table.concat(st.events, ","))