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_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.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:
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()).