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 provided goes on top of the others, followed by the second, then the third, until the last layer is reached. The bottom layer goes under all other layers, but over the base layer. (In this case, top_layer goes over middle_layer, which goes over bottom_layer, which goes over the location provided by pos.)

Animating Layers

Just like the base layer, extra layers can be animated. This is largely the same, but has a couple differences.

When animating extra layers, you don't need to specify flipbook_pos_extra (unless specifying a layer's Atlas), as Flipbook changes it while animating.

If you're only animating one extra layer, the syntax is the same.

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

Ranges function the same as they did with the base layer.

When animating multiple layers, each animation needs to have a key associated with it, so Flipbook knows which layer it belongs to. Here's an example of a Joker with 3 extra layers being animated:

flipbook_anim_extra = {
  foo = { { xrange = { first = 0, last = 2 }, yrange = { first = 0, last = 2 }, t = 1 } },
  bar = { { x = 0, y = 3, t = 0.333 }, { x = 1, y = 3, t = 0.2 } },
  baz = { { x = 2, y = 3, t = 0.111 }, { x = 3, y = 3, t = 0.1 } }
}

In the example where the animation is given directly without a key, the key defaults to extra.

Like the flipbook_pos_extra, the top layer is the first in the table, and the bottom layer is the last (so here, foo renders over bar, which renders over baz).

Extra layer animations don't have to synchronise with the base layer or each other; layer animations run independently from each other.

Anima