• Parameters:
  • type = 'skim'
  • <card layer> TABLE Optional:
    • include SEQUENCE of COORDs/RECTs
    • exclude SEQUENCE of COORDs/RECTs Optional
    • timing TABLE of INTEGERs Optional
    • is_periodic BOOLEAN Optional default = false
    • direction SEQUENCE is {STRING, STRING, STRING} Optional default = {"r", "f", "f"}

{
  pos = {
    include     = {},
    exclude     = {},
    timing      = {},
    is_periodic = false,
    direction   = {"r", "f", "f"}
  },
}

The "Skim" macro generates frame sequences by "skimming" through the atlas row-wise or column-wise, with options to explicitly include and exclude specific areas on the atlas. Timings can also be specified.

A COORD is a TABLE with keys x and y. These coordinates correspond to points/sprites on an atlas, hence they are 0-indexed.

A RECT is an extension of COORDs; it is a TABLE with keys x1, x2, y1, and y2, which correspond to the point/sprite corners of a rectangle on an atlas. RECTs are automatically evaluated by the Skim macro, so the only thing that needs to be inputted in include and exclude is a TABLE, not an Object.

A RECT a shorthand for a list of COORDs. For example, the RECT {x1=2, x2=3, y1=4, y2=5} is equivalent to the sequence of COORDs {x=2,y=4}, {x=3, y=4}, {x=2, y=5}, {x=3, y=5}.

Below is an example of the COORD {x=0,y=1} and the RECT {x1=2,x2=3,y1=1,y2=2}.

The direction SEQUENCE contains three STRINGs:

• The first corresponds to the group type. It accepts the values row or col, and throws an error for any other value. This determines whether the macro skims through the active area (see next section) row-wise or column-wise.
• The second corresponds to the group iteration direction. It accepts the values forward or backward, and throws an error for any other value. This determines the order in which rows/columns are iterated through.
• The third corresponds to the group sub-iteration direction. It accepts the values forward or backward, and throws an error for any other value. This determines the order in which the sprites in each row/columns are iterated through.

The values row, col, forward, and backward can be shorthanded to use the first letter of each string (i.e. r, c, f, b).

The active area refers to the collection of sprites in the atlas that contribute to the animation of a layer. Smaller areas can be added to the total active area by defining COORDs and RECTs with include={}, and removed from the total active area by defining COORDs and RECTs with exclude={}.

Consider the following visualization. Here,

• A has include={{x1=0,x2=3,y1=0,y2=2}}, exclude={{x=0,y=0},{x1=1,x2=3,y1=2,y2=2}}.
• B has include={{x1=1,x2=3,y1=0,y2=1},{x=0,y=2}}, exclude={{x=2,y=0},{x=3,y=1}}.

SEQ then describes how these active areas are skimmed through (assuming direction={"r","f","f"}).

timing is a TABLE whose integer values correspond to the parameter t in the frame of the same index. Each value in timing corresponds to frames in the final generated sequence (i.e. after skimming through the active area). timing can either be:

• An INTEGER SEQUENCE ({1,2,3,4,5,...})
• An INTEGER non-SEQUENCE ({[1]=5,[8]=2}), in which case nils default to 1. (Remember, Lua is 1-indexed!)

If the length of timing is not equal to the number of frames, all frames after the highest index in timing will default to t=1.

If is_periodic is true, rather than the above being the case, timings will repeat after the highest index in timimg.

Hint: To slow the entire animation by some factor, a shorthand are the parameters timing={n}, is_periodic=true, where n is the factor to slow down by. This effectively sets t=n for all frames automatically.

All following examples assume the following frame sequence:

{
  { x=1, y=1 },
  { x=2, y=1 },
  { x=3, y=1 },
  { x=1, y=2 },
  { x=2, y=2 },
  { x=3, y=2 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=2 },
  { x=3, y=1, t=3 },
  { x=1, y=2, t=4 },
  { x=2, y=2, t=5 },
  { x=3, y=2, t=6 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=2 },
  { x=3, y=1, t=3 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=1 },
  { x=3, y=2, t=1 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=2 },
  { x=3, y=1, t=3 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=2 },
  { x=3, y=2, t=3 },
}

{
  { x=1, y=1, t=4 },
  { x=2, y=1, t=2 },
  { x=3, y=1, t=1 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=1 },
  { x=3, y=2, t=1 },
}

{
  { x=1, y=1, t=4 },
  { x=2, y=1, t=2 },
  { x=3, y=1, t=4 },
  { x=1, y=2, t=2 },
  { x=2, y=2, t=4 },
  { x=3, y=2, t=2 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=1 },
  { x=3, y=1, t=5 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=1 },
  { x=3, y=2, t=1 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=1 },
  { x=3, y=1, t=5 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=1 },
  { x=3, y=2, t=5 },
}

{
  { x=1, y=1, t=1 },
  { x=2, y=1, t=1 },
  { x=3, y=1, t=1 },
  { x=1, y=2, t=1 },
  { x=2, y=2, t=1 },
  { x=3, y=2, t=1 },
}