UI/Renderable: Sprite

What this page covers #

sprite renders atlas-driven textured frames and supports fast runtime frame switching.

By task #

Define sprite frames and atlas rectangles: see Definition
Switch frames at runtime: see Runtime control
Build a simple frame animation loop: see Example: simple animation

Textured quad driven by frames from a sprite atlas. Each frame defines a source rect (aabb), visual size, frame metadata origin, and colour tint. Switch frames to animate.

Import #

Definition #

Renderable options object passed to UI.createElement(..., { renderable: { ... } }):

SpriteRenderable

Textured quad driven by frames from a sprite atlas.

type 'sprite' - Renderable type identifier.
texture string - Required. Path to the sprite atlas texture.
frames Array<SpriteFrame> - Array of frame definitions.
frame number optional - Initial frame index. Default 0.
shader { vert: string, frag: string } optional - Optional SPIR-V shader override.

SpriteFrame

Individual frame within a sprite atlas.

size { x, y } - Intended on-screen size. The renderable scales the aabb rectangle to this size.
origin { x, y } - Frame metadata origin (pivot data from the atlas).
aabb { min: { x, y }, max: { x, y } } - Sub-rectangle within the atlas texture (in pixels).
colour [r, g, b, a] optional - Per-frame tint multiplier.

Notes #

size is the intended on-screen size of the frame. The renderable scales the aabb rectangle to this size.
frames[].origin is frame metadata for the sprite frame.
Element-level pivot is renderable.origin in UI.createElement (or UI.setOrigin at runtime).
Use renderable.origin for per-element transform intent; use frames[].origin when the pivot is part of atlas frame data.
aabb selects the sub-rectangle within the atlas texture (in pixels).
Optional colour multiplies the sprite tint; you can also animate colour via the animation system.

Top-level element options #

Pass these alongside renderable in UI.createElement (see also UI/Renderable: Shared properties):

UI.createElement(win, {
  renderable: {
    type: 'sprite',
    origin?: { x, y },
    position?: { x, y },
    scale?: { x, y },
    rotation?: number
  },
  contentAlign?: { x?: 'start'|'center'|'end', y?: 'start'|'center'|'end' }
})

Runtime control #

UI.setSpriteFrame

Switches to the given frame and re-prepares geometry/UVs.

UI.setSpriteFrame(windowId, id, frameIndex): boolean

You can also use the generic resource helpers: UI.setTexture, UI.clearTexture, UI.setShader, UI.clearShader.

Example: simple animation #

Defines three atlas frames and cycles through them with a timer to produce a looping sprite animation. This is the simplest approach for animated icons or small character sprites where you want direct frame control rather than the keyframe animation system.

import * as UI from 'Helix/UserInterface';

const frames = [
  { size: { x: 32, y: 32 }, origin: { x: 16, y: 16 }, aabb: { min:{x:0,y:0}, max:{x:32,y:32} } },
  { size: { x: 32, y: 32 }, origin: { x: 16, y: 16 }, aabb: { min:{x:32,y:0}, max:{x:64,y:32} } },
  { size: { x: 32, y: 32 }, origin: { x: 16, y: 16 }, aabb: { min:{x:64,y:0}, max:{x:96,y:32} } }
];

const spr = await UI.createElement(win, {
  renderable: {
    type: 'sprite',
    texture: '/rom/sprites/atlas.png',
    frames,
    frame: 0,
    position: { x: 100, y: 100 },
    origin: { x: 16, y: 16 }
  }
});
await UI.attachRoot(win, spr);

let i = 0;
setInterval(async () => {
  i = (i + 1) % frames.length;
  await UI.setSpriteFrame(win, spr, i);
}, 120);

<- UI/Renderable: Panel UI/Renderable: Particles ->