sprite
stableCreate and manipulate 2D sprite objects with position, rotation, scale, flip, opacity, z-order, anchor, and bounding-box collision; also parse sprite sheets into animation frames.
use plugin sprite::{Sprite.new, Sprite.get_position, Sprite.set_position, …} Plugin snippets can be edited in the Playground, but native capabilities are executed locally with the Zolo CLI.
Functions (28)
- Sprite.new Create a new sprite with given dimensions
- Sprite.get_position Get the sprite's current position
- Sprite.set_position Set the sprite's position
- Sprite.get_rotation Get the rotation in radians
- Sprite.set_rotation Set the rotation in radians
- Sprite.get_scale Get the x/y scale factors
- Sprite.set_scale Set the x/y scale factors
- Sprite.get_flip Get horizontal/vertical flip state
- Sprite.set_flip Set horizontal/vertical flip
- Sprite.is_visible Check whether the sprite is visible
- Sprite.set_visible Show or hide the sprite
- Sprite.get_z_order Get the draw order value
- Sprite.set_z_order Set the draw order value
- Sprite.get_anchor Get the anchor point
- Sprite.set_anchor Set the anchor point (0–1 range)
- Sprite.get_opacity Get the opacity (0.0–1.0)
- Sprite.set_opacity Set the opacity (0.0–1.0)
- Sprite.get_size Get the sprite's width and height
- Sprite.set_size Set the sprite's width and height
- Sprite.bounding_box Get the axis-aligned bounding box
- Sprite.contains_point Test if a point is inside the sprite
- Sprite.overlaps Test if two sprites overlap
- SpriteSheet.new Create a sprite sheet from texture dimensions
- SpriteSheet.get_frame Get pixel rect for a frame index
- SpriteSheet.frame_count Get the total number of frames
- SpriteSheet.get_animation_frames Get a range of animation frame rects
- SpriteSheet.columns Get the number of columns
- SpriteSheet.rows Get the number of rows
From import to result
- 01Import only what you use
- 02Copy the smallest example
- 03Run it with the Zolo CLI
Create a new sprite with given dimensions
Creates a new sprite handle with the given dimensions. Initial position is (0, 0), scale (1, 1), fully opaque and visible.
use plugin sprite::{Sprite}
let player = Sprite.new(64.0, 64.0)Get the sprite's current position
Returns the current position as {x, y}.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_position(100.0, 200.0)
let pos = s.get_position()
print("x={pos["x"]} y={pos["y"]}")Set the sprite's position
Sets the sprite's world position.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_position(150.0, 80.0)Get the rotation in radians
Returns the current rotation in radians.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_rotation(1.5707)
print(s.get_rotation())Set the rotation in radians
Sets the sprite's rotation in radians.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_rotation(3.14159)Get the x/y scale factors
Returns the current scale as {x, y}.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_scale(2.0, 2.0)
let sc = s.get_scale()
print("sx={sc["x"]} sy={sc["y"]}")Set the x/y scale factors
Sets the sprite's x and y scale factors. Values less than 1.0 shrink, greater than 1.0 enlarge.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_scale(1.5, 1.5)Get horizontal/vertical flip state
Returns the flip state as {x, y} booleans.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_flip(true, false)
let f = s.get_flip()
print("flip_x={f["x"]}")Set horizontal/vertical flip
Sets horizontal and/or vertical flip. Use flip_x = true to mirror the sprite along the Y axis.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_flip(true, false)Check whether the sprite is visible
Returns true if the sprite is currently visible.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
print(s.is_visible())Show or hide the sprite
Shows (true) or hides (false) the sprite.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_visible(false)Get the draw order value
Returns the sprite's z-order (draw layer) value.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_z_order(5)
print(s.get_z_order())Set the draw order value
Sets the z-order. Higher values render on top.
use plugin sprite::{Sprite}
let bg = Sprite.new(800.0, 600.0)
bg.set_z_order(0)
let player = Sprite.new(32.0, 32.0)
player.set_z_order(10)Get the anchor point
Returns the anchor point as {x, y} in the 0.0–1.0 range. The default anchor is (0, 0) — top-left.
use plugin sprite::{Sprite}
let s = Sprite.new(64.0, 64.0)
s.set_anchor(0.5, 0.5)
let a = s.get_anchor()
print("anchor={a["x"]},{a["y"]}")Set the anchor point (0–1 range)
Sets the anchor point. (0.5, 0.5) centres the sprite on its position; (1.0, 1.0) places the bottom-right at the position.
use plugin sprite::{Sprite}
let s = Sprite.new(64.0, 64.0)
s.set_anchor(0.5, 0.5)Get the opacity (0.0–1.0)
Returns the current opacity in the range 0.0 (fully transparent) to 1.0 (fully opaque).
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_opacity(0.5)
print(s.get_opacity())Set the opacity (0.0–1.0)
Sets the sprite's opacity. Values are clamped to [0.0, 1.0].
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_opacity(0.75)Get the sprite's width and height
Returns the sprite dimensions as {width, height}.
use plugin sprite::{Sprite}
let s = Sprite.new(64.0, 32.0)
let sz = s.get_size()
print("w={sz["width"]} h={sz["height"]}")Set the sprite's width and height
Changes the sprite's logical dimensions.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_size(64.0, 64.0)Get the axis-aligned bounding box
Returns the axis-aligned bounding box as {x, y, w, h}, taking anchor and scale into account.
use plugin sprite::{Sprite}
let s = Sprite.new(32.0, 32.0)
s.set_position(100.0, 100.0)
s.set_anchor(0.5, 0.5)
let bb = s.bounding_box()
print("box x={bb["x"]} y={bb["y"]} w={bb["w"]} h={bb["h"]}")Test if a point is inside the sprite
Returns true if the world point (px, py) falls inside the sprite's bounding box.
use plugin sprite::{Sprite}
let s = Sprite.new(64.0, 64.0)
s.set_position(0.0, 0.0)
print(s.contains_point(32.0, 32.0))Test if two sprites overlap
Returns true if the bounding boxes of this sprite and other overlap. Use for simple AABB collision detection.
use plugin sprite::{Sprite}
let a = Sprite.new(32.0, 32.0)
a.set_position(0.0, 0.0)
let b = Sprite.new(32.0, 32.0)
b.set_position(16.0, 0.0)
if a.overlaps(b) {
print("collision!")
}Create a sprite sheet from texture dimensions
Creates a sprite sheet handle by dividing the texture into frames of frame_width x frame_height pixels.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 64, 64, 64)Get pixel rect for a frame index
Returns the pixel rectangle {x, y, w, h} for the frame at zero-based index.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 64, 64, 64)
let frame = sheet.get_frame(2)
print("frame at x={frame["x"]} y={frame["y"]}")Get the total number of frames
Returns the total number of frames available in the sprite sheet.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 64, 64, 64)
print("frames: {sheet.frame_count()}")Get a range of animation frame rects
Returns a table of count frame rectangles starting from frame start. Frames past the end of the sheet are skipped.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 64, 64, 64)
let walk_frames = sheet.get_animation_frames(0, 4)
for i, frame in walk_frames {
print("frame {i}: x={frame["x"]}")
}Get the number of columns
Returns the number of frame columns in the sprite sheet.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 64, 64, 64)
print("columns: {sheet.columns()}")Get the number of rows
Returns the number of frame rows in the sprite sheet.
use plugin sprite::{SpriteSheet}
let sheet = SpriteSheet.new(256, 128, 64, 64)
print("rows: {sheet.rows()}")