TKTileAnimation Class Reference

Inherits from NSObject
Conforms to NSCopying
Declared in TKTileAnimation.h

Overview

Represents a tile animation for a specific tile GID or coord.

Global vs Coord Animations

By default, all animations start out as global. They are indexed by GID, and every tile using the animation plays the same animation from the same TKTileAnimation instance. This means global animations will be frame-synchronized, always showing the same frame and always changing frames at the same time.

The other type of animations is stored in a TKTileLayer instance, indexed by coord. You have to call [TKTileLayer playTileAnimationForTile:atCoord:] to create and play one of these coord-based tile animations. The coord-based TKTileAnimation instances are copied from a global TKTileAnimation but will share the same TKTileAnimationFrame array to keep memory usage reasonable. Each coordinate’s TKTileAnimation instance will be able to play independently of other animations.

Animation update rate

Tile animations are updated independent of framerate, meaning the animation speed will be the same at 60 or 10 fps.

However the animations will never skip frames. At a minimum each tile animation frame will be displayed for the duration of a single (render) frame. Depending on the frame durations of an animation a tile animation may therefore seem to slow down as the framerate drops, more so the lower the frame durations are. Meaning such a “low framerate animation slowdown” will first be noticable with animations that cycle very quickly through their frames.

Animation Timer Resolution is 16.66666 ms

In Tiled you specify an animation frame’s duration in milliseconds (ms). However in reality the animation duration is more coarse, as it is bound to frame updates. At most, a mobile device will render 60 frames per second. This means the time between two frames is at least 1/60 = 0.016666 seconds or 16.66666 ms.

Therefore, the “resolution” of animation durations is a multiple of 16.66666 ms. This means, whether you specify 17 ms or 32 ms as animation duration, the ingame playback will (most of the time) be the exact same speed for both 17 ms and 32 ms durations. Only if you choose 34 ms will the animation suddenly play noticably slower.

Hopefully this will prevent you from going nuts when you try to tweak certain animations' speeds to a millisecond level of accuracy - it’s simply not achievable/possible. ;)

Animation Duration Reference Chart

This chart assumes the game runs at an ideal 60 fps. It tells you which millisecond ranges are equivalent to how many frames.

Animation Playback Events

  frameChangeBlock

A TKTileAnimationFrameChange block that is executed every time the animation changes to a new frame. The frame property is already set to the next frame when the block runs.

@property (copy, nullable) TKTileAnimationFrameChange frameChangeBlock

Declared In

TKTileAnimation.h

  completionBlock

A TKTileAnimationCycleComplete block that is executed every time the animation starts over or ended.

@property (copy, nullable) TKTileAnimationCycleComplete completionBlock

Discussion

To determine whether the animation ended, check if the animation’s repeatCount is 0 and isPlaying is NO.

Declared In

TKTileAnimation.h

Animation Frames

  frames

The list of TKTileAnimationFrame instances the animation cycles through.

@property (readonly, nonnull) NSArray<TKTileAnimationFrame*> *frames

Discussion

Note: The frames are shared with all other animations associated with the same tile.

Declared In

TKTileAnimation.h

  duration

Total animation duration in seconds. That’s the duration of all TKTileAnimationFrame instances in the frames array added up.

@property (readonly) NSTimeInterval duration

Declared In

TKTileAnimation.h

  frameIndex

Current frame’s index into frames array. Useful to start animation at a specific or random frame.

@property NSUInteger frameIndex

Discussion

If the value is changed, it is ensured that the new index remains within bounds. Then the frame and frameExpires properties are updated.

Declared In

TKTileAnimation.h

  frame

The TKTileAnimationFrame instance that’s currently shown.

@property (readonly, weak, nullable) TKTileAnimationFrame *frame

Declared In

TKTileAnimation.h

Animation References

  tileLayer

If set, indicates that this animation runs on a specific coordinate of the given tile layer. The coord parameter will also be valid if tileLayer is set.

@property (weak, readonly, nullable) TKTileLayer *tileLayer

Declared In

TKTileAnimation.h

  coord

The tile coord this animation is associated with.

@property (readonly) TKPoint coord

Discussion

Note: Only valid for tileLayer animations. Will be {-1, -1} for synchronous (global) tile animations.

Declared In

TKTileAnimation.h

  tile

Global (map) animation: The tileset tile (global, without flags) this animation is associated with. Tile layer animation: The tile (global, with flags) that used to be at this coord before the animation playback began. Used to restore the previous tile after playing an animation.

@property (readonly) TKTileGID tile

Discussion

Note: This is not the animation’s current frame tile.

Declared In

TKTileAnimation.h

  name

The name of the tile animation. Defaults to empty string. Can be set by creating a tile property named anim.name.

@property (copy, nonnull) NSString *name

Declared In

TKTileAnimation.h

Animation Playback Behavior

  repeatCount

How many times the animation should repeat. The value is zero-based, meaning a repeatCount of zero will play the animation once, then stop.

@property NSInteger repeatCount

Discussion

After the end of each animation cycle, repeatCount is decreased by one. So in order to play the same animation multiple times with a repeatCount greater than 0 you’ll need to set repeatCount before each play, or use playWithRepeatCount:.

The default repeatCount of TKRepeatCountInfinite (-1) indicates that the animation will repeat indefinitely (it will loop).

Declared In

TKTileAnimation.h

  speed

Overall playback speed of the animation. Defaults to 1 (original speed as set in Tiled). Higher values will play the animation faster, values lower than 1.0 make animation play slower.

@property float speed

Discussion

Changing speed will recalculate frameExpires using the frame’s remaining time. This makes it possible to have a gradual animation speedup or slowdown over time.

Speed can never be 0 or negative, it will be set to FLT_EPSILON in that case to prevent potential division by zero. If you want to pause the animation use the paused property.

See Also

Declared In

TKTileAnimation.h

  frameExpires

If this is less than current time, the frameIndex increases/decreases (depending on playsBackwards). Can be modified to make the current frame remain longer or shorter. Specifically useful for randomized start delays.

@property NSTimeInterval frameExpires

Discussion

Note: If you are also changing frameIndex, be sure to change frameIndex first since doing so will update frameExpires which would void your previous changes to frameExpires.

Set it to 0 to make the animation change to the next frame instantly. Or set it to [NSDate timeIntervalSinceReferenceDate] + t where t is the desired frame duration in seconds.

Declared In

TKTileAnimation.h

  playsBackwards

If YES, the animation will play backwards. It’ll start at the last frame and will run to the first frame.

@property BOOL playsBackwards

Discussion

Changing this property will start the animation anew ie it will reset frameIndex to the first / last frames' index.

Declared In

TKTileAnimation.h

Play/Pause Animation

  isPlaying

Is YES while the animation is cycling through its frames. Is NO when the animation was stopped or ran to completion. Note: When paused the animation will not change its isPlaying state. A paused animation is technically still playing.

@property (readonly) BOOL isPlaying

Declared In

TKTileAnimation.h

  paused

If YES, the animation playback is paused, freezing the current frame and remaining frame duration. Once set back to NO, playback will resume at the given frame with the remaining frame duration.

@property BOOL paused

Declared In

TKTileAnimation.h

– play

Begins animation playback with current settings. Assuming default settings, this will play the animation forwards and loop it indefinitely.

- (void)play

Declared In

TKTileAnimation.h

– playOnce

Begins animation playback with current settings and repeatCount of 0.

- (void)playOnce

Declared In

TKTileAnimation.h

– playWithRepeatCount:

Begins animation playback with current settings and repeatCount. A repeatCount of zero will play the animation once.

- (void)playWithRepeatCount:(NSInteger)repeatCount

Parameters

repeatCount

How many times the animation should repeat (zero based). To play the animation once, use 0. See repeatCount property.

Declared In

TKTileAnimation.h

Stop/Remove Animation

– stop

Stops animation playback. Will replace the frame’s tile with the original tile.

- (void)stop

Discussion

If tileLayer is non-nil the animation is not removed from the coordinate, allowing it to be played again without requiring allocating and copying another animation.

Declared In

TKTileAnimation.h

– remove

Stops animation playback and removes the animation from the tile layer’s coordinate, allowing its memory to be freed.

- (void)remove

Discussion

This only has an effect if the animation was previously played at a specific coordinate, ie tileLayer property is not nil. Otherwise it has the same effect as calling stop.

Will restore the original tile after removal.

Declared In

TKTileAnimation.h

– removeAndKeepFrame

Stops animation playback and removes the animation from the tile layer’s coordinate, allowing its memory to be freed.

- (void)removeAndKeepFrame

Discussion

This only has an effect if the animation was previously played at a specific coordinate, ie tileLayer property is not nil. Otherwise it has the same effect as calling stop.

Will set the animation’s current frame tile at the coordinate.

Declared In

TKTileAnimation.h