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.
See Also
Properties
Methods
- .animate()
- .getReel()
- .isPlaying()
- .loops()
- .pauseAnimation()
- .reel()
- .reelFrame()
- .reelPosition()
- .resetAnimation()
- .resumeAnimation()
.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.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
undefinedif no such reel exists.
.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.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.
.pauseAnimation()
public this .pauseAnimation(void)Pauses the currently playing animation, or does nothing if no animation is playing.
.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
xposition on the sprite map (x's unit is the horizontal size of the sprite in the sprite map).
- fromY
yposition 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
xandyvalues 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']);.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.
.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
.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.
.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.
google groups
starwed@gmail.com
github