Sprite — movable image objects

A sprite is a positioned, movable image — the graphics primitive most of the family moves. Sprites render on either backend — FireStorm hardware sprites or the software chipset — behind one API. And a sprite is a target, so motion moves it, tween fades it, and collision uses its bounds.

Status: design. Not built yet.

What it is

A sprite is an image (or animation frames) plus a position, size, flip, palette, z-order, and visibility — the thing you actually see move on screen. Because a sprite is registered as a stage target, the entire family acts on it without special cases: motion writes its position, tween its alpha/scale/colour, collision reads its bound, state decides which animation it plays.

Two backends, one sprite

A sprite renders through either the FireStorm hardware sprite engine (fast, chipset-bounded in count and size, tied to the FPGA image) or the software chipset (always available, ImGui resolution, more flexible counts). The choice is per-sprite (or the default), and the calls are identical — so a sprite authored for the software chipset to overlay an emulated machine is the same object as one drawn by the hardware chipset.

Frames and animation

A sprite can hold a sheet of frames; animate by stepping frames on the tick (a frame sequence at a rate) or by driving its properties through tween / timeline. Frame animation and property animation compose — a walk cycle's frames and a squash-and-stretch tween at once.

As a target

Position, scale, rotation, and alpha are the sprite's target properties (written by motion/tween); its box or circle is its collision bound. So sprites are the natural targets for the whole family — most of what motion, state, path, and spawn move is a sprite.

Parenting — chains and trees

A sprite can be parented to another: its position, scale, and rotation become relative to the parent, and the two compose up the chain. Move, scale, or rotate the parent and every descendant follows — a chain (A → B → C) or a tree (one parent, many children, each with children of its own) transforms as one articulated whole.

The composition is the same affine stack motion already uses per target — a child's world transform is its parent's world transform composed with its own local one:

• position — the child's local offset is scaled and rotated by the parent before being added, so a child orbits as the parent rotates and spreads as the parent scales;
• rotation — parent rotation + local rotation;
• scale — parent scale × local scale.

Because it is pure affine composition it is deterministic, and it composes with the rest of the family for nothing: drive the parent with motion and the children follow the path; tween the parent's scale and the whole tree grows; a state machine flips the parent and the rig mirrors with it.

The uses are the rig-and-attachment ones — a character (torso → arm → hand), a vehicle (body → turret → barrel), an orrery (sun → planet → moon), a boss assembled from parts, a HUD group that moves together. In the register map each sprite carries a parent index; the chipset resolves the forest in one pass per frame — each node's world transform cached once, children reading it — so depth is cheap, bounded only by the per-frame budget.

On the stage

A sprite is a registry target, drawn in the render pass through its backend after React. It writes no simulation state at render; the simulation moved it earlier, in Advance.

Clients

• Luau — require("sprite"): create sprites, set image / frames / flip / z, animate.
• AntBASIC — a SPRITE verb creates one and returns a target for DRAW / MOVE / TWEEN.

Related

• software chipset / FireStorm — the two backends · motion / tween / collision — what acts on it · image — its pixels · spawn — pooling many of them
• luau_sprite — the Luau API