Animator

Animator is a tool, which allows animations to be played from spritesheets or from a collection of images easily.

Properties

---

Tools

Tools are utility functions, which aid in defining animation frames. Tools are mainly used in conjuction with Animator:AddSpritesheet()

List of all available events

Name changes

In the upcoming updates, it is possible for the listed tools to change names. Currently the names of these functions do not make sense at all.

Name:	Description:
PopulateRow	Fills a table with x amount of ones(1)
PopulateColumn	Fills x amount of tables with y amount of ones(1)

Class properties

Name:	Description:
Framerate	The framerate of the animation
Frame	Current frame
MaxFrames	How many frames are there in the animation
CurrentAnimation	The current animation's name
Running	Is animation being played with :Play()
Objects	Array of attached objects

API

---

.new(objects)

Parameter: Objects {ImageLabel | ImageButton}

Constructs a new Animator class. If objects argument is present it will automatically attach those objects.

:AddSpritesheet(imageId, size, animations)

Parameter: imageId String | Number Parameter: size Vector2 Parameter: animations {[String]: {{Number}}}

Adds animations with the help of spritesheets.

Example

local Animator = require(Rethink.Animator)
local myAnimation = Animator.new()

myAnimation:AddSpritesheet(SPRITESHEET_ID, ANIMATION_CELL_SIZE, {
    ["run"] = {
        { 1, 1, 1, 1, 1 },
    },
})

A new animation can be created by adding a new key value paired table. The key of the table should be the name of the animation, and the value should be a set of ones(1) and zeros(0) to indicate, which represent each frame on your spritesheet.

Steps to create your animation:

1. Count how many squares are in a row and a column
2. In our animation table create as many tables as rows and inside them as many zeros(0) as columns
3. Replace the zeros(0) with ones(1) which are desired to be the part of the animation

Results:

myAnimation:AddSpritesheet(SPRITESHEET_ID, ANIMATION_CELL_SIZE, {
    ["rotating_squares"] = {
        { 1, 1, 1, 1, 1 },
        { 1, 0, 0, 0, 0 },
        { 0, 0, 0, 0, 0 },
        { 0, 0, 0, 0, 0 },
        { 0, 0, 0, 0, 0 },
    },
})

Tables containing no ones(1) are not required and can be left out. In case the animation is not connected and there is space between them:

1. Using r

   r is an offset value, which can be inserted into animation tables having gaps in them. When Animator reads and maps out the animations it will use the r's value to offset the frame.

   Normally this represents the 1st row but since there's an r key Animator will offset it by that amount. In our case this will represent the 3rd row, instead of the 1st row.

   myAnimation:AddSpritesheet(SPRITESHEET_ID, ANIMATION_CELL_SIZE, {
       ["rotating_squares"] = {
           { r = 3, 1, 1, 0, 0, 0 },
       },
   })
   

2. Filling out gaps

   Filling out the empty gaps with animation tables contaizing zeros(0) work as well. However, for larger spritesheets, using r is the recommended option.

   myAnimation:AddSpritesheet(SPRITESHEET_ID, ANIMATION_CELL_SIZE, {
       ["rotating_squares"] = {
           { 0, 0, 0, 0, 0 },
           { 0, 0, 0, 0, 0 },
           { 1, 1, 0, 0, 0 },
       },
   })
   

:AddCollection(collection)

Parameter: collection {[String]: {String | Number}}

Adds a collection of images as animations. The structure of the collection table matches the one used in Animator:AddSpritesheet() method. However, instead of tables containing a set of zeros(0) and ones(1) the images' ids are used.

Example

local Animator = require(Rethink.Animator)
local myAnimation = Animator.new()

myAnimation:AddCollection({
    ["example"] = {
        IMAGE_ID_1,
        IMAGE_ID_2,
        IMAGE_ID_3
    },
})

:Play()

Returns: Promise Promise

Plays the selected animation independant from framerate infinitely.

:Stop()

Haults the animation, which was started by Animator:Play()

:SetFramerate(framerate)

Parameter: framerate Number Default: framerate 60

Sets the framerate of the animations, default value is 60 FPS.

:NextFrame()

Advances to the next frame in the selected animation.

:PreviousFrame()

Advances to the previous frame in the selected animation.

:AttachObject(object)

Parameter: object ImageLabel | ImageButton

Attaches the provided object to Animator, which will display the current animation frame.

:DetachObject(object)

Parameter: object ImageLabel | ImageButton

Detaches the provided obhect from Animator and will no longer display the current animation frame.

:ChangeAnimation(animationName)

Parameter: animationName String

Changes the animation being played. If Animator cannot find the specified animation it will throw an error.

:ClearAnimationData()

Clears all the data associated with animations. This includes objects as well.

:GetCurrentAnimation()

Returns: AnimationData {Number}

Returns the current animation data that Animator uses.

:GetCurrentFrame()

Returns: Frame Number

Returns the current frame the animation is on.

:GetFramerate()

Returns: Framerate Number

Returns the framerate.

:GetMaxFrames()

Returns: MaxFrame Number

Returns the maximum frames in the animation.

:GetObjects()

Returns: Objects {ImageLabel | ImageButton}

Returns all of the attached objects.

:Destroy()

Destroys the current Animator class.