Sprite functions

Create, configure, animate, and remove Lua sprites from your mod scripts.

Lua sprites are custom display objects your script creates and manages independently of the engine’s built-in characters and notes. You create a sprite with makeLuaSprite, configure it, then add it to the scene with addLuaSprite.

function onCreate()
  makeLuaSprite("myBg", "backgrounds/city", 0, 0)
  setObjectCamera("myBg", "camGame")
  addLuaSprite("myBg", false)
end

---

Creating sprites

makeLuaSprite

Creates a new static image sprite and registers it by tag.

tag · string · required

A unique string identifier for this sprite. Used to reference it in all other functions.

imagePath · string

Image name relative to the images/ directory, without extension. Pass an empty string or nil to create a 1×1 white graphic instead.

x · number · default: "0"

Initial X position.

y · number · default: "0"

Initial Y position.

makeLuaSprite("overlay", "ui/vignette", 0, 0)

The sprite is not visible until you call addLuaSprite.

makeAnimatedLuaSprite

Creates an animated sprite backed by a Sparrow XML atlas.

tag · string · required

Unique tag for this sprite.

imagePath · string · required

Atlas image name relative to images/.

x · number · default: "0"

Initial X position.

y · number · default: "0"

Initial Y position.

spriteType · string

Reserved for future use. Pass nil or omit.

makeAnimatedLuaSprite("explosion", "effects/boom", 400, 300)
addAnimationByPrefix("explosion", "play", "boom", 24, false)
addLuaSprite("explosion", true)
playAnim("explosion", "play", true)

makeGraphic

Fills an existing sprite with a solid color rectangle. Call this after makeLuaSprite (with an empty image path) to set the size and color.

tag · string · required

Tag of an existing sprite.

width · number · required

Width of the rectangle in pixels.

height · number · required

Height of the rectangle in pixels.

color · string · default: "FFFFFF"

Hex color string (e.g. "FF0000" for red, "000000" for black).

makeLuaSprite("blackBars", "", 0, 0)
makeGraphic("blackBars", 1280, 120, "000000")
addLuaSprite("blackBars", true)

---

Adding and removing sprites

addLuaSprite

Adds a previously created sprite to the scene so it renders.

tag · string · required

Tag of the sprite to add.

isFront · boolean · default: "false"

If true, draws the sprite in front of characters. If false, draws it behind characters.

addLuaSprite("myBg", false)    -- behind characters
addLuaSprite("myOverlay", true) -- in front of characters

removeLuaSprite

Removes a sprite from the scene and hides it.

tag · string · required

Tag of the sprite to remove.

destroy · boolean

Reserved. The sprite data is retained in case you want to re-add it later.

removeLuaSprite("temporaryEffect")

luaSpriteExists

Returns true if a sprite with the given tag has been created.

tag · string · required

Tag to check.

if luaSpriteExists("mySprite") then
  setObjectAlpha("mySprite", 0.5)
end

---

Positioning and display

setObjectCamera

Assigns a sprite to a camera layer. Sprites on camGame scroll with the game world; sprites on camHUD are fixed to the screen.

tag · string · required

Sprite tag.

camera · string · default: "camGame"

Camera name: "camGame", "camHUD", or "camOther". Case-insensitive; "hud" maps to "camHUD".

setObjectCamera("scorePopup", "camHUD")

To set alpha or visibility on a sprite, use setProperty: setProperty("mySprite.alpha", 0.5) or setProperty("mySprite.visible", false). There are no separate setObjectAlpha / setObjectVisible functions.

setObjectOrder

Sets the draw order (z-index) of a sprite relative to other Lua sprites.

tag · string · required

Sprite tag.

order · number · required

Draw order. Lower values render first (behind higher values).

setObjectOrder("foreground", 10)
setObjectOrder("midground", 5)

screenCenter

Centers a sprite on the screen along the specified axis.

tag · string · required

Sprite tag.

axis · string · default: "xy"

Which axes to center: "x", "y", or "xy" (both).

makeLuaSprite("banner", "ui/banner", 0, 0)
screenCenter("banner", "x")
addLuaSprite("banner", true)

setScrollFactor

Controls how much a sprite moves with the camera (parallax effect).

tag · string · required

Sprite tag.

x · number · required

Horizontal scroll multiplier. 0 = fixed to camera, 1 = moves with world.

y · number · required

Vertical scroll multiplier.

-- Distant background: barely scrolls
setScrollFactor("skyBg", 0.1, 0.1)
-- HUD element: doesn't scroll at all
setScrollFactor("hudOverlay", 0, 0)

---

Scaling

scaleObject

Sets the scale multiplier of a sprite directly.

tag · string · required

Sprite tag.

x · number · required

Horizontal scale. 1.0 = original size.

y · number · required

Vertical scale. 1.0 = original size.

scaleObject("bigSprite", 2.0, 2.0)

setGraphicSize

Scales a sprite to an explicit pixel size. If one dimension is 0, the other is derived from the aspect ratio automatically.

tag · string · required

Sprite tag.

width · number

Target width in pixels. Pass 0 to derive from height.

height · number

Target height in pixels. Pass 0 to derive from width.

-- Scale to exactly 400px wide, preserve aspect ratio
setGraphicSize("logo", 400, 0)

-- Scale to 200×100 (may distort)
setGraphicSize("bar", 200, 100)

updateHitbox

Recalculates the sprite’s collision box after scaling. Call this after scaleObject or setGraphicSize if you need accurate width/height reads via getProperty.

tag · string · required

Sprite tag.

setGraphicSize("mySprite", 300, 0)
updateHitbox("mySprite")
local w = getProperty("mySprite.width") -- now accurate

---

Animations

addAnimationByPrefix

Registers a named animation using a Sparrow atlas prefix.

tag · string · required

Tag of an animated sprite.

name · string · required

Name to assign to this animation (used in playAnim).

prefix · string · required

The SubTexture name prefix from the atlas XML (without frame numbers).

fps · number · default: "24"

Frames per second.

loop · boolean · default: "true"

Whether the animation loops.

makeAnimatedLuaSprite("fire", "effects/fire", 600, 400)
addAnimationByPrefix("fire", "burn", "fire loop", 24, true)
addAnimationByPrefix("fire", "ignite", "fire start", 18, false)
addLuaSprite("fire", false)
playAnim("fire", "ignite", true)

addAnimationByIndices

Registers an animation using specific frame indices from the atlas instead of the full prefix sequence.

tag · string · required

Sprite tag.

name · string · required

Animation name.

prefix · string · required

Atlas prefix.

indices · table · required

Lua table of 1-based frame indices to include (e.g. {0, 1, 2, 5}).

fps · number · default: "24"

Frames per second.

loop · boolean · default: "true"

Whether the animation loops.

-- Use only the first 3 frames of the "blink" atlas sequence
addAnimationByIndices("character", "blink", "char blink", {0, 1, 2}, 12, false)

addOffset

Sets an offset that is applied when a specific animation plays. Useful for aligning sprites whose atlas frames have different anchor points.

tag · string · required

Sprite tag.

name · string · required

Animation name to attach this offset to.

x · number · default: "0"

Horizontal offset in pixels.

y · number · default: "0"

Vertical offset in pixels.

addOffset("myChar", "idle", -10, 5)
addOffset("myChar", "singLEFT", 30, -20)

playAnim

Plays a named animation on a sprite.

tag · string · required

Sprite tag.

name · string · required

Animation name (must be registered with addAnimationByPrefix or similar).

forced · boolean · default: "false"

If true, restarts the animation even if it is already playing.

reversed · boolean · default: "false"

Reserved for future use.

frame · number

Reserved for future use.

playAnim("explosion", "burst", true)

objectPlayAnimation

Alias for playAnim. Accepts (tag, name, forced) — no reversed or frame parameters.

objectPlayAnimation("explosion", "burst", true)

characterPlayAnim

Queues an animation to play on a built-in character (boyfriend, dad, or gf) rather than a Lua sprite.

charType · string · required

Character to target: "boyfriend", "dad", or "gf".

anim · string · required

Animation name to play.

forced · boolean · default: "false"

If true, restarts the animation even if already playing.

characterPlayAnim("boyfriend", "hey", false)

---

Other sprite utilities

addAnimation

Alias for addAnimationByPrefix. Accepts the same parameters: (tag, name, prefix, fps, loop).

addAnimation("fire", "burn", "fire loop", 24, true)

addProperty

Declares a custom property on a sprite (stored as a custom variable). Only sets the value if the property has not already been defined — useful for optional mod parameters.

name · string · required

Property name.

defaultValue · any · required

Value to set if the property doesn’t already exist.

addProperty("myFlag", false)
addProperty("damageMultiplier", 1.0)