Class: Animation

Phaser.GameObjects.Components. Animation

A Game Object Animation Controller.

This controller lives as an instance within a Game Object, accessible as sprite.anims.


new Animation(parent)

Parameters:
Name Type Description
parent Phaser.GameObjects.GameObject

The Game Object to which this animation controller belongs.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 11)

Members


accumulator :number

Internal time overflow accumulator.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 210)

animationManager :Phaser.Animations.AnimationManager

A reference to the global Animation Manager.

Type:
Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 39)

<nullable> currentAnim :Phaser.Animations.Animation

The current Animation loaded into this Animation Controller.

Type:
Since: 3.0.0
Default Value:
  • null
Source: src/gameobjects/components/Animation.js (Line 60)

<nullable> currentFrame :Phaser.Animations.AnimationFrame

The current AnimationFrame being displayed by this Animation Controller.

Type:
Since: 3.0.0
Default Value:
  • null
Source: src/gameobjects/components/Animation.js (Line 70)

duration :number

How long the animation should play for, in milliseconds. If the frameRate property has been set then it overrides this value, otherwise the frameRate is derived from duration.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 112)

forward :boolean

Will the playhead move forwards (true) or in reverse (false).

Type:
  • boolean
Since: 3.0.0
Default Value:
  • true
Source: src/gameobjects/components/Animation.js (Line 188)

frameRate :number

The frame rate of playback in frames per second. The default is 24 if the duration property is null.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 101)

<readonly> isPaused :boolean

true if the current animation is paused, otherwise false.

Type:
  • boolean
Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 480)

isPlaying :boolean

Is an animation currently playing or not?

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/components/Animation.js (Line 50)

msPerFrame :number

ms per frame, not including frame specific modifiers that may be present in the Animation data.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 124)

<nullable> nextAnim :string

The key of the next Animation to be loaded into this Animation Controller when the current animation completes.

Type:
  • string
Since: 3.16.0
Default Value:
  • null
Source: src/gameobjects/components/Animation.js (Line 80)

nextTick :number

The time point at which the next animation frame will change.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 220)

parent :Phaser.GameObjects.GameObject

The Game Object to which this animation controller belongs.

Type:
Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 30)

pendingRepeat :boolean

An internal flag keeping track of pending repeats.

Type:
  • boolean
Since: 3.0.0
Default Value:
  • false
Source: src/gameobjects/components/Animation.js (Line 240)

repeatCounter :number

An internal counter keeping track of how many repeats are left to play.

Type:
  • number
Since: 3.0.0
Default Value:
  • 0
Source: src/gameobjects/components/Animation.js (Line 230)

skipMissedFrames :boolean

Skip frames if the time lags, or always advanced anyway?

Type:
  • boolean
Since: 3.0.0
Default Value:
  • true
Source: src/gameobjects/components/Animation.js (Line 134)

Methods


_startAnimation(key [, startFrame])

Load an Animation and fires 'onStartEvent' event, extracted from 'play' method.

Parameters:
Name Type Argument Default Description
key string

The string-based key of the animation to play, as defined previously in the Animation Manager.

startFrame integer <optional>
0

Optionally start the animation playing from this frame index.

Since: 3.12.0
Source: src/gameobjects/components/Animation.js (Line 567)
Fires:
  • Phaser.Animations.Events#event:START_ANIMATION_EVENT
  • Phaser.Animations.Events#event:SPRITE_START_ANIMATION_EVENT
  • Phaser.Animations.Events#event:SPRITE_START_KEY_ANIMATION_EVENT
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

chain( [key])

Sets an animation to be played immediately after the current one completes.

The current animation must enter a 'completed' state for this to happen, i.e. finish all of its repeats, delays, etc, or have the stop method called directly on it.

An animation set to repeat forever will never enter a completed state.

You can chain a new animation at any point, including before the current one starts playing, during it, or when it ends (via its animationcomplete callback). Chained animations are specific to a Game Object, meaning different Game Objects can have different chained animations without impacting the global animation they're playing.

Call this method with no arguments to reset the chained animation.

Parameters:
Name Type Argument Description
key string | Phaser.Animations.Animation <optional>

The string-based key of the animation to play next, as defined previously in the Animation Manager. Or an Animation instance.

Since: 3.16.0
Source: src/gameobjects/components/Animation.js (Line 298)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

delayedPlay(delay, key [, startFrame])

Waits for the specified delay, in milliseconds, then starts playback of the requested animation.

Parameters:
Name Type Argument Default Description
delay integer

The delay, in milliseconds, to wait before starting the animation playing.

key string

The key of the animation to play.

startFrame integer <optional>
0

The frame of the animation to start from.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 361)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

destroy()

Destroy this Animation component.

Unregisters event listeners and cleans up its references.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 1141)

getCurrentKey()

Returns the key of the animation currently loaded into this component.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 382)
Returns:

The key of the Animation loaded into this component.

Type
string

getDelay()

Gets the amount of time, in milliseconds that the animation will be delayed before starting playback.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 348)
Returns:

The amount of time, in milliseconds, the Animation will wait before starting playback.

Type
integer

getProgress()

Returns a value between 0 and 1 indicating how far this animation is through, ignoring repeats and yoyos. If the animation has a non-zero repeat defined, getProgress and getTotalProgress will be different because getProgress doesn't include any repeats or repeat delays, whereas getTotalProgress does.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 632)
Returns:

The progress of the current animation, between 0 and 1.

Type
number

getRepeat()

Gets the number of times that the animation will repeat after its first iteration. For example, if returns 1, the animation will play a total of twice (the initial play plus 1 repeat). A value of -1 means the animation will repeat indefinitely.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 698)
Returns:

The number of times that the animation will repeat.

Type
integer

getRepeatDelay()

Gets the amount of delay between repeats, if any.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 736)
Returns:

The delay between repeats.

Type
number

getTimeScale()

Gets the Time Scale factor.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 929)
Returns:

The Time Scale value.

Type
number

getTotalFrames()

Returns the total number of frames in this animation.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 942)
Returns:

The total number of frames in this animation.

Type
integer

getYoyo()

Gets if the current Animation will yoyo when it reaches the end. A yoyo'ing animation will play through consecutively, and then reverse-play back to the start again.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 1127)
Returns:

true if the animation is set to yoyo, false if not.

Type
boolean

<protected> load(key [, startFrame])

Internal method used to load an animation into this component.

Parameters:
Name Type Argument Default Description
key string

The key of the animation to load.

startFrame integer <optional>
0

The start frame of the animation to load.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 398)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

nextFrame()

Advances the animation to the next frame, regardless of the time or animation state. If the animation is set to repeat, or yoyo, this will still take effect.

Calling this does not change the direction of the animation. I.e. if it was currently playing in reverse, calling this method doesn't then change the direction to forwards.

Since: 3.16.0
Source: src/gameobjects/components/Animation.js (Line 1063)
Returns:

The Game Object this Animation Component belongs to.

Type
Phaser.GameObjects.GameObject

pause( [atFrame])

Pause the current animation and set the isPlaying property to false. You can optionally pause it at a specific frame.

Parameters:
Name Type Argument Description
atFrame Phaser.Animations.AnimationFrame <optional>

An optional frame to set after pausing the animation.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 425)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

play(key [, ignoreIfPlaying] [, startFrame])

Plays an Animation on a Game Object that has the Animation component, such as a Sprite.

Animations are stored in the global Animation Manager and are referenced by a unique string-based key.

Parameters:
Name Type Argument Default Description
key string | Phaser.Animations.Animation

The string-based key of the animation to play, as defined previously in the Animation Manager. Or an Animation instance.

ignoreIfPlaying boolean <optional>
false

If an animation is already playing then ignore this call.

startFrame integer <optional>
0

Optionally start the animation playing from this frame index.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 497)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onStartEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

playReverse(key [, ignoreIfPlaying] [, startFrame])

Plays an Animation (in reverse mode) on the Game Object that owns this Animation Component.

Parameters:
Name Type Argument Default Description
key string | Phaser.Animations.Animation

The string-based key of the animation to play, as defined previously in the Animation Manager. Or an Animation instance.

ignoreIfPlaying boolean <optional>
false

If an animation is already playing then ignore this call.

startFrame integer <optional>
0

Optionally start the animation playing from this frame index.

Since: 3.12.0
Source: src/gameobjects/components/Animation.js (Line 533)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onStartEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

previousFrame()

Advances the animation to the previous frame, regardless of the time or animation state. If the animation is set to repeat, or yoyo, this will still take effect.

Calling this does not change the direction of the animation. I.e. if it was currently playing in forwards, calling this method doesn't then change the direction to backwards.

Since: 3.16.0
Source: src/gameobjects/components/Animation.js (Line 1085)
Returns:

The Game Object this Animation Component belongs to.

Type
Phaser.GameObjects.GameObject

remove( [key] [, animation])

Handle the removal of an animation from the Animation Manager.

Parameters:
Name Type Argument Description
key string <optional>

The key of the removed Animation.

animation Phaser.Animations.Animation <optional>

The removed Animation.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 677)

restart( [includeDelay])

Restarts the current animation from its beginning, optionally including its delay value.

Parameters:
Name Type Argument Default Description
includeDelay boolean <optional>
false

Whether to include the delay value of the animation when restarting.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 769)
Fires:
  • Phaser.Animations.Events#event:RESTART_ANIMATION_EVENT
  • Phaser.Animations.Events#event:SPRITE_RESTART_ANIMATION_EVENT
  • Phaser.Animations.Events#event:SPRITE_RESTART_KEY_ANIMATION_EVENT
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

resume( [fromFrame])

Resumes playback of a paused animation and sets the isPlaying property to true. You can optionally tell it to start playback from a specific frame.

Parameters:
Name Type Argument Description
fromFrame Phaser.Animations.AnimationFrame <optional>

An optional frame to set before restarting playback.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 453)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

reverse()

Reverse the Animation that is already playing on the Game Object.

Since: 3.12.0
Source: src/gameobjects/components/Animation.js (Line 612)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setCurrentFrame(animationFrame)

Sets the given Animation Frame as being the current frame and applies it to the parent Game Object, adjusting its size and origin as needed.

Parameters:
Name Type Description
animationFrame Phaser.Animations.AnimationFrame

The Animation Frame to set as being current.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 989)
Returns:

The Game Object this Animation Component belongs to.

Type
Phaser.GameObjects.GameObject

setDelay( [value])

Sets the amount of time, in milliseconds, that the animation will be delayed before starting playback.

Parameters:
Name Type Argument Default Description
value integer <optional>
0

The amount of time, in milliseconds, to wait before starting playback.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 329)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setProgress( [value])

Takes a value between 0 and 1 and uses it to set how far this animation is through playback. Does not factor in repeats or yoyos, but does handle playing forwards or backwards.

Parameters:
Name Type Argument Default Description
value number <optional>
0

The progress value, between 0 and 1.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 654)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setRepeat(value)

Sets the number of times that the animation should repeat after its first iteration. For example, if repeat is 1, the animation will play a total of twice (the initial play plus 1 repeat). To repeat indefinitely, use -1. repeat should always be an integer.

Parameters:
Name Type Description
value integer

The number of times that the animation should repeat.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 714)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setRepeatDelay(value)

Sets the amount of time in seconds between repeats. For example, if repeat is 2 and repeatDelay is 10, the animation will play initially, then wait for 10 seconds before repeating, then play again, then wait another 10 seconds before doing its final repeat.

Parameters:
Name Type Description
value number

The delay to wait between repeats, in seconds.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 749)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setTimeScale( [value])

Sets the Time Scale factor, allowing you to make the animation go go faster or slower than default. Where 1 = normal speed (the default), 0.5 = half speed, 2 = double speed, etc.

Parameters:
Name Type Argument Default Description
value number <optional>
1

The time scale factor, where 1 is no change, 0.5 is half speed, etc.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 909)
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

setYoyo( [value])

Sets if the current Animation will yoyo when it reaches the end. A yoyo'ing animation will play through consecutively, and then reverse-play back to the start again.

Parameters:
Name Type Argument Default Description
value boolean <optional>
false

true if the animation should yoyo, false to not.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 1107)
Returns:

The Game Object this Animation Component belongs to.

Type
Phaser.GameObjects.GameObject

stop()

Immediately stops the current animation from playing and dispatches the animationcomplete event.

If no animation is set, no event will be dispatched.

If there is another animation queued (via the chain method) then it will start playing immediately.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 810)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onCompleteEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

stopAfterDelay(delay)

Stops the current animation from playing after the specified time delay, given in milliseconds.

Parameters:
Name Type Description
delay integer

The number of milliseconds to wait before stopping this animation.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 854)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onCompleteEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

stopOnFrame(frame)

Stops the current animation from playing when it next sets the given frame. If this frame doesn't exist within the animation it will not stop it from playing.

Parameters:
Name Type Description
frame Phaser.Animations.AnimationFrame

The frame to check before stopping this animation.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 889)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onCompleteEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

stopOnRepeat()

Stops the current animation from playing when it next repeats.

Since: 3.4.0
Source: src/gameobjects/components/Animation.js (Line 873)
Fires:
  • Phaser.GameObjects.Components.Animation#event:onCompleteEvent
Returns:

The Game Object that owns this Animation Component.

Type
Phaser.GameObjects.GameObject

update(time, delta)

The internal update loop for the Animation Component.

Parameters:
Name Type Description
time number

The current timestamp.

delta number

The delta time, in ms, elapsed since the last frame.

Since: 3.0.0
Source: src/gameobjects/components/Animation.js (Line 955)