Sprites

Tecs provides a complete sprite system with animated sprites from Aseprite, per-frame collision boxes, animation events, and material maps for advanced lighting. Sprites are rendered using GPU instancing for maximum performance.

Quick Start

local assets = require("tecs2d.assets")
local manager = world.resources[assets]

-- Load sprite sheet (async, returns handle, caches asset)
local handle = manager:loadSpriteSheet("player.png")

-- Create sprite from loaded sheet
world:spawn(
    tecs.builtins.Transform(100, 100),
    gfx.Sprite.fromSheet(handle.value, "walk")
)

Creating Sprites

From Asset Manager (Recommended)

Use loadSpriteSheet for async loading with automatic caching.

local assets = require("tecs2d.assets")
local manager = world.resources[assets]

-- Load sprite sheet (async, returns handle)
local handle = manager:loadSpriteSheet("player.png")

-- Spawn a Sprite and pass in option configuration
world:spawn(
    tecs.builtins.Transform(200, 100),
    gfx.Sprite.fromSheet(handle.value, "attack", {
        speed = 1.5,         -- 1.5x playback speed
        centered = true,     -- Center on transform (default)
        pivotSlice = "feet", -- Use "feet" slice for pivot
        startTime = 0        -- Animation start time
    })
)

For static images without animation, use loadStaticSheet:

local bgHandle = manager:loadStaticSheet("background.png")
world:spawn(
    tecs.builtins.Transform(0, 0),
    gfx.Sprite.fromSheet(bgHandle.value)
)

Convenience Shorthand (Sync)

fromAseprite combines loading and sprite creation in one call. Useful for prototyping, but blocks the main thread:

-- Loads sheet synchronously and creates sprite
gfx.Sprite.fromAseprite("player.png", "walk")

-- With options
gfx.Sprite.fromAseprite("player.png", "attack", {
    speed = 1.5,
    pivotSlice = "feet"
})

From SpriteSheet (Sync)

For loading a sheet once and creating multiple sprites:

-- Load sheet synchronously (blocks main thread)
local sheet = gfx.SpriteSheet.fromFile("enemies.png")

-- Create multiple sprites from the same sheet
local goblin = gfx.Sprite.fromSheet(sheet, "goblin_idle")
local orc = gfx.Sprite.fromSheet(sheet, "orc_idle")

From Texture (Single Frame)

For simple textures without animation:

local texture = love.graphics.newImage("bullet.png")
gfx.Sprite.fromTexture(texture)

Sprite Options

Option	Type	Default	Description
speed	number	1.0	Animation speed multiplier
centered	boolean	true	Center sprite on transform position
pivotSlice	string	nil	Name of Aseprite slice to use as pivot
startTime	number	0	Animation start time (for staggering)

Sprite Methods

local sprite = world:get(entityId, gfx.Sprite)

-- Animation control
sprite:setTag("run")           -- Change animation tag
sprite:playOnce("attack")      -- Play a tag once, then freeze on the last frame
sprite:pause()                 -- Pause at current frame
sprite:resume()                -- Resume from pause
sprite:pauseAtEnd()            -- Jump to last frame and pause
sprite:pauseAtStart()          -- Jump to first frame and pause
sprite:gotoFrame(3)            -- Jump to specific frame (0-indexed)

-- Query state
local tag = sprite:getTag()              -- Current tag name
local frame = sprite:getFrame()          -- Current frame (0-indexed within tag)
local absFrame = sprite:getAbsoluteFrame() -- Absolute frame (1-indexed in sheet)
local w, h = sprite:getDimensions()      -- Sprite dimensions
local px, py = sprite:getPivot()         -- Current pivot point
local cx, cy = sprite:getCenter()        -- Center point (0.5, 0.5)

Combining with Other Components

Sprites work with styling components:

Component	Description
Color	RGBA tint applied to the sprite
BlendMode	Controls pixel blending (add, multiply, etc.)
Unlit	Skip dynamic lighting (use for UI sprites)
Pivot	Custom origin point (overrides pivotSlice option)
Material	Per-entity GPU shader effects (dissolve, glow, etc.)

local sheet = manager:loadSpriteSheet("player.png").value

world:spawn(
    tecs.builtins.Transform(100, 100),
    gfx.Sprite.fromSheet(sheet, "idle"),
    gfx.Color(1, 0.8, 0.8, 1),           -- Tint
    gfx.Unlit,                           -- Skip lighting
    gfx.Pivot(0.5, 1.0)                  -- Custom pivot (overrides pivotSlice)
)

GPU Rendering Architecture

Sprites are rendered using a high-performance GPU pipeline that can handle millions of sprites efficiently.

Texture Buckets

Sprite textures are automatically grouped into size-bucketed texture arrays:

Bucket	Max Size	Layers per Array
Tiny	16×16	512
Small	64×64	256
Medium	256×256	128
Large	512×512	64
XL	1024×1024	32
XXL	2048×2048	16

This architecture enables:

• Single draw call per bucket - All sprites using textures in the same bucket are batched together
• Automatic allocation - Textures are assigned to buckets based on their dimensions
• GPU culling - Visibility culling runs entirely on the GPU via compute shaders

DirectSprite for Large Textures

Textures larger than 2048×2048 cannot use the bucket system. Use the DirectSprite component for these:

world:spawn(
    tecs.builtins.Transform(0, 0),
    gfx.Sprite.fromTexture(hugeBackgroundTexture),
    gfx.DirectSprite  -- Bypass bucket system, render directly
)

DirectSprite entities are rendered separately and don't benefit from instanced batching.

Documentation

Topic	Description
Sheets	Loading sprite sheets, Aseprite export settings, material maps
Animation	Tags, playback control, timing, directions
Slices	Pivot points, per-frame pivots
Collisions	Physics integration from slices
Events	ChangeTag events
Tiling	RepeatedSprite for tiling