Sprites — blit sources for the canvas.
Everything here is duck-typed for canvas:blit: a sprite is any table that
carries a surface (a term.gfx_core userdata) plus a source sub-rect
(sx, sy, sw, sh) and its size (w, h). Four kinds:
sprite(source, opts) — view a region of a canvas/surface/sprite.
sheet(source, opts) — a sprite atlas; sheet:frame(i_or_name) -> sprite.
art(spec) — pseudo-pixel-art rasterized once from a char-map +
palette at an integer scale. Monochrome art baked as
a white mask can be recoloured per-blit via tint.
anim(spec) — a frame sequence with per-frame durations; itself a
blit source that delegates to the current frame.
| Name | Signature |
|---|---|
sprite | sprite(source, opts) -> sprite, err |
sheet | sheet(source, opts) -> sheet, err |
art | art(spec) -> sprite |
anim | anim(spec) -> anim |
sprite(
source,opts) ->sprite,err
Create a sprite viewing a region of a canvas/surface/sprite
opts:
sx, sy (1-indexed top-left, default 1,1),
sw, sh (size, default the full source).
The returned sprite shares the source pixels — it is a lightweight view, not a copy.
sheet(
source,opts) ->sheet,err
Create a sprite sheet (atlas) over a source image
Two ways to define frames:
Tile grid: tile_w, tile_h (required), margin (border, default 0),
spacing (gap between tiles, default 0). Frames are numbered left-to-right,
top-to-bottom starting at 1.
Explicit: frames — an array of {x,y,w,h} rects (1-indexed) and/or a map
of name -> {x,y,w,h}.
sheet:frame(index_or_name) returns a sprite; sheet:nframes() the count.
art(
spec) ->sprite
Create a pseudo-pixel-art sprite from a char-map and palette
spec:
rows (array of equal-ish strings),
palette (map char -> {r,g,b,a}; unmapped chars and spaces are transparent),
scale (integer block size per cell, default 1),
glitch_color (colour used for cells the :glitch method toggles on; defaults to the first palette entry).
The art is rasterized once into its own surface and returned as a sprite, so
it blits/flips/tints/atlases like any other. A monochrome mask (one palette
entry of white) can be recoloured at blit time via the tint option.
anim(
spec) ->anim
Create an animated sprite from a frame sequence
spec:
either frames (an array of sprites) or {sheet=<sheet>, frames=<array of indices/names>};
durations (a single number of seconds applied to every frame, or an array of per-frame seconds);
loop (true = forever, false = stop on the last frame, or a positive integer loop count);
on_end (called once when a non-looping/counted animation finishes).
The anim is itself a blit source delegating to the current frame: call
:update(dt) each tick, then canvas:blit(anim, x, y) (or anim:current()).