Skip to content

SpriteBatch

The SpriteBatch class manages a collection of batched sprites (either grid tiles or custom quads) sharing a single image texture.

It supports efficient reuse, z-depth sorting, and batch-level global transformations (position, scale, rotation, and color tinting).

Synopsis

Constructors

Instance Methods

Tile/Quad Methods

Batch Management Methods

Global Transformation Methods

Render Methods

Constructors

SpriteBatch(image, max_sprites[, tile_w, tile_h])

Creates a new SpriteBatch linked to a specific image atlas.

Parameters:

Parameter Type Required Description
image Image Yes The source Image object to use as a texture atlas.
max_sprites int Yes The initial maximum capacity of the batch (must be > 0).
tile_w int No Width of an individual grid tile in pixels. Required if using add_tile/set_tile.
tile_h int No Height of an individual grid tile in pixels. Required if using add_tile/set_tile.

Tile/Quad Methods

sprite_batch.add_tile(tile_id, x, y[, z, r, g, b, a, scale_x, scale_y, angle])

Adds a new grid tile sprite to the batch and returns its assigned index ID.

Source rectangles are calculated automatically based on the tile_w and tile_h provided in the constructor.

Parameters:

Parameter Type Required Description
tile_id int Yes The index of the tile in the grid (left-to-right, top-to-bottom).
x, y float Yes The target X and Y coordinates.
z float No Z-depth for automatic sorting. Defaults to 0.0.
r, g, b, a int No Color tint channels (0-255). Defaults to 255 (opaque white).
scale_x float No Horizontal scale factor. Defaults to 1.0.
scale_y float No Vertical scale factor. Defaults to scale_x.
angle float No Rotation angle in degrees. Defaults to 0.0.
  • Returns: int: The unique index allocated for this sprite in the batch.

sprite_batch.set_tile(index, tile_id, x, y[, z, r, g, b, a, scale_x, scale_y, angle])

Updates an existing tile slot or revives a previously removed index using grid calculations.

Parameters:

Parameter Type Required Description
index int Yes The active slot index to update.
others Mixed (See add_tile) The same parameters as add_tile.

sprite_batch.add_quad(src_x, src_y, src_w, src_h, x, y[, z, r, g, b, a, scale_x, scale_y, angle])

Adds a custom quad sprite to the batch using an explicit source rectangle. Useful for packed texture atlases (like TexturePacker outputs) that do not use a strict grid.

Parameters:

Parameter Type Required Description
src_x, src_y int Yes Source rectangle X and Y coordinates on the image atlas.
src_w, src_h int Yes Source rectangle width and height.
x, y float Yes The target X and Y coordinates.
z float No Z-depth for automatic sorting. Defaults to 0.0.
r, g, b, a int No Color tint channels (0-255). Defaults to 255 (opaque white).
scale_x float No Horizontal scale factor. Defaults to 1.0.
scale_y float No Vertical scale factor. Defaults to scale_x.
angle float No Rotation angle in degrees. Defaults to 0.0.
  • Returns: int: The unique index allocated for this sprite in the batch.

sprite_batch.set_quad(index, src_x, src_y, src_w, src_h, x, y[, z, r, g, b, a, scale_x, scale_y, angle])

Updates an existing quad slot or revives a previously removed index using explicit source coordinates.

Parameters:

Parameter Type Required Description
index int Yes The active slot index to update.
others Mixed (See add_quad) The same parameters as add_quad.

Batch Management Methods

sprite_batch.remove(index)

Deactivates a sprite slot by index, hiding it from rendering and recycling its ID.

Parameters:

Parameter Type Required Description
index int Yes The target index to remove.

sprite_batch.clear()

Deactivates all active sprite slots and resets the active count.

sprite_batch.shrink()

Trims internal slice capacities down to match the highest active sprite index, freeing unused memory back to the OS.

Global Transformation Methods

Global transformations are applied uniformly across the entire batch at draw time. They stack mathematically with individual sprite properties.

sprite_batch.set_position(x, y)

Sets the global translation coordinates for the entire batch.

Parameters:

Parameter Type Required Description
x float Yes Global X offset.
y float Yes Global Y offset.

sprite_batch.set_scale(scale_x[, scale_y])

Sets the global scale multipliers.

Parameters:

Parameter Type Required Description
scale_x float Yes Global horizontal scale factor.
scale_y float No Global vertical scale factor. Defaults to scale_x.

sprite_batch.set_rotation(angle)

Sets the global rotation angle for the batch. Sprites will orbit around the batch's global origin point (which defaults to (0,0) but can be changed via set_origin).

Parameters:

Parameter Type Required Description
angle float Yes Global rotation angle in degrees.

sprite_batch.set_origin(origin_x, origin_y)

Sets the custom global origin/pivot coordinate for scaling and orbital rotation.

Parameters:

Parameter Type Required Description
origin_x float Yes Custom origin X coordinate.
origin_y float Yes Custom origin Y coordinate.

sprite_batch.set_color(r, g, b, a)

Sets a global RGBA color multiplier for the batch.

Parameters:

Parameter Type Required Description
r, g, b, a float Yes Color multipliers ranging from 0.0 to 1.0.

Render Methods

sprite_batch.draw()

Sorts active elements natively by z-depth and submits them to the render queue with global transformations applied.

Examples

// 1. Load an image atlas (e.g., a 16x16 tilemap sheet)
local atlas = Image("res://assets/tileset.png")

// 2. Create a SpriteBatch for up to 1000 sprites, configuring 16x16 grids
local batch = SpriteBatch(atlas, 1000, 16, 16)

// 3. Add tiles (tile_id, x, y, z, r, g, b, a, scale_x, scale_y, angle)
local playerIdx = batch.add_tile(4, 100, 100, 10.0, 255, 255, 255, 255, 1.0, 1.0, 0.0) // High Z
local shadowIdx = batch.add_tile(5, 100, 105, 0.0, 255, 255, 255, 128, 1.0, 1.0, 0.0)  // Low Z

// 4. Transform the entire batch (like a camera moving)
batch.set_position(50.0, 20.0)
batch.set_scale(2.0, 2.0)

// In your render loop:
function draw() {
    // 5. Update individual sprites dynamically
    batch.set_tile(playerIdx, 4, playerX, playerY, 10.0)

    // 6. Automatically z-sorts and draws all active elements
    batch.draw()
}