Skip to content

Home

Jump to bottom
Whitebrim edited this page Apr 30, 2024 · 19 revisions

AnimatedSprite is class inherited from the Sprite class, so it contains all sprite behaviour.
On top of that AnimatedSprite provides automatically drawing imagetables, animation finite state machine, json animation configuration.

Basics

To create animated sprite you need:

  1. If you haven't already, add this line playdate.graphics.sprite.update() to the playdate.update() function
  2. Create AnimatedSprite instance
  3. Add animation state
  4. Play the animation

See example_1A for the concrete example.

More detailed description

AnimatedSprite is an extension for Playdate's sprite class. It handles all animation stuff.
You don't need to know when and how to update the sprite's image - just configure states and play the animation.

To create an animated sprite, you need to call AnimatedSprite.new(imagetable, [states, [animate]]).
!! Imagetable can be send as path to the imagetable file or as an actual imagetable if you need to create several AnimatedSprites (not to load imagetable every time).

Imagetable is Playdate's structure that is created using playdate.graphics.imagetable.new. This can be used to import image tables in a variety of formats: GIF, sequential image table and matrix image table. Read Playdate Docs for more info.

If you want to configure the animation - first add states, then play the animation.
If you add more than 1 state, the first one you add will be used as default state and when you call :playAnimation() the animation will start from that state.

Adding states

Use :addState(name, [startFrame], [endFrame], [params], [animate]) to add animation states to the finite state machine (example_1A, example_1B, example_1C).
See this page for all available parameters.
The first added state will be used as default to play animation with.
If you want another state to be the default, you can type .asDefault() after adding this state (example_1B), or separately call :setDefaultState(stateName).

There's always the "default" state that contains default values for all states. If you don't add any states this default state will be used.
It will play animation from the first frame to the last and loop infinitely, changing frames on every update() call, with no scaling, no flipping.

Don't confuse .defaultState (:setDefaultState(name)) variable and .states.default table:

  • .defaultState is a string field that contains the state name of the state to play animation from at the first start or after animation reset (:stopAnimetion()).
  • .states.default table contains default values for all animation states. If you add a new animation and don't specify any parameter, its value is taken from the default table.

Controlling flow of the animation

  • To play the animation - call :playAnimation()
  • To pause the animation - call :pauseAnimation()
  • To resume the animation after pausing - call :resumeAnimation()
  • You can call :toggleAnimation() to toggle between play and pause.
  • If you need to reset your animation - call :stopAnimation(). This will reset all animation variables as if animation wasn't played before.
    Then you can call :playAnimation() to start the animation from the default state.

Hidden features

  • If you want to flip all states in your animated sprite (e.g., your 2D character needs to be flipped when it's walking left) you can chage your sprite's .globalFlip.
    This global flip value will be added on top of each state's local flip, so if local flip is "FlipX" and global flip is "FlipX" then sprite won't be flipped at all. (-1 * -1 = 1)
  • If you don't specify a parameter for any given state or set your state's config parameter to nil then it'll be taken from .states.default.
    If you change any of the values in .states.default, it will affect all states that didn't specify that parameter. This will work even during animations.

List of public functions that you will be using

AnimatedSprite.new(imagetable, [states], [animate]) / AnimatedSprite(imagetable, [states], [animate]) -- Create new animation sprite instance

:playAnimation() -- Play the animation
:pauseAnimation() -- Pause the animation
:resumeAnimation() -- Resume the animation after pausing
:toggleAnimation() -- Toggle between play and pause
:stopAnimation() -- Reset the animation

:addState(name, [startFrame], [endFrame], [params], [animate]) -- Add a new state to the finite state machine
.loadStates(path) -- Get the configuration table from the JSON file
:setStates(states, [animate], [defaultState]) -- Initialise the finite machine with the configuration table [states]
:getCurrentState() -- Get reference to the current state
:getLocalStates() -- Get the table of the finite machine states
:copyLocalStates() -- Get the copy of the state table to initialise other animated sprites
:changeState(name, [play]) -- Change current state in the finite state machine to the [name] state
:changeStateAndSelectFrame(name, frameIndex, [play]) -- Change current state and start from selected local frame (index from 1 to frames count)
:forceNextAnimation([instant], [state]) -- Used to change state to the next animation (from current state's nextAnimation param) or to the specified state now or in the end of the current animation loop.
:setDefaultState(name) -- You can change the default state. The animation will start from this state after the first call of :playAnimation()
:printAllStates() -- Debug print of the finite state machine states
:getCurrentFrameIndex() -- Get current displayed frame imagetable index
:getCurrentFrameLocalIndex() -- Get the current frame's local index in the state. Index from 1 to frames count. Also works if `frames` property is provided
.currentState -- String field contains current state name

.states.["state_name"] -- OR
.states.state_name -- access state by name to change parameters on-the-go. See example 3B and 3C for usage

:updateAnimation() -- Called by default in the :update() function. Invoke manually to move the animation to the next frame.
Clone this wiki locally