SpriteAnimation Component

Events

StartAnimation [Data = {Reel}]
When an animation starts playing, or is resumed from the paused state
AnimationEnd [Data = { Reel }]
When the animation finishes
FrameChange [Data = { Reel }]
Each time the frame of the current reel changes
ReelChange [Data = { Reel }]
When the reel changes

Used to animate sprites by treating a sprite map as a set of animation frames. Must be applied to an entity that has a sprite-map component.

To define an animation, see the reel method. To play an animation, see the animate method.

A reel is an object that contains the animation frames and current state for an animation. The reel object has the following properties:

id: (String)

the name of the reel

frames: (Array)

A list of frames in the format [xpos, ypos]

currentFrame: (Number)

The index of the current frame

easing: (Crafty.easing object)

The object that handles the internal progress of the animation.

duration: (Number)

The duration in milliseconds.

Many animation related events pass a reel object as data. As typical with events, this should be treated as read only data that might be later altered by the entity. If you wish to preserve the data, make a copy of it.

Properties

Methods

Back to top

.animationSpeed

The playback rate of the animation. This property defaults to 1.

Back to top

.animate()

public this .animate([String reelId] [, Number loopCount])
reelId

ID of the animation reel to play. Defaults to the current reel if none is specified.

loopCount

Number of times to repeat the animation. Use -1 to repeat indefinitely. Defaults to 1.

Play one of the reels previously defined through .reel(...). Simply pass the name of the reel. If you wish the animation to play multiple times in succession, pass in the amount of times as an additional parameter. To have the animation repeat indefinitely, pass in -1.

If another animation is currently playing, it will be paused.

This will always play an animation from the beginning. If you wish to resume from the current state of a reel, use resumeAnimation().

Once an animation ends, it will remain at its last frame.

Example

// Define a sprite-map component
Crafty.sprite(16, "images/sprite.png", {
    PlayerSprite: [0,0]
});

// Play the animation across 20 frames (so each sprite in the 4 sprite animation should be seen for 5 frames) and repeat indefinitely
Crafty.e("2D, DOM, SpriteAnimation, PlayerSprite")
    .reel('PlayerRunning', 20, 0, 0, 3) // setup animation
    .animate('PlayerRunning', -1); // start animation
Back to top

.getReel()

public Reel .getReel()
[Returns]

The current reel, or null if there is no active reel

public Reel .getReel(reelId)
reelId

The id of the reel to fetch.

[Returns]

The specified reel, or undefined if no such reel exists.

Back to top

.isPlaying()

public Boolean .isPlaying([String reelId])
reelId

The reelId of the reel we wish to examine

[Returns]

The current animation state

Determines if the specified animation is currently playing. If no reelId is specified, checks if any animation is playing.

Example

myEntity.isPlaying() // is any animation playing
myEntity.isPlaying('PlayerRunning') // is the PlayerRunning animation playing
Back to top

.loops()

public this .loops(Number loopCount)
loopCount

The number of times to play the animation

Sets the number of times the animation will loop for. If called while an animation is in progress, the current state will be considered the first loop.

public Number .loops()
[Returns]

The number of loops left. Returns 0 if no reel is active.

Back to top

.pauseAnimation()

public this .pauseAnimation(void)

Pauses the currently playing animation, or does nothing if no animation is playing.

Back to top

.reel()

Used to define reels, to change the active reel, and to fetch the id of the active reel.

public this .reel(String reelId, Duration duration, Number fromX, Number fromY, Number frameCount[, Number rowLength])

Defines a reel by starting and ending position on the sprite sheet.

reelId

ID of the animation reel being created

duration

The length of the animation in milliseconds.

fromX

Starting x position on the sprite map (x's unit is the horizontal size of the sprite in the sprite map).

fromY

y position on the sprite map (y's unit is the horizontal size of the sprite in the sprite map). Remains constant through the animation.

frameCount

The number of sequential frames in the animation. If negative, the animation will play backwards.

rowLength

The number of frames in a sprite sheet row. The sequential frames will auto-wrap to a new row when they reach the end of the current row. This is an optional argument that defaults to Infinity.

public this .reel(String reelId, Duration duration, Array frames)

Defines a reel by an explicit list of frames

reelId

ID of the animation reel being created

duration

The length of the animation in milliseconds.

frames

An array of arrays containing the x and y values of successive frames: [[x1,y1],[x2,y2],...] (the values are in the unit of the sprite map's width/height respectively).

public this .reel(String reelId, Duration duration, Array frames)

Defines a reel by an explicit list of frames with sprite names

reelId

ID of the animation reel being created

duration

The length of the animation in milliseconds.

frames

An array of strings containing the sprite names of successive frames: ['spriteName1','spriteName2',...].

public this .reel(String reelId)

Switches to the specified reel. The sprite will be updated to that reel's current frame

reelID

the ID to switch to

public Reel .reel()
[Returns]

The id of the current reel

A method to handle animation reels. Only works for sprites built with the Crafty.sprite methods. See the Tween component for animation of 2D properties.

To setup an animation reel, pass the name of the reel (used to identify the reel later), and either an array of absolute sprite positions or the start x on the sprite map, the y on the sprite map and then the end x on the sprite map.

Example

// Define a sprite-map component
Crafty.sprite(16, "images/sprite.png", {
    PlayerSprite: [0,0],
    PlayerIdle1: [0,1],
    PlayerLeftFootForward: [1,1],
    PlayerIdle2: [2,1],
    PlayerRightFootForward: [3,1]
});

// Define an animation on the second row of the sprite map (fromY = 1)
// from the left most sprite (fromX = 0) to the fourth sprite
// on that row (frameCount = 4), with a duration of 1 second
Crafty.e("2D, DOM, SpriteAnimation, PlayerSprite").reel('PlayerRunning', 1000, 0, 1, 4);

// This is the same animation definition, but using the alternative method
Crafty.e("2D, DOM, SpriteAnimation, PlayerSprite").reel('PlayerRunning', 1000, [[0, 1], [1, 1], [2, 1], [3, 1]]);

// This is the same animation definition, but uses sprite names instead of numbers
Crafty.e("2D, DOM, SpriteAnimation, PlayerSprite")
      .reel('PlayerRunning', 1000, ['PlayerIdle1', 'PlayerLeftFootForward', 'PlayerIdle2', 'PlayerRightFootForward']);
Back to top

.reelFrame()

public this .reelFrame(String frameName)

Sets the position of the current reel by frame name.

frameName

Name in the sprite map.

Jumps to specifed frame if the reel was created with sprite names.

Back to top

.reelPosition()

public this .reelPosition(Integer position)

Sets the position of the current reel by frame number.

position

the frame to jump to. This is zero-indexed. A negative values counts back from the last frame.

public this .reelPosition(Number position)

Sets the position of the current reel by percent progress.

position

a non-integer number between 0 and 1

public this .reelPosition(String position)

Jumps to the specified position. The only currently accepted value is "end", which will jump to the end of the reel.

public Number .reelPosition()
[Returns]

The current frame number

Back to top

.resetAnimation()

public this .resetAnimation()

Resets the current animation to its initial state. Resets the number of loops to the last specified value, which defaults to 1.

Neither pauses nor resumes the current animation.

Back to top

.resumeAnimation()

public this .resumeAnimation()

This will resume animation of the current reel from its current state. If a reel is already playing, or there is no current reel, there will be no effect.