# paint
A small raster painter for making pixel art in code (rectangles, lines, ellipses, polygons, ordered Bayer dithering, dithered gradients through a colour ramp, 1 px outlines, ASCII-art stamps, blits and colour replacement), plus deterministic random numbers and tileable value noise, and saving the result as a nearest-filtered texture asset and a material on the kit's sprite or parallax shader.
Every sprite sheet, tile set and background in twoDKit is painted with it. `require("pixelPaint.paint")`; twoDKit also offers it as `twoDKit.paint`.
Coordinates are pixels with (0, 0) at the TOP-LEFT and +y down. Colours are `{ r, g, b, a }` tables, 0..255. Painting with partial alpha blends over what is there; alpha 0 or 255 writes the pixel as-is.
## 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`, or `pixelParallax.parallax` when `shader == "parallax"` (cutout, alpha cutoff 0.5).
```luau
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")
```
# 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
```luau
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).
```luau
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.