Flipbook

Flipbook — Balatro Animation API

Introduction

Welcome to Flipbook! This API mod allows you to animate the Jokers, Consumables, Vouchers, etc. in your Balatro mods.

If you only need simple animation, then SMODS already has tools for that. This mod adds more in-depth animation features, such as individual frame delays, frame ranges and animation states.

Getting Started With Animation

Here is a simple animation for a Joker that changes between three sprites on 1 second intervals:

flipbook_anim = {

{ x = 0, y = 0, t = 1 },

{ x = 1, y = 0, t = 1 },

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

}

x and y work similarly to pos. t is how long the frame is shown for, in seconds.

This is put on the Joker's object definition, alongside its other variables like key and pos. You can also animate Centers from the vanilla game or from other mods by using SMODS' take_ownership function, or by other means of adding code to Centers.

Ranges

The above animation can be simplified using the xrange field:

flipbook_anim = {

{ xrange = { first = 0, last = 2 }, y = 0, t = 1 }

}

If your animation has lots of frames within a range of x locations, xrange is a shorthand that allows you to code that in 1 line. first is the location in the range that will be shown first; last will be shown last.

t is the time that each frame individually will be shown, so this animation will last a total of 1 + 1 + 1 = 3 seconds.

You can also use yrange:

flipbook_anim = {

{ xrange = { first = 0, last = 2 }, yrange = { first = 0, last = 2 }, t = 1 }

}

This works similarly to xrange, but operates on y values instead. As shown in the code above, these two fields can be used together to save a lot of lines of code.

Note that you cannot currently specify individual frame durations when using xrange or yrange; t applies to all frames within range.

When using xrange and yrange together, frames are displayed in reading order (left to right, top to bottom). Here's what the above code would look like without using xrange or yrange:

flipbook_anim = {

{ x = 0, y = 0, t = 1 },

{ x = 1, y = 0, t = 1 },

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

{ x = 0, y = 1, t = 1 },

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

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

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

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

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

}

If first is less than last, the range will be in ascending order. However, if first is greater than last, the range will be in descending order, which may be useful for reversing animations:

flipbook_anim = {

{ xrange = { first = 2, last = 0 }, yrange = { first = 2, last = 0 }, t = 1 }

}

This is equivalent to:

flipbook_anim = {

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

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

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

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

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

{ x = 0, y = 1, t = 1 },

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

{ x = 1, y = 0, t = 1 },

{ x = 0, y = 0, t = 1 },

}

Layers

The field flipbook_pos_extra allows you to specify multiple layers for your object. Below is an example of a Joker with two layers:

atlas = "example",

pos = { x = 0, y = 0 },

flipbook_pos_extra = { x = 1, y = 1, atlas = "foo" }

The location in pos is always the bottom layer; any flipbook_pos_extras are rendered on top of it.

Each extra layer can optionally use a different Atlas from the bottom layer — if no Atlas is provided, they default to the bottom layer's Atlas.

If an object with multiple layers has an edition, all layers are rendered with the edition automatically.

You can have more than two layers:

atlas = "example",

pos = { x = 0, y = 0 },

flipbook_pos_extra = {

top_layer = { x = 1, y = 1 }, -- Defaults to atlas "example"

middle_layer = { x = 2, y = 3, atlas = "bar" }, -- Uses atlas "bar"

bottom_layer = { x = 5, y = 8, atlas = "baz" }, -- Uses atlas "baz"

}

The above code specifies four layers. Each layer needs to have a key, but the keys can be whatever you want them to be (as long as they are valid in Lua).

In the example where the x, y and atlas are given directly without a key, the key defaults to extra.

The first layer pr