Log inGet started
World

Pixel Ledges: 2D Platformer Kit with Sprites, Tilemaps, Wall Jumps and Dash

README.md

level

Turns a platformer level typed as rows of text characters into a tilemap: a grid of cells, the tile list (with the right autotiled edge and corner tile in every ground cell, one-way platform ends, spikes facing away from their wall, scattered decorations), the mesh data to draw it, merged collision rectangles with no inner seams, spike hit tests and the list of things placed in it (start, checkpoints, gems, goal, moving platforms). Pure data and maths: it spawns nothing.

twoDKit.Level2D is the component that builds a playable level from this; call the module directly for tools, tests, or a level built your own way.

Text format

Rows are read top to bottom; cell (x, y) counts x from the left and y from the BOTTOM row, from 0. One character is one world unit (16 art pixels). Default legend (Level.DEFAULT_LEGEND, pass your own to parse):

CharKindCharKind
#solid ground=one-way platform (jump up through it)
^spikesBback wall (drawn behind, no collision)
P or Splayer startCcheckpoint
Mmoving platform, side to sideVmoving platform, up and down
ogemGgoal
*forced decoration. or spaceempty

#, =, ^ and B become cells; the rest become markers. Unknown characters count as empty and are reported. A marker inside a back-wall shaft keeps the wall behind it.

API

  • parse(text, legend?) -> (Grid, problems): Grid = { width, height, cells, markers, text }, cells[y + 1][x + 1] one of "solid", "oneway", "spike", "back", "empty"; markers are { kind, x, y, char, index }.
  • kind(grid, x, y, outside?): the cell kind; outside the grid counts as solid unless outside is given. isSolid(grid, x, y).
  • mask(grid, x, y): eight-neighbour mask for twoDKit.autotile.
  • spikeDir(grid, x, y): "up", "down", "left" or "right", away from the solid it is fixed to.
  • tiles(grid, { decorChance?, seed? }): every tile to draw { x, y, tile, z }; decorations grow on empty cells above ground, placed by a deterministic hash of seed.
  • meshData(tiles, name?): positions / normals / uvs / indices for renderer.mesh.create, in level-local units.
  • rects(grid, kind): cells of one kind merged into few rectangles { x, y, w, h } (one-way runs stay one row tall).
  • spikeBox(dir), spikeHit(grid, x0, y0, x1, y1): spike danger boxes and a level-local overlap test.
  • toText(grid): the grid as text again.
local Level = require("twoDKit.level")
local grid, problems = Level.parse([[
..P.......o.........G.
.......====......####.
....C..^^......M......
######################
]])
local mesh = renderer.mesh.create(Level.meshData(Level.tiles(grid, { seed = 3 })))
for _, r in Level.rects(grid, "solid") do print(r.x, r.y, r.w, r.h) end