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 withDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/Quiet-Wolfe/Rustic-Engine/llms.txt
Use this file to discover all available pages before exploring further.
makeLuaSprite, configure it, then add it to the scene with addLuaSprite.
Creating sprites
makeLuaSprite
Creates a new static image sprite and registers it by tag.
A unique string identifier for this sprite. Used to reference it in all other functions.
Image name relative to the
images/ directory, without extension. Pass an empty string or nil to create a 1×1 white graphic instead.Initial X position.
Initial Y position.
addLuaSprite.
makeAnimatedLuaSprite
Creates an animated sprite backed by a Sparrow XML atlas.
Unique tag for this sprite.
Atlas image name relative to
images/.Initial X position.
Initial Y position.
Reserved for future use. Pass
nil or omit.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 of an existing sprite.
Width of the rectangle in pixels.
Height of the rectangle in pixels.
Hex color string (e.g.
"FF0000" for red, "000000" for black).Adding and removing sprites
addLuaSprite
Adds a previously created sprite to the scene so it renders.
Tag of the sprite to add.
If
true, draws the sprite in front of characters. If false, draws it behind characters.removeLuaSprite
Removes a sprite from the scene and hides it.
Tag of the sprite to remove.
Reserved. The sprite data is retained in case you want to re-add it later.
luaSpriteExists
Returns true if a sprite with the given tag has been created.
Tag to check.
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.
Sprite tag.
Camera name:
"camGame", "camHUD", or "camOther". Case-insensitive; "hud" maps to "camHUD".setObjectOrder
Sets the draw order (z-index) of a sprite relative to other Lua sprites.
Sprite tag.
Draw order. Lower values render first (behind higher values).
screenCenter
Centers a sprite on the screen along the specified axis.
Sprite tag.
Which axes to center:
"x", "y", or "xy" (both).setScrollFactor
Controls how much a sprite moves with the camera (parallax effect).
Sprite tag.
Horizontal scroll multiplier.
0 = fixed to camera, 1 = moves with world.Vertical scroll multiplier.
Scaling
scaleObject
Sets the scale multiplier of a sprite directly.
Sprite tag.
Horizontal scale.
1.0 = original size.Vertical scale.
1.0 = original size.setGraphicSize
Scales a sprite to an explicit pixel size. If one dimension is 0, the other is derived from the aspect ratio automatically.
Sprite tag.
Target width in pixels. Pass
0 to derive from height.Target height in pixels. Pass
0 to derive from width.updateHitbox
Recalculates the sprite’s collision box after scaling. Call this after scaleObject or setGraphicSize if you need accurate width/height reads via getProperty.
Sprite tag.
Animations
addAnimationByPrefix
Registers a named animation using a Sparrow atlas prefix.
Tag of an animated sprite.
Name to assign to this animation (used in
playAnim).The SubTexture name prefix from the atlas XML (without frame numbers).
Frames per second.
Whether the animation loops.
addAnimationByIndices
Registers an animation using specific frame indices from the atlas instead of the full prefix sequence.
Sprite tag.
Animation name.
Atlas prefix.
Lua table of 1-based frame indices to include (e.g.
{0, 1, 2, 5}).Frames per second.
Whether the animation loops.
addOffset
Sets an offset that is applied when a specific animation plays. Useful for aligning sprites whose atlas frames have different anchor points.
Sprite tag.
Animation name to attach this offset to.
Horizontal offset in pixels.
Vertical offset in pixels.
playAnim
Plays a named animation on a sprite.
Sprite tag.
Animation name (must be registered with
addAnimationByPrefix or similar).If
true, restarts the animation even if it is already playing.Reserved for future use.
Reserved for future use.
objectPlayAnimation
Alias for playAnim. Accepts (tag, name, forced) — no reversed or frame parameters.
characterPlayAnim
Queues an animation to play on a built-in character (boyfriend, dad, or gf) rather than a Lua sprite.
Character to target:
"boyfriend", "dad", or "gf".Animation name to play.
If
true, restarts the animation even if already playing.Other sprite utilities
addAnimation
Alias for addAnimationByPrefix. Accepts the same parameters: (tag, name, prefix, fps, loop).
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.
Property name.
Value to set if the property doesn’t already exist.