source(src) -> surface, sx, sy, sw, sh

Resolve a source to its surface and rect

A canvas or a raw surface supplies its whole area; a sprite, or any table with a surface, its own rect, each field left out standing for the whole. Nil for anything else.

rgba(col) -> r, g, b, a

A colour's four bytes

col is {r, g, b, a}; a left out is 255. The four stand last in a call's arguments, where a multiple return is read whole.

sprite(src, opts) -> sprite, err

Create a sprite viewing a region of a canvas/surface/sprite

opts.sx, opts.sy set the top-left, default 1, 1. opts.sw, opts.sh set the size, default the whole source. The rect counts on the surface, whatever the source: a sprite of a sprite does not offset by its parent's rect. The sprite shares the source's pixels; it is a view, not a copy. Returns nil and an error for a source that is not a canvas, surface or sprite.

sheet(src, opts) -> sheet, err

Create a sprite sheet (atlas) over a source image

Frames come from a tile grid or from explicit rects.

opts field	description
tile_w, tile_h	tile size; required without frames
margin	border around the grid, default 0
spacing	gap between tiles, default 0
frames	an array of {x, y, w, h} rects, a map of name -> {x, y, w, h}, or both

Grid frames count from 1, left to right, then top to bottom.

sheet:frame(index_or_name) returns the frame's sprite, or nil. sheet:nframes() returns the count of numbered frames.

art(spec) -> sprite

Create a pseudo-pixel-art sprite from a char-map and palette

spec field	description
rows	array of strings, one character per cell
palette	map of character to {r, g, b, a}; other characters are transparent
scale	pixels per cell side, default 1
glitch_color	colour of a cell glitch turns on; default the first palette entry

The art is drawn once into its own surface. The result blits, flips and tints like any sprite. Art drawn in white recolours at blit time through tint.

art:glitch(prob, color) returns a new art sprite with each cell turned on or off at random, with probability prob (default 0.15). A cell turned on takes color, default glitch_color.

anim(spec) -> anim, err

Create an animated sprite from a frame sequence

spec field	description
frames	an array of sprites; with sheet, an array of frame indices or names
sheet	the sheet frames names
durations	seconds per frame: one number for all, or an array; default 0.1
loop	true (default) loops forever, false stops on the last frame, a number loops that many times
on_end	fn(anim), called once when the animation finishes

A durations array shorter than the frames repeats its last entry. A duration of 0 or less answers nil and an error: update steps the clock down by a frame's duration until it falls under, which a nought never does.

The anim blits as its current frame. Call anim:update(dt) each tick, then canvas:blit(anim, x, y).

method	description
anim:update(dt)	advance by dt seconds; holds the last frame once finished
anim:current()	the current frame's sprite
anim:done()	true once finished
anim:reset()	back to the first frame, unfinished