Spritesheet Functions

Functions to display images on screen.

makeLuaSprite

makeLuaSprite(tag:String, ?image:String = null, ?x:Float = 0, ?y:Float = 0):Void

Creates a Lua Sprite with a specific image and store it as the name input in "tag".

tag - Lua Sprite nametag to save.
image (Optional) - Image to display, don't include the extension!
x (Optional) - Defaults to 0.
y (Optional) - Defaults to 0.

Examples:

makeLuaSprite('mySprite', 'funkay') - Create a Lua Sprite with tag "mySprite" displaying image assets/shared/images/funkay.png.
makeLuaSprite('mySprite', 'myStage/myImage') - Create a Lua Sprite with tag "mySprite" displaying image mods/My-Mod/images/myStage/myImage.png.

Note: You will still have to add the Lua Sprite to the scene with addLuaSprite or it won't be visible.

makeAnimatedLuaSprite

makeAnimatedLuaSprite(tag:String, ?image:String = null, ?x:Float = 0, ?y:Float = 0, ?spriteType:String = 'auto'):Void

Creates an animated Lua Sprite with a specific image and .XML/.JSON/.TXT, then store it as the name input in "tag".

tag - Lua Sprite nametag to save.
image (Optional) - Image to display, don't include the extension!
x (Optional) - Defaults to 0.
y (Optional) - Defaults to 0.
spriteType (Optional) - Forces a spritesheet type, can be "sparrow" (.XML), "packer" (.TXT) or "aseprite" (.JSON). Defaults to "auto".

Examples:

makeAnimatedLuaSprite('mySprite', 'logoBumpin') - Create a Lua Sprite with tag "mySprite" displaying assets/shared/images/logoBumpin, using its .PNG and .XML files.
makeAnimatedLuaSprite('mySprite', 'aseprite-test', 0, 0, 'aseprite') - Create a Lua Sprite with tag "mySprite" displaying mods/My-Mod/images/aseprite-test, using its .PNG and .JSON files.

Note: You will still have to add the Lua Sprite to the scene with addLuaSprite or it won't be visible.

Note 2: Follow these instructions to export properly from Aseprite.

makeGraphic

makeGraphic(tag:String, ?width:Int = 256, ?height:Int = 256, ?color:String = 'FFFFFF'):Void

Generates a solid color square as graphic for a Lua Sprite.

tag - Sprite variable name or Lua Sprite nametag.
width - Graphic width in pixels. Defaults to 256.
height - Graphic height in pixels. Defaults to 256.
color (Optional) - Color hexadecimal string or color name.

Examples:

makeGraphic('mySprite', 500, 500, 'FF0000') - Turns Lua Sprite with tag "mySprite" into a 500x500 red square.
makeGraphic('mySprite', 1000, 200, 'green') - Turns Lua Sprite with tag "mySprite" into a 1000x200 green square.

loadGraphic

loadGraphic(tag:String, image:String = null, ?gridX:Int = 0, ?gridY:Int = 0):Void

Loads an image to a Lua Sprite, this image can be divided into frames in a consistently sized grid that doesn't require a .XML/.JSON/.TXT, which can be used as animation through "addAnimation".

tag - Sprite variable name or Lua Sprite nametag.
image - Image to display, don't include the extension!
gridX (Optional) - Defaults to 0.
gridY (Optional) - Defaults to 0.

Examples:

loadGraphic('mySprite', 'funkay') - Sets graphic of the Lua Sprite named "mySprite" to assets/shared/images/funkay.png.
loadGraphic('mySprite', 'icons/icon-bf', 150, 150) - Loads BF's Health Icon sprite on a Lua Sprite as a 150x150 grid.

loadFrames

loadFrames(tag:String, image:String, ?spriteType:String = 'auto'):Void

Loads a specific image and .XML/.JSON/.TXT to a Lua Sprite.

tag - Sprite variable name or Lua Sprite nametag.
image - Image to display, don't include the extension!
spriteType (Optional) - Forces a spritesheet type, can be "sparrow" (.XML), "packer" (.TXT) or "aseprite" (.JSON). Defaults to "auto".

Examples:

loadFrames('mySprite', 'logoBumpin') - Loads assets/shared/images/logoBumpin to the Lua Sprite with tag "mySprite", using its .PNG and .XML files.
loadFrames('mySprite', 'aseprite-test', 'aseprite') - Loads mods/My-Mod/images/aseprite-test, using its .PNG and .JSON files.

Note: Follow these instructions to export properly from Aseprite.

addAnimationByPrefix

addAnimationByPrefix(tag:String, name:String, prefix:String, ?framerate:Float = 24, ?loop:Bool = true):Bool

Adds an animation from a symbol.
Returns true if the operation was successful.

tag - Sprite variable name or Lua Sprite nametag.
name - Animation name.
prefix - Animation name in Adobe Animate/Aseprite.
framerate (Optional) - Animation FPS.
loop (Optional) - Should the animation loop?

Examples:

addAnimationByPrefix('mySprite', 'idle', 'Test Anim Idle') - Adds an animation named "idle", symbol is named "Test Anim Idle" on Animate, running at 24 FPS and loop disabled.
addAnimationByPrefix('mySprite', 'spin', 'Test Spin', 30, true) - Adds an animation named "spin", symbol is named "Test Spin" on Animate, running at 30 FPS and loop enabled.

addAnimationByIndices

addAnimationByIndices(tag:String, name:String, prefix:String, indices:Dynamic = null, ?framerate:Float = 24, ?loop:Bool = false):Bool

Adds an animation from a symbol, playing only the specified frames.
Returns true if the operation was successful.

tag - Sprite variable name or Lua Sprite nametag.
name - Animation name.
prefix - Animation name in Adobe Animate/Aseprite.
indices - Animation frames, can be formatted either as a string separated by commas or as a table.
framerate (Optional) - Animation FPS.
loop (Optional) - Should the animation loop?

Examples:

addAnimationByIndices('mySprite', 'idle', 'Test Anim Idle', '0, 1, 2, 3, 4, 5, 6, 7') - Adds "idle" using string indices.
addAnimationByIndices('mySprite', 'idle', 'Test Anim Idle', {0, 1, 2, 3, 4, 5, 6, 7}) - Adds "idle" using table indices.

addAnimation

addAnimation(tag:String, name:String, frames:Dynamic = null, ?framerate:Float = 24, ?loop:Bool = true):Bool

Adds an animation from a grid done with "loadGraphic", playing only the specified frames.
Returns true if the operation was successful.

tag - Sprite variable name or Lua Sprite nametag.
name - Animation name.
frames - Animation frames, can be formatted either as a string separated by commas or as a table.
framerate (Optional) - Animation FPS.
loop (Optional) - Should the animation loop?

Examples:

addAnimation('mySprite', 'idle', '0, 1, 2') - Adds "idle" using string indices.
addAnimation('mySprite', 'idle', {0, 1, 2}) - Adds "idle" using table indices.

addOffset

addOffset(tag:String, name:String, x:Float, y:Float):Bool

Adds an offset for the animation, offsets change automatically when you use "playAnim".
Returns true if the operation was successful.

tag - Sprite variable name or Lua Sprite nametag.
name - Animation name.
x - Offset X.
y - Offset Y.

Examples:

addOffset('mySprite', 'idle', 50, 38) - Add offsets (X: 50, Y: 38) to "idle" animation.

playAnim

playAnim(tag:String, name:String, ?forced:Bool = false, ?reverse:Bool = false, ?startFrame:Int = 0):Bool

Plays animation on a Sprite and updates offsets set with "addOffset".
Returns true if the operation was successful.

tag - Sprite variable name or Lua Sprite nametag.
name - Animation name.
forced (Optional) - When false, playing the same animation again will only reset it if the animation is finished. Defaults to false.
reverse (Optional) - Animation plays backwards. Defaults to false.
startFrame (Optional) - Start animation at a specific frame. Defaults to 0.

Examples:

playAnim('mySprite', 'idle', true) - Forces "mySprite" to play the "idle" animation.

addLuaSprite

addLuaSprite(tag:String, ?inFront:Bool = false):Void

Adds the Lua Sprite to the scene.

tag - Lua Sprite nametag.
inFront (Optional) - If true, the instance is added at the top of everything in its camera, if false, it will be added behind all characters.

Examples:

addLuaSprite('mySprite', true) - Adds a Lua Sprite with the tag "mySprite" at the top of everything.

removeLuaSprite

removeLuaSprite(tag:String, ?destroy:Bool = true, ?group:String = null):Void

Removes a Lua Sprite from the scene.

tag - Lua Sprite nametag.
destroy (Optional) - If enabled, clears the sprite object from memory once removed, do not disable unless you know what you're doing.
group (Optional) - Group variable name to remove the sprite from.

Examples:

removeLuaSprite('mySprite') - Removes the Lua Sprite with the tag "mySprite".

luaSpriteExists

luaSpriteExists(tag:String):Bool

Returns if a Lua Sprite with a specific tag exists.

tag - Lua Sprite nametag.