TKTileLayer Class Reference

Inherits from TKLayer : NSObject
Declared in TKTileLayer.h

Overview

Represents a tile layer in a tilemap.

Creating a Tile Layer

+ tileLayerWithTiles:size:

Creates and initializes a tile layer. Takes an already allocated tile GID buffer and takes ownership for it. The buffer length (in bytes) is assumed to be: layer.width * layer.height * sizeof(TKTileGID)

+ (nonnull instancetype)tileLayerWithTiles:(nonnull TKTileGID *)tiles size:(TKSize)size

Parameters

tiles

A pointer to a tile buffer containing tile GIDs.

size

The size of the tile layer, in grid coordinates.

Return Value

A new instance of TKTileLayer.

Discussion

Warning: You must not free() the tiles buffer, it will be freed automatically when the TKTileLayer instance deallocates.

Declared In

TKTileLayer.h

– initWithTiles:size:

Initializes a tile layer. Takes an already allocated tile GID buffer and takes ownership for it. The buffer length (in bytes) is assumed to be: layer.width * layer.height * sizeof(TKTileGID)

- (nonnull instancetype)initWithTiles:(nonnull TKTileGID *)tiles size:(TKSize)size

Parameters

tiles

A pointer to a tile buffer containing tile GIDs.

size

The size of the tile layer, in grid coordinates.

Return Value

A new instance of TKTileLayer.

Discussion

Warning: You must not free() the tiles buffer, it will be freed automatically when the TKTileLayer instance deallocates.

Declared In

TKTileLayer.h

Layer Dimensions

  size

The layer’s size, in grid coordinates. Usually identical to the [TKMap size] property.

@property (readonly) TKSize size

Return Value

The size of the tile layer, in grid coordinates.

Declared In

TKTileLayer.h

  bounds

Layer bounds is a rect (in points) with origin {0, 0} and size {widthtileWidth, heighttileHeight}.

@property (readonly) CGRect bounds

Declared In

TKTileLayer.h

  innerBounds

The layer’s inner bounds (in points) is the largest area that is guaranteed to encompass only tiles and not transparent (non-tile) areas.

@property (readonly) CGRect innerBounds

Discussion

For isometric and hexagonal maps the map borders aren’t straight lines since tiles are “staggered” along both axis, this leaves every other tile half-empty so to speak. The inner bounds tells you how much to move inwards onto the layer to see only tiles and no transparent areas when rendering or scrolling.

Note: This property returns bounds for orthogonal and regular (non-staggered) isometric maps.

Declared In

TKTileLayer.h

– boundsForLayerSize:

The smallest map bounds CGRect that includes all tiles of the given tile dimensions. Essentially this converts grid coordinate size into a points CGRect.

- (CGRect)boundsForLayerSize:(TKSize)size

Parameters

size

The size in grid coordinates.

Return Value

A bounds rect in points.

Declared In

TKTileLayer.h

– innerBoundsForLayerSize:

The smallest inner map bounds CGRect that includes all tiles of the given tile dimensions. Essentially this converts grid coordinate size into a points CGRect, but taking into account that for isometric and hexagonal maps the bounds rect must be larger since this method’s intention is to return a bounds rect large enough so that there aren’t any “holes” (partially empty tiles) in the sized area.

- (CGRect)innerBoundsForLayerSize:(TKSize)size

Parameters

size

The size in grid coordinates.

Return Value

A bounds rect in points.

Declared In

TKTileLayer.h

Working with Tile GIDs (ignoring flags)

– tileAt:

Returns the tile GID at the given grid coordinate. Any TKTileFlag the tile might have set are already masked out (removed).

- (TKTileGID)tileAt:(TKPoint)coord

Parameters

coord

A grid coordinate.

Return Value

The tile GID (without flags) at the given grid coordinate, or TKTileGIDInvalid (-1) if the coordinates are out of bounds.

Declared In

TKTileLayer.h

– setTile:at:

Sets a tile GID at the given grid coordinate while leaving the tile’s TKTileFlag (if any) unmodified. A tile GID of TKTileGIDEmpty (0) will remove the tile.

- (void)setTile:(TKTileGID)tile at:(TKPoint)coord

Parameters

tile

The tile GID to set. Must be a valid tile GID. Any TKTileFlag flags that are set will be ignored.

coord

A grid coordinate.

Discussion

Note: If the grid coordinates are out of bounds the command is ignored.

Declared In

TKTileLayer.h

– removeTileAt:

Clears a tile at the given grid coordinate. Same as calling: setTile:TKTileGIDEmpty x:y:

- (void)removeTileAt:(TKPoint)coord

Parameters

coord

A grid coordinate.

Discussion

Note: If the grid coordinates are out of bounds the command is ignored.

Declared In

TKTileLayer.h

Working with Tile GIDs including flags

– tileWithFlagsAt:

Returns the tile GID at the given grid coordinate. The tile GID may have TKTileFlag flags set. To mask out (remove) the flags do: TKTileGID tileWithoutFlags = (tile & TKTileFlagMask);

- (TKTileGID)tileWithFlagsAt:(TKPoint)coord

Parameters

coord

A grid coordinate.

Return Value

The tile GID with flags (if any) at the given grid coordinate, or TKTileGIDInvalid (-1) if the coordinates are out of bounds.

Declared In

TKTileLayer.h

– setTileWithFlags:at:

Sets a tile GID including its TKTileFlag at the given grid coordinate. A tile GID of TKTileGIDEmpty (0) will remove the tile.

- (void)setTileWithFlags:(TKTileGID)tile at:(TKPoint)coord

Parameters

tile

The tile GID (with optional flags) to set. Must be a valid tile GID.

coord

A grid coordinate.

Discussion

Note: If the grid coordinates are out of bounds the command is ignored.

Declared In

TKTileLayer.h

Working with Tile Flags

– tileFlagsAt:

Returns the tile’s TKTileFlag at the given grid coordinate.

- (TKTileFlag)tileFlagsAt:(TKPoint)coord

Parameters

coord

A grid coordinate.

Return Value

The flags (if any) at the given grid coordinate. Returns 0 (no flags set) for coordinates that are out of bounds.

Declared In

TKTileLayer.h

– setTileFlags:at:

Sets a tile’s TKTileFlag at the given grid coordinate, while preserving the tile’s GID.

- (void)setTileFlags:(TKTileFlag)flags at:(TKPoint)coord

Parameters

flags

The TKTileFlag to set.

coord

A grid coordinate.

Discussion

Note: If the grid coordinates are out of bounds the command is ignored.

Declared In

TKTileLayer.h

– clearTileFlagsAt:

Clears a tile’s TKTileFlag at the given grid coordinate. Same as calling: setTileFlags:0 x:y:

- (void)clearTileFlagsAt:(TKPoint)coord

Parameters

coord

A grid coordinate.

Discussion

Note: If the grid coordinates are out of bounds the command is ignored.

Declared In

TKTileLayer.h

Converting Coordinates

– convertToGridCoordinate:

Convert point to grid coordinates. Used for “picking” tiles. To use screen points, convert them to the layer’s coordinate space first, so that the point is relative to the layer’s origin.

- (TKPoint)convertToGridCoordinate:(CGPoint)point

Parameters

point

A point in layer’s coordinate system (relative to layer’s origin).

Return Value

The point converted to grid coordinates.

Declared In

TKTileLayer.h

– convertToPoint:

Convert grid coordinate to point in layer’s coordinate system. The returned point is the lower-left corner of the tile (tile origin), relative to the layer’s origin.

- (CGPoint)convertToPoint:(TKPoint)coord

Parameters

coord

A grid coordinate.

Return Value

The converted point in the layer’s coordinate system, ie relative to the layer’s origin.

Declared In

TKTileLayer.h

– convertToPoint:offset:

Convert grid coordinate to point in layer’s coordinate system. The point offset enables you to get the tile’s 4 corners, its center, and for hexagon and iso tiles their vertices as point coordinates relative to the layer’s origin.

- (CGPoint)convertToPoint:(TKPoint)coord offset:(TKTileOffset)offsetType

Parameters

coord

A grid coordinate.

offsetType

One of the TKTileOffset enums that determines which point offset to apply.

Return Value

The grid coordinate converted to a point relative to layer’s origin, with added offset to the desired location within the tile.

Declared In

TKTileLayer.h

– pointOffsetFor:

Returns the offset in points for a given location within a tile, ie the corners, the center, one of the 6 hexagon vertices or one of the 4 rhombus edges. You can add the returned offset to a grid coordinate obtained through convertGridCoordinate: or simply use convertGridCoordinate:offset: to have this done for you.

- (CGPoint)pointOffsetFor:(TKTileOffset)offsetType

Parameters

offsetType

One of the TKTileOffset enums that determines which point offset to get.

Return Value

The desired location’s offset, in points relative to tile’s origin, ie in the range: {0 to tileWidth, 0 to tileHeight}.

Declared In

TKTileLayer.h

– createVerticesForTileAt:winding:

Returns the vertices of a tile, in point coordinates relative to the given tile coord. Winding can be specified as it makes a difference depending on the API being used (compare GKPolygonObstacle vs SKPhysicsBody bodyWithPoints:).

- (nonnull CGPoint *)createVerticesForTileAt:(TKPoint)coord winding:(TKVertexWinding)winding

Parameters

coord

The tile’s coordinates.

winding

One of the TKVertexWinding enums specifying either clockwise (eg for GKPolygonObstacle) or counter-clockwise (eg for SKPhysicsBody) point winding.

Return Value

A CGPoint memory buffer (array). It contains either 4 points (orthogonal or isometric maps) or 6 points (hexagonal maps).

Discussion

Warning: You take ownership of the buffer, meaning you will eventually have to call free() on the buffer!

Declared In

TKTileLayer.h

– neighborCoordAt:inDirection:

Returns the coordinate of a neighboring tile in the given cardinal direction.

- (TKPoint)neighborCoordAt:(TKPoint)coord inDirection:(TKCardinalDirection)direction

Parameters

coord

Get a neighbor relative to this coordinate.

direction

The TKCardinalDirection from the given tile coord.

Return Value

The neighbor tile coordinate in the given direction relative to the provided coordinate.

Discussion

While getting neighboring coordinates is trivial for orthogonal and regular isometric maps, it’s more complex for staggered maps (iso and hex) due to the fact that the neighboring coordinate may either change both x/y or may increase x or y by +- 2 coordinate points. This also depends on what coordinate you need a neighbor for and what the stagger settings are.

Declared In

TKTileLayer.h

Tile Animations

– playTileAnimation:atCoord:

Plays a tile animation at the given coordinate, copying an existing TKTileAnimation.

- (nullable TKTileAnimation *)playTileAnimation:(nonnull TKTileAnimation *)animation atCoord:(TKPoint)coord

Parameters

animation

A TKTileAnimation instance. This animation will be copied and the copy is returned.

coord

The coord (within map’s bounds) to play this animation at.

Return Value

A copy of the input TKTileAnimation instance, or nil if the coords are out of bounds.

Discussion

This method will create a copy of the reference animation (except for the frames, they are not copied). Thus “animations at coord” will play asynchronously, ie independent of all other animations. The tile GID (including flags) previously at the coordinate will be copied into the [TKTileAnimation tile] property.

The returned TKTileAnimation instance can be further modified to alter playback, for instance changing speed or playing backwards. The default behavior will call the play method and playback behavior depends on the passed-in animation’s settings.

Note: Coordinate-specific animations are not stored in the TMX file. You will need to play any coord-specific animation every time after loading a TMX. You need to be able to deduct this information from other data if you need to restore coord-specific animations and animation states.

Declared In

TKTileLayer.h

– tileAnimationAtCoord:

Returns the tile animation, if any, assigned to the given coordinate.

- (nullable TKTileAnimation *)tileAnimationAtCoord:(TKPoint)coord

Parameters

coord

The coordinate to get the tile animation from.

Return Value

The TKTileAnimation at this coordinate, or nil if there’s no tile animation associated with this coordinate.

Declared In

TKTileLayer.h

– removeTileAnimationAtCoord:keepFrame:

Removes a tile animation associated with the given coordinate. This will release the TKTileAnimation copy and free its memory. Optionally the currently displayed frame can be “kept”, ie set as regular tile at the coord. Otherwise removing the animation will reveal the original tile.

- (void)removeTileAnimationAtCoord:(TKPoint)coord keepFrame:(BOOL)keepFrame

Parameters

coord

The coord to remove an animation from.

keepFrame

If YES, the animation’s currently displayed frame (tile) will be set at the coord and thus “kept”. If NO, the original tile at this coordinate is restored, ie the tile in the tileset that the animation is associated with.

Discussion

This method does nothing if there’s no animation for this coordinate.

Declared In

TKTileLayer.h

GameplayKit Methods

– obstacleForTileAt:

Returns a GKPolygonObstacle instance representing the tile’s shape at the given coord. The vertices are in points.

- (nonnull GKPolygonObstacle *)obstacleForTileAt:(TKPoint)coord

Parameters

coord

The tile coord for which to get a polygon obstacle.

Return Value

A GKPolygonObstacle instance representing the given tile’s shape, in layer coordinates (origin in lower-left corner of layer/map).

Discussion

Note: The polygon forms the grid’s shape at that position. It does not account for tile size, which may be larger than the grid.

Declared In

TKLayer+GameplayKit.h