Log inGet started
World

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

README.md

pixelPaint: paint pixel art in code

A small raster painter for making pixel-art sprites, sprite sheets, tile sets and parallax layers in code, in any Zero world: rectangles, lines, ellipses, polygons, ordered Bayer dithering, dithered gradients through a colour ramp, 1 px outlines, ASCII-art stamps, blits and colour replacement, with seeded random numbers and tileable value noise so the same code paints the same art on every machine. It saves the result as a nearest-filtered, lossless texture asset and, if you like, a material ready to draw.

Every character, tile set, background, gem and effect in twoDKit (the 2D pixel platformer kit) is painted with it.

Install

zero zeromind installAsset 8606dc47-a973-4bce-83ed-f26e7f288526 in the engine shell, or search ZeroMind for "pixelPaint". It has no dependencies. Materials it writes name the pixelSprites.sprite or pixelParallax.parallax shader (or one you choose); install pixelSprites or pixelParallax, or pass your own shader, to draw them.

A sprite in ten lines

local Paint = require("pixelPaint.paint")
local c = Paint.canvas(16, 16)
c:rect(2, 4, 12, 10, Paint.hex("#8a5a2b"))              -- crate body
c:dither(2, 9, 12, 5, Paint.hex("#5e3a1a"), 0.5)        -- shaded lower half
c:line(2, 4, 13, 13, Paint.hex("#5e3a1a"))              -- brace
c:outline(Paint.hex("#1c120a"))                         -- 1 px outline around it
Paint.save(c, "/source/myArt", "crate", {})             -- /source/myArt/crate.texture
Paint.material("/source/myArt", "crate", "myArt.crate") -- /source/myArt/crate.material

Run it once from a script or the shell (luau myPainter.luau); the texture and material are ordinary assets of your world from then on. Change the code and run it again to repaint them.

API

Colours and randomness:

  • Paint.hex("#rrggbb" | "#rrggbbaa", a?), Paint.ramp({ hex... }), Paint.mix(a, b, t), Paint.shade(c, factor), Paint.CLEAR.
  • Paint.rng(seed): xorshift32 with next(), int(a, b), chance(p), pick(list); the same art on every run and machine.
  • Paint.noise(x, y, seed, period?): 2D value noise 0..1, tileable when period is given. Paint.bayer(x, y), 4 x 4 ordered-dither threshold.

Canvas (Paint.canvas(w, h, fill?)), methods called with ::

  • set, get, alpha, inside, clear(x, y, w, h).
  • rect, frame (1 px border), line, ellipse(cx, cy, rx, ry, c, outlineOnly?), circle, poly({ x1, y1, x2, y2, ... }, c).
  • dither(x, y, w, h, c, level, onlyOpaque?), gradient(x, y, w, h, ramp).
  • outline(c, x?, y?, w?, h?, diagonal?): 1 px outline outside every opaque pixel in the region.
  • rows(x, y, { "..ab.." }, palette, flipX?): paint ASCII art; . and space are skipped.
  • blit(src, sx, sy, w, h, dx, dy, flipX?), replace(from, to), copy(), toPng().

Saving:

  • Paint.save(canvas, folder, name, { wrap? }) -> path: writes <folder>/<name>.texture (sprite, nearest filter, no mips, lossless; wrap = "repeat" repeats horizontally for backgrounds). Saving over an existing texture rewrites its source image.
  • Paint.material(folder, name, textureIdentity, shader?) -> path: writes <folder>/<name>.material on pixelSprites.sprite, on pixelParallax.parallax when shader == "parallax", or on any shader identity containing a dot (cutout, alpha cutoff 0.5).
local Paint = require("pixelPaint.paint")
local c = Paint.canvas(16, 16)
c:rect(0, 0, 16, 16, Paint.hex("#3a2a1e"))
c:dither(0, 8, 16, 8, Paint.hex("#2a1d14"), 0.5)
c:frame(0, 0, 16, 16, Paint.hex("#120c08"))
Paint.save(c, "/source/myArt", "crate", {})
Paint.material("/source/myArt", "crate", "myArt.crate")

Changelog

  • 1.0.1: the install line names this package's id.
  • 1.0.0: first release, split out of twoDKit (where it was twoDKit.paint, which still works). Paint.material also takes any shader identity.