Deprecated: Phaser 3 API Documentation

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:

Source: src/gameobjects/components/Animation.js (Line 210)

animationManager :Phaser.Animations.AnimationManager

A reference to the global Animation Manager.

Type:

Phaser.Animations.AnimationManager

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:

Phaser.Animations.Animation

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:

Phaser.Animations.AnimationFrame

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:

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:

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:

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:

Source: src/gameobjects/components/Animation.js (Line 220)

parent :Phaser.GameObjects.GameObject

The Game Object to which this animation controller belongs.

Type:

Phaser.GameObjects.GameObject

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:

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 1146)

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 637)

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 703)

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 741)

Returns:

The delay between repeats.

Type: number

getTimeScale()

Gets the Time Scale factor.

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

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 947)

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 1132)

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 1068)

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 this 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 1090)

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 682)

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 774)

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 617)

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 994)

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 659)

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 719)

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 754)

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 914)

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 1112)

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 815)

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 859)

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.