From Moondust Wiki
Jump to navigation Jump to search

*No download available for this library yet.*

Note: This page is still under construction, in the meantime there is in-text documentation in the API itself.
animatX is a LunaLua library designed to help simplify scripting reusable animation behavior for custom bosses, NPCs, blocks, BGOs, etc.


This library is only included in SMBX2 Beta 4 (in the future); no download available as of yet.

Usage Overview

To load the animatX library, import it with API.load:

local animatx = API.load("animatx");

You can then use animatx.Set {table properties} to make an Animation Set (AnimSet) object and place sprites that use a given AnimSet with AnimSet:Instance {table properties}. These sprites, known as Animation Instance (AnimInst) objects, animate independently of one another but follow the behavior defined in their AnimSet.

local animatx = API.load("animatx")
local sheet_sonic = Graphics.loadImage("sonic.png")

local sequences_sonic  = {
                          [1] = "1,2,3,4,5,4,3,2",
                          [3] = "1,2,3,4, 5ls,6,7,8, 4le,3,2,1",
                          [4] = "1,2,3, 4ls, 5le,6,7",
                          [5] = "1p1, 2, 3p1, 2",
                          [6] = "1,2,3, 4ls,5,6,7"

local set1 = animatx.Set {sheet=sheet_sonic, states=6, frames=8, sequences=seqs_sonic}

local spr = set1:Instance {x=400,y=300, state=1, scale=2, yAlign=animatx.ALIGN.BOTTOM, sceneCoords=true}

Sprite Sheet Format

Think of an animatX sprite sheets like multiple NPC or Block sheets combined – each column represents a different animation and each row corresponds to a frame index.
Sheets may have any number of rows and columns, and only unique frames need to be included.
Animatx example2.png Animatx example1.png


Sequences define the animation behavior of a given state. They consist of a series of "steps", each containing its own set of commands. When in a given state, an AnimInst object will follow the commands of the corresponding sequence step by step. Once it gets to the end of a sequence it will change to the next state in its queue (or restart the current sequence if none are queued).

Sequences should be defined as a table of strings passed in during an AnimSet's creation with the "sequences" argument. The basic structure of a sequence string is a series of command-number pairs separated by commas, like so:

"frame1, frame2, frame4, frame3, frame2 loopstart, frame9, random4 quake3, frame5 pause1, frame5 loopend, frame6"

Full sequences like that are rather awkward to read, however, so there are a number of ways to make them more compact:

  • If a command group begins with a number, that number is assumed to be the frame number.
  • Each command has a one- or two-character shorthand equivalent. For example, "random" can be shortened to "r" and "loopstart" can be written as "ls".
  • If no number is specified for a given command it will default to a pre-defined value.
  • Spaces between commands or steps are optional.

With the above tricks in mind, the following string is equivalent to the previous example:

"1,2,4,3, 2ls, 9, r4q3, 5p2, 5le,6"

Here are the various commands that can be used in sequence strings:

Full command Shorthand Default value Effect
frame f 1 Sets the AnimInst's current frame to the given row of the state's column.
pause p 1 Pauses the AnimInst, preventing it from continuing the sequence for the given number of steps
random r 1 Sets the AnimInst's current frame to a random row of the given state's column
quake q 30 Causes the AnimInst to shake for the given number of frames (similar to the Mother Brain damage shaking)
loopstart ls N/A Marks the beginning of the sequence's loop.
If this command is not used, the AnimSet will always loop back to the first step of the sequence.
loopend le N/A Marks the end of the sequence's loop.
If the AnimSet reaches this step when no other states are queued, it will ignore all of the other commands and
jump to the first step of the sequence's loop. Otherwise, this command has no effect.
if this command is not used, the AnimObject will restart or move on after completing the last step.