Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Animations . AnimationState

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Animations . AnimationState

The Animation State Component.

This component provides features to apply animations to Game Objects. It is responsible for loading, queuing animations for later playback, mixing between animations and setting the current animation frame to the Game Object that owns this component.

This component lives as an instance within any Game Object that has it defined, such as Sprites.

You can access its properties and methods via the anims property, i.e. Sprite.anims.

As well as playing animations stored in the global Animation Manager, this component can also create animations that are stored locally within it. See the create method for more details.

Prior to Phaser 3.50 this component was called just Animation and lived in the Phaser.GameObjects.Components namespace. It was renamed to AnimationState in 3.50 to help better identify its true purpose when browsing the documentation.

Constructor:

new AnimationState(parent)

Parameters:

name type description
parent Phaser.GameObjects.GameObject

The Game Object to which this animation component belongs.

Since: 3.0.0

Members

<private> _paused: boolean
Focus
Focus

Description:

Is the Animation paused?

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
<private> _pendingStop: number
Focus
Focus

Description:

Internal property tracking if this Animation is waiting to stop.

0 = No 1 = Waiting for ms to pass 2 = Waiting for repeat 3 = Waiting for specific frame

Type:
number
Since: 3.4.0
Focus
Focus
<private> _pendingStopValue: any
Focus
Focus

Description:

Internal property used by _pendingStop.

Type:
any
Since: 3.4.0
Focus
Focus
<private> _wasPlaying: boolean
Focus
Focus

Description:

Was the animation previously playing before being paused?

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
accumulator: number
Focus
Focus

Description:

Internal time overflow accumulator.

This has the delta time added to it as part of the update step.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

A reference to the global Animation Manager.

Type:
Since: 3.0.0
Focus
Focus
<protected> anims: Phaser.Structs.Map.<string, Phaser.Animations.Animation>
Focus
Focus

Description:

The Animations stored locally in this Animation component.

Do not modify the contents of this Map directly, instead use the add, create and remove methods of this class instead.

Type:
Since: 3.50.0
Focus
Focus
<nullable> currentAnim: Phaser.Animations.Animation
Focus
Focus

Description:

The current Animation loaded into this Animation component.

Will by null if no animation is yet loaded.

Type:
Default: null
Since: 3.0.0
Focus
Focus
<nullable> currentFrame: Phaser.Animations.AnimationFrame
Focus
Focus

Description:

The current AnimationFrame being displayed by this Animation component.

Will by null if no animation is yet loaded.

Type:
Default: null
Since: 3.0.0
Focus
Focus
delay: number
Focus
Focus

Description:

The delay before starting playback of the current animation, in milliseconds.

This value is set when a new animation is loaded into this component and should be treated as read-only, as changing it once playback has started will not alter the animation. To change the delay, provide a new value in the PlayAnimationConfig object.

Prior to Phaser 3.50 this property was private and called _delay.

Type:
number
Default: 0
Since: 3.50.0
Focus
Focus
delayCounter: number
Focus
Focus

Description:

A counter keeping track of how much delay time, in milliseconds, is left before playback begins.

This is set via the playAfterDelay method, although it can be modified at run-time if required, as long as the animation has not already started playing.

Type:
number
Default: 0
Since: 3.50.0
Focus
Focus
duration: number
Focus
Focus

Description:

The duration of the current animation, in milliseconds.

This value is set when a new animation is loaded into this component and should be treated as read-only, as changing it once playback has started will not alter the animation. To change the duration, provide a new value in the PlayAnimationConfig object.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
forward: boolean
Focus
Focus

Description:

Is the playhead moving forwards (true) or in reverse (false) ?

Type:
boolean
Default: true
Since: 3.0.0
Focus
Focus
frameRate: number
Focus
Focus

Description:

The frame rate of playback, of the current animation, in frames per second.

This value is set when a new animation is loaded into this component and should be treated as read-only, as changing it once playback has started will not alter the animation. To change the frame rate, provide a new value in the PlayAnimationConfig object.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
hasStarted: boolean
Focus
Focus

Description:

Has the current animation started playing, or is it waiting for a delay to expire?

Type:
boolean
Default: false
Since: 3.50.0
Focus
Focus
hideOnComplete: boolean
Focus
Focus

Description:

Should the GameObject's visible property be set to false when the animation completes?

This value is set when a new animation is loaded into this component, but can also be modified at run-time, assuming the animation is still actively playing.

Type:
boolean
Since: 3.50.0
Focus
Focus
inReverse: boolean
Focus
Focus

Description:

An internal trigger that tells the component if it should plays the animation in reverse mode ('true') or not ('false'). This is used because forward can be changed by the yoyo feature.

Prior to Phaser 3.50 this property was private and called _reverse.

Type:
boolean
Default: false
Since: 3.50.0
Focus
Focus
<readonly> isPaused: boolean
Focus
Focus

Description:

true if the current animation is paused, otherwise false.

Type:
boolean
Since: 3.4.0
Focus
Focus
isPlaying: boolean
Focus
Focus

Description:

Is an animation currently playing or not?

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
msPerFrame: number
Focus
Focus

Description:

The number of milliseconds per frame, not including frame specific modifiers that may be present in the Animation data.

This value is calculated when a new animation is loaded into this component and should be treated as read-only. Changing it will not alter playback speed.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

The key, instance, or config of the next Animation to be loaded into this Animation component when the current animation completes.

Will by null if no animation has been queued.

Type:
Default: null
Since: 3.16.0
Focus
Focus
nextAnimsQueue: array
Focus
Focus

Description:

A queue of Animations to be loaded into this Animation component when the current animation completes.

Populate this queue via the chain method.

Type:
array
Since: 3.24.0
Focus
Focus
nextTick: number
Focus
Focus

Description:

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

This value is compared against the accumulator as part of the update step.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus

Description:

The Game Object to which this animation component belongs.

You can typically access this component from the Game Object via the this.anims property.

Type:
Since: 3.0.0
Focus
Focus
pendingRepeat: boolean
Focus
Focus

Description:

An internal flag keeping track of pending repeats.

Type:
boolean
Default: false
Since: 3.0.0
Focus
Focus
repeat: number
Focus
Focus

Description:

The number of times to repeat playback of the current animation.

If -1, it means the animation will repeat forever.

This value is set when a new animation is loaded into this component and should be treated as read-only, as changing it once playback has started will not alter the animation. To change the number of repeats, provide a new value in the PlayAnimationConfig object.

Prior to Phaser 3.50 this property was private and called _repeat.

Type:
number
Default: 0
Since: 3.50.0
Focus
Focus
repeatCounter: number
Focus
Focus

Description:

A counter that keeps track of how many repeats are left to run.

This value is set when a new animation is loaded into this component, but can also be modified at run-time.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
repeatDelay: number
Focus
Focus

Description:

The number of milliseconds to wait before starting the repeat playback of the current animation.

This value is set when a new animation is loaded into this component, but can also be modified at run-time.

You can change the repeat delay by providing a new value in the PlayAnimationConfig object.

Prior to Phaser 3.50 this property was private and called _repeatDelay.

Type:
number
Default: 0
Since: 3.0.0
Focus
Focus
showOnStart: boolean
Focus
Focus

Description:

Should the GameObject's visible property be set to true when the animation starts to play?

This will happen after any delay that may have been set.

This value is set when a new animation is loaded into this component, but can also be modified at run-time, assuming the animation is currently delayed.

Type:
boolean
Since: 3.50.0
Focus
Focus
skipMissedFrames: boolean
Focus
Focus

Description:

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

Type:
boolean
Default: true
Since: 3.0.0
Focus
Focus
<protected> textureManager: Phaser.Textures.TextureManager
Focus
Focus

Description:

A reference to the Texture Manager.

Type:
Since: 3.50.0
Focus
Focus
timeScale: number
Focus
Focus

Description:

The Time Scale factor.

You can adjust this value to modify the passage of time for the animation that is currently playing. For example, setting it to 2 will make the animation play twice as fast. Or setting it to 0.5 will slow the animation down.

You can change this value at run-time, or set it via the PlayAnimationConfig.

Prior to Phaser 3.50 this property was private and called _timeScale.

Type:
number
Default: 1
Since: 3.50.0
Focus
Focus
yoyo: boolean
Focus
Focus

Description:

Should the current animation yoyo? An animation that yoyos will play in reverse, from the end to the start, before then repeating or completing. An animation that does not yoyo will just play from the start to the end.

This value is set when a new animation is loaded into this component, but can also be modified at run-time.

You can change the yoyo by providing a new value in the PlayAnimationConfig object.

Prior to Phaser 3.50 this property was private and called _yoyo.

Type:
boolean
Default: false
Since: 3.50.0
Focus
Focus

Methods

chain(key)
Focus
Focus

Description:

Sets an animation, or an array of animations, to be played in the future, after the current one completes or stops.

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

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

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 event).

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 all currently chained animations.

Parameters:

name type description
key string | Array.<string> | Phaser.Animations.Animation | Array.<Phaser.Animations.Animation> | Phaser.Types.Animations.PlayAnimationConfig | Array.<Phaser.Types.Animations.PlayAnimationConfig>

The string-based key of the animation to play, or an Animation instance, or a PlayAnimationConfig object, or an array of them.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.16.0
Focus
Focus
complete()
Focus
Focus

Description:

The current animation has completed. This dispatches the ANIMATION_COMPLETE event.

This method is called by the Animation instance and should not usually be invoked directly.

If no animation is loaded, no events will be dispatched.

If another animation has been queued for playback, it will be started after the events fire.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.50.0
Focus
Focus
create(config)
Focus
Focus

Description:

Creates a new Animation that is local specifically to this Sprite.

When a Sprite owns an animation, it is kept out of the global Animation Manager, which means you're free to use keys that may be already defined there. Unless you specifically need a Sprite to have a unique animation, you should favor using global animations instead, as they allow for the same animation to be used across multiple Sprites, saving on memory. However, if this Sprite is the only one to use this animation, it's sensible to create it here.

If an invalid key is given this method will return false.

If you pass the key of an animation that already exists locally, that animation will be returned.

A brand new animation is only created if the key is valid and not already in use by this Sprite.

If you wish to re-use an existing key, call the remove method first, then this method.

Parameters:

name type description
config Phaser.Types.Animations.Animation

The configuration settings for the Animation.

Returns:
Description:

The Animation that was created, or false if the key is already in use.

Examples:
Since: 3.50.0
Focus
Focus
destroy()
Focus
Focus

Description:

Destroy this Animation component.

Unregisters event listeners and cleans up its references.

Examples:
Since: 3.0.0
Focus
Focus
<private> emitEvents(event)
Focus
Focus

Description:

Fires the given animation event.

Parameters:

name type description
event string

The Animation Event to dispatch.

Examples:
Since: 3.50.0
Focus
Focus
exists(key)
Focus
Focus

Description:

Checks to see if the given key is already used locally within the animations stored on this Sprite.

Parameters:

name type description
key string

The key of the Animation to check.

Returns:
Description:

true if the Animation exists locally, or false if the key is available, or there are no local animations.

Type:
  • boolean
Examples:
Since: 3.50.0
Focus
Focus
generateFrameNames(key, [config])
Focus
Focus

Description:

Generate an array of Phaser.Types.Animations.AnimationFrame objects from a texture key and configuration object.

Generates objects with string based frame names, as configured by the given Phaser.Types.Animations.GenerateFrameNames.

It's a helper method, designed to make it easier for you to extract all of the frame names from texture atlases. If you're working with a sprite sheet, see the generateFrameNumbers method instead.

Example:

If you have a texture atlases loaded called gems and it contains 6 frames called ruby_0001, ruby_0002, and so on, then you can call this method using: this.anims.generateFrameNames('gems', { prefix: 'ruby_', end: 6, zeroPad: 4 }).

The end value tells it to look for 6 frames, incrementally numbered, all starting with the prefix ruby_. The zeroPad value tells it how many zeroes pad out the numbers. To create an animation using this method, you can do:

this.anims.create({
  key: 'ruby',
  repeat: -1,
  frames: this.anims.generateFrameNames('gems', {
    prefix: 'ruby_',
    end: 6,
    zeroPad: 4
  })
});

Please see the animation examples for further details.

Parameters:

name type arguments description
key string

The key for the texture containing the animation frames.

config Phaser.Types.Animations.GenerateFrameNames <optional>

The configuration object for the animation frame names.

Returns:
Description:

The array of {@link Phaser.Types.Animations.AnimationFrame} objects.

Examples:
Since: 3.50.0
Focus
Focus
generateFrameNumbers(key, config)
Focus
Focus

Description:

Generate an array of Phaser.Types.Animations.AnimationFrame objects from a texture key and configuration object.

Generates objects with numbered frame names, as configured by the given Phaser.Types.Animations.GenerateFrameNumbers.

If you're working with a texture atlas, see the generateFrameNames method instead.

It's a helper method, designed to make it easier for you to extract frames from sprite sheets. If you're working with a texture atlas, see the generateFrameNames method instead.

Example:

If you have a sprite sheet loaded called explosion and it contains 12 frames, then you can call this method using: this.anims.generateFrameNumbers('explosion', { start: 0, end: 12 }).

The end value tells it to stop after 12 frames. To create an animation using this method, you can do:

this.anims.create({
  key: 'boom',
  frames: this.anims.generateFrameNames('explosion', {
    start: 0,
    end: 12
  })
});

Note that start is optional and you don't need to include it if the animation starts from frame 0.

To specify an animation in reverse, swap the start and end values.

If the frames are not sequential, you may pass an array of frame numbers instead, for example:

this.anims.generateFrameNumbers('explosion', { frames: [ 0, 1, 2, 1, 2, 3, 4, 0, 1, 2 ] })

Please see the animation examples and GenerateFrameNumbers config docs for further details.

Parameters:

name type description
key string

The key for the texture containing the animation frames.

config Phaser.Types.Animations.GenerateFrameNumbers

The configuration object for the animation frames.

Returns:
Description:

The array of {@link Phaser.Types.Animations.AnimationFrame} objects.

Examples:
Since: 3.50.0
Focus
Focus
get(key)
Focus
Focus

Description:

Get an Animation instance that has been created locally on this Sprite.

See the create method for more details.

Parameters:

name type description
key string

The key of the Animation to retrieve.

Returns:
Description:

The Animation, or null if the key is invalid.

Examples:
Since: 3.50.0
Focus
Focus
getFrameName()
Focus
Focus

Description:

Returns the key of the animation frame currently displayed by this component.

Returns:
Description:

The key of the Animation Frame currently displayed by this component, or an empty string if no animation has been loaded.

Type:
  • string
Examples:
Since: 3.50.0
Focus
Focus
getName()
Focus
Focus

Description:

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

Prior to Phaser 3.50 this method was called getCurrentKey.

Returns:
Description:

The key of the Animation currently loaded into this component, or an empty string if none loaded.

Type:
  • string
Examples:
Since: 3.50.0
Focus
Focus
getProgress()
Focus
Focus

Description:

Returns a value between 0 and 1 indicating how far this animation is through, ignoring repeats and yoyos.

The value is based on the current frame and how far that is in the animation, it is not based on the duration of the animation.

Returns:
Description:

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

Type:
  • number
Examples:
Since: 3.4.0
Focus
Focus
getTotalFrames()
Focus
Focus

Description:

Returns the total number of frames in this animation, or returns zero if no animation has been loaded.

Returns:
Description:

The total number of frames in the current animation, or zero if no animation has been loaded.

Type:
  • number
Examples:
Since: 3.4.0
Focus
Focus
globalRemove([key], [animation])
Focus
Focus

Description:

Handle the removal of an animation from the Animation Manager.

Parameters:

name type arguments description
key string <optional>

The key of the removed Animation.

animation Phaser.Animations.Animation <optional>

The removed Animation.

Examples:
Since: 3.50.0
Focus
Focus
<private> handleComplete()
Focus
Focus

Description:

Handles the completion of an animation playback.

Examples:
Since: 3.50.0
Focus
Focus
<private> handleRepeat()
Focus
Focus

Description:

Handles the repeat of an animation.

Examples:
Since: 3.50.0
Focus
Focus
<private> handleStart()
Focus
Focus

Description:

Handles the start of an animation playback.

Examples:
Since: 3.50.0
Focus
Focus
<private> handleStop()
Focus
Focus

Description:

Handles the stop of an animation playback.

Examples:
Since: 3.50.0
Focus
Focus
<protected> load(key)
Focus
Focus

Description:

Internal method used to load an animation into this component.

Parameters:

name type description
key string | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or a PlayAnimationConfig object.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
nextFrame()
Focus
Focus

Description:

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.

Returns:
Description:

The Game Object this Animation Component belongs to.

Examples:
Since: 3.16.0
Focus
Focus
pause([atFrame])
Focus
Focus

Description:

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

Parameters:

name type arguments description
atFrame Phaser.Animations.AnimationFrame <optional>

An optional frame to set after pausing the animation.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
play(key, [ignoreIfPlaying])
Focus
Focus

Description:

Start playing the given animation on this Sprite.

Animations in Phaser can either belong to the global Animation Manager, or specifically to this Sprite.

The benefit of a global animation is that multiple Sprites can all play the same animation, without having to duplicate the data. You can just create it once and then play it on any Sprite.

The following code shows how to create a global repeating animation. The animation will be created from all of the frames within the sprite sheet that was loaded with the key 'muybridge':

var config = {
    key: 'run',
    frames: 'muybridge',
    frameRate: 15,
    repeat: -1
};

//  This code should be run from within a Scene:
this.anims.create(config);

However, if you wish to create an animation that is unique to this Sprite, and this Sprite alone, you can call the Animation.create method instead. It accepts the exact same parameters as when creating a global animation, however the resulting data is kept locally in this Sprite.

With the animation created, either globally or locally, you can now play it on this Sprite:

this.add.sprite(x, y).play('run');

Alternatively, if you wish to run it at a different frame rate, for example, you can pass a config object instead:

this.add.sprite(x, y).play({ key: 'run', frameRate: 24 });

When playing an animation on a Sprite it will first check to see if it can find a matching key locally within the Sprite. If it can, it will play the local animation. If not, it will then search the global Animation Manager and look for it there.

If you need a Sprite to be able to play both local and global animations, make sure they don't have conflicting keys.

See the documentation for the PlayAnimationConfig config object for more details about this.

Also, see the documentation in the Animation Manager for further details on creating animations.

Parameters:

name type arguments Default description
key string | Phaser.Animations.Animation | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or an Animation instance, or a PlayAnimationConfig object.

ignoreIfPlaying boolean <optional> false

If this animation is already playing then ignore this call.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
playAfterDelay(key, delay)
Focus
Focus

Description:

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

If the animation also has a delay value set in its config, it will be added to the delay given here.

If an animation is already running and a new animation is given to this method, it will wait for the given delay before starting the new animation.

If no animation is currently running, the given one begins after the delay.

Prior to Phaser 3.50 this method was called 'delayedPlay' and the parameters were in the reverse order.

Parameters:

name type description
key string | Phaser.Animations.Animation | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or an Animation instance, or a PlayAnimationConfig object.

delay number

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

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.50.0
Focus
Focus
playAfterRepeat(key, [repeatCount])
Focus
Focus

Description:

Waits for the current animation to complete the repeatCount number of repeat cycles, then starts playback of the given animation.

You can use this to ensure there are no harsh jumps between two sets of animations, i.e. going from an idle animation to a walking animation, by making them blend smoothly into each other.

If no animation is currently running, the given one will start immediately.

Parameters:

name type arguments Default description
key string | Phaser.Animations.Animation | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or an Animation instance, or a PlayAnimationConfig object.

repeatCount number <optional> 1

How many times should the animation repeat before the next one starts?

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.50.0
Focus
Focus
playReverse(key, [ignoreIfPlaying])
Focus
Focus

Description:

Start playing the given animation on this Sprite, in reverse.

Animations in Phaser can either belong to the global Animation Manager, or specifically to this Sprite.

The benefit of a global animation is that multiple Sprites can all play the same animation, without having to duplicate the data. You can just create it once and then play it on any Sprite.

The following code shows how to create a global repeating animation. The animation will be created from all of the frames within the sprite sheet that was loaded with the key 'muybridge':

var config = {
    key: 'run',
    frames: 'muybridge',
    frameRate: 15,
    repeat: -1
};

//  This code should be run from within a Scene:
this.anims.create(config);

However, if you wish to create an animation that is unique to this Sprite, and this Sprite alone, you can call the Animation.create method instead. It accepts the exact same parameters as when creating a global animation, however the resulting data is kept locally in this Sprite.

With the animation created, either globally or locally, you can now play it on this Sprite:

this.add.sprite(x, y).playReverse('run');

Alternatively, if you wish to run it at a different frame rate, for example, you can pass a config object instead:

this.add.sprite(x, y).playReverse({ key: 'run', frameRate: 24 });

When playing an animation on a Sprite it will first check to see if it can find a matching key locally within the Sprite. If it can, it will play the local animation. If not, it will then search the global Animation Manager and look for it there.

If you need a Sprite to be able to play both local and global animations, make sure they don't have conflicting keys.

See the documentation for the PlayAnimationConfig config object for more details about this.

Also, see the documentation in the Animation Manager for further details on creating animations.

Parameters:

name type arguments Default description
key string | Phaser.Animations.Animation | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or an Animation instance, or a PlayAnimationConfig object.

ignoreIfPlaying boolean <optional> false

If an animation is already playing then ignore this call.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.12.0
Focus
Focus
previousFrame()
Focus
Focus

Description:

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.

Returns:
Description:

The Game Object this Animation Component belongs to.

Examples:
Since: 3.16.0
Focus
Focus
remove(key)
Focus
Focus

Description:

Removes a locally created Animation from this Sprite, based on the given key.

Once an Animation has been removed, this Sprite cannot play it again without re-creating it.

Parameters:

name type description
key string

The key of the animation to remove.

Returns:
Description:

The Animation instance that was removed from this Sprite, if the key was valid.

Examples:
Since: 3.50.0
Focus
Focus
restart([includeDelay], [resetRepeats])
Focus
Focus

Description:

Restarts the current animation from its beginning.

You can optionally reset the delay and repeat counters as well.

Calling this will fire the ANIMATION_RESTART event immediately.

If you includeDelay then it will also fire the ANIMATION_START event once the delay has expired, otherwise, playback will just begin immediately.

Parameters:

name type arguments Default description
includeDelay boolean <optional> false

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

resetRepeats boolean <optional> false

Whether to reset the repeat counter or not?

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
resume([fromFrame])
Focus
Focus

Description:

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 arguments description
fromFrame Phaser.Animations.AnimationFrame <optional>

An optional frame to set before restarting playback.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
reverse()
Focus
Focus

Description:

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

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.12.0
Focus
Focus
setCurrentFrame(animationFrame)
Focus
Focus

Description:

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

Parameters:

name type description
animationFrame Phaser.Animations.AnimationFrame

The animation frame to change to.

Returns:
Description:

The Game Object this Animation Component belongs to.

Examples:
Since: 3.4.0
Focus
Focus
setProgress([value])
Focus
Focus

Description:

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.

The value is based on the current frame and how far that is in the animation, it is not based on the duration of the animation.

Parameters:

name type arguments description
value number <optional>

The progress value, between 0 and 1.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.4.0
Focus
Focus
setRepeat(value)
Focus
Focus

Description:

Sets the number of times that the animation should repeat after its first play through. 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. The value should always be an integer.

Calling this method only works if the animation is already running. Otherwise, any value specified here will be overwritten when the next animation loads in. To avoid this, use the repeat property of the PlayAnimationConfig object instead.

Parameters:

name type description
value number

The number of times that the animation should repeat.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.4.0
Focus
Focus
startAnimation(key)
Focus
Focus

Description:

Load the animation based on the key and set-up all of the internal values needed for playback to start. If there is no delay, it will also fire the start events.

Parameters:

name type description
key string | Phaser.Types.Animations.PlayAnimationConfig

The string-based key of the animation to play, or a PlayAnimationConfig object.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.50.0
Focus
Focus
stop()
Focus
Focus

Description:

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

If no animation is running, no events will be dispatched.

If there is another animation in the queue (set via the chain method) then it will start playing.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.0.0
Focus
Focus
stopAfterDelay(delay)
Focus
Focus

Description:

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

It then dispatches the ANIMATION_STOP event.

If no animation is running, no events will be dispatched.

If there is another animation in the queue (set via the chain method) then it will start playing, when the current one stops.

Parameters:

name type description
delay number

The number of milliseconds to wait before stopping this animation.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.4.0
Focus
Focus
stopAfterRepeat([repeatCount])
Focus
Focus

Description:

Stops the current animation from playing when it next repeats.

It then dispatches the ANIMATION_STOP event.

If no animation is running, no events will be dispatched.

If there is another animation in the queue (set via the chain method) then it will start playing, when the current one stops.

Prior to Phaser 3.50 this method was called stopOnRepeat and had no parameters.

Parameters:

name type arguments Default description
repeatCount number <optional> 1

How many times should the animation repeat before stopping?

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.50.0
Focus
Focus
stopOnFrame(frame)
Focus
Focus

Description:

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.

It then dispatches the ANIMATION_STOP event.

If no animation is running, no events will be dispatched.

If there is another animation in the queue (set via the chain method) then it will start playing, when the current one stops.

Parameters:

name type description
frame Phaser.Animations.AnimationFrame

The frame to check before stopping this animation.

Returns:
Description:

The Game Object that owns this Animation Component.

Examples:
Since: 3.4.0
Focus
Focus
update(time, delta)
Focus
Focus

Description:

The internal update loop for the AnimationState Component.

This is called automatically by the Sprite.preUpdate method.

Parameters:

name type description
time number

The current timestamp.

delta number

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

Examples:
Since: 3.0.0
Focus
Focus