2.5. Working with Tile Animations Document

Previous: Working with Objects - Next: Working with TilesetsReturn to Index


Tile Animations are used to display a sequence of tiles on a tile layer. Each animation is represented by a TKTileAnimation instance, which contains one or more TKTileAnimationFrame instances.

The TKTileLayer class also contains methods for playing (and removing) tile animations at a specific coordinate. While the TKMap class contains methods to obtain global tile animations by tile GID or name.

Global vs Coord Tile Animations

There are two types of tile animations: global and coord based.

All tile animations start out as global animations. By default they play automatically when the map is loaded, and repeat indefinitely. All animations of the same type are synchronized, meaning they will all display the same tile and change frames at the same time.

To play a coord-based animation, you’ll use the play animation methods in TKTileLayer, providing a global animation as reference. The global animation is copied, and associated with a specific coordinate on the layer. This allows such coord-based animations to play independently of any other tile animation.

Editing Tile Animations

Open a TMX map in Tiled. Select the tile in the tileset that you want the tile animation to be associated with - normally this will be the animation’s first frame.

Choose View -> Tile Animation Editor from the menu. This will open the Tile Animation Editor window:

Start dragging tiles from the tileset on the right onto the frames list (upper left). By default, animation frames have a delay of 100 (milliseconds, ms). To change the delay, simply double-click the entry.

A fully edited animation with 5 frames can be seen below:

Now close the window. You’ll notice that in the tileset, the tile you had selected before opening the Tile Animation Editor window now has a filmstrip icon on top of it:

Now whereever you place this tile on a tile layer, it will automatically play a global animation at this coordinate.

Limitations of Tile Animations

You can only create an animation with the tiles of a single tileset. You can’t use tiles from other tileset images, and you can’t use individual images not in a tileset.

Both global and coord-based tile animations share the same animation frames. Whenever you need variants of the same animation you’ll need to add the necessary variants in Tiled.

Accessing Global Tile Animations

The TKMap instance stores all global tile animationed contained in the TMX format.

You can add or replace an existing tile animation by creating a TKTileAnimation instance and at a minimum setting its tile property. Then call:

TKTileAnimation* animation = [TKTileAnimation new];
animation.tile = 123;
[map addTileAnimation:animation];

// Swift
let animation = TKTileAnimation()
animation.tile = 123
map.addTileAnimation(animation)

This will store the tile animation for its Tile GID. If there was a previously assigned tile animation with this tile GID, the new animation will replace the existing one.

To access this tile animation:

TKTileAnimation* animation = [map tileAnimationForTile:123];

// Swift
let animation = map.tileAnimationForTile(123)

If the tile GID has properties, and there’s a property named anim.name with a non-empty string, then you can also access the animation by its name (recommended since tile GIDs can change):

TKTileAnimation* animation = [map tileAnimationNamed:@"trapdoor"];

// Swift
let animation = map.tileAnimationForTile("trapdoor")

Coord-Based Tile Animations

A TKTileLayer stores the coord-based instances of tile animations. These are animations that run at a specific coordinate with their own animation state, meaning they play independently of any other tile animation.

To play a tile animation at a given coordinate, you would first get a global TKTileAnimation from TKMap and then call:

TKTileAnimation* animation = [map tileAnimationNamed:@"trapdoor"];
TKTileAnimation* newAnim = [tileLayer playTileAnimation:animation atCoord:TKPointMake(12, 37)];
newAnim.repeatCount = 0;

// Swift    
let animation = map.tileAnimationNamed("trapdoor")
let newAnim = tileLayer.playTileAnimation(animation, atCoord:TKPoint(12, 37))
newAnim.repeatCount = 0

This will create a copy of the tile animation named “trapdoor” and play it once, with other animation parameters identical to the global animation’s parameters. If you need to tweak the parameters, for instance reversing the animation or changing its speed, you simply take the returned animation (the copy) and change its properties as needed.

If there’s already an existing animation playing at this coordinate, it will be replaced.

Coord-based animations remain in memory and associated with their coordinate until removed. This makes it easier to play infrequent, event-based tile animations at a given coordinate, such as doors.

To access an existing coord-based animation, you call:

TKTileAnimation* animation = [tileLayer tileAnimationAtCoord:TKPointMake(12, 37)];

// Swift
let animation = tileLayer.tileAnimationAtCoord(TKPoint(12, 37))

This will return the tile animation at the given coordinate, whether it is still playing or not. It will return nil if there’s no animation for this coordinate.

To finally remove an animation and optionally keeping its currently displayed tile animation frame, you call:

TKPoint coord = TKPointMake(12, 37);
[tileLayer removeTileAnimationAtCoord:coord keepFrame:NO];

// Swift
let coord = TKPoint(12, 37)
tileLayer.removeTileAnimationAtCoord(coord, keepFrame:false)

Not keeping the current tile animation frame will instantly restore the tile animation’s original tile at the coordinate, ie the tile the animation is associated with.


Previous: Working with Objects - Next: Working with TilesetsReturn to Index