Animatx.lua

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.

Installation
AnimatX will come packaged with SMBX 2.0 Beta 4.

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

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.

Sprite Sheet Format
Think of 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.

Sequences
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: 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"
 * 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.

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