TKTileset Class Reference

Inherits from NSObject
Conforms to TKImageOwner
TKPropertiesOwner
Declared in TKTileset.h

Overview

Represents an image from which tiles are drawn. Also holds terrain and tile collision data.

Tilesets refer to their data by “local” tile, which is a 0-based index into the tileset image. In Tiled, you can see this tileset-local GID by selecting a tile on the tileset, then look at the Tile properties where the property named “ID” tells you the tileset-local GID of the selected tile.

To convert a global tile GID to a local GID, use the convertToLocalTile: method. It removes the tile’s flags (if any) and then subtracts the firstTile property from the GID which results in a tileset-local tile GID.

Accessing the Tileset's Tilemap

  map

Reference to the tilemap the tileset is part of.

@property (readonly, weak, nullable) TKMap *map

Declared In

TKTileset.h

Identifying the Tileset

  name

The name of the tileset.

@property (copy, nonnull) NSString *name

Declared In

TKTileset.h

  firstTile

The first tile’s global GID in this tileset. It’s the global GID assigned to the top-left tile in the tileset. To convert a global GID to a tileset-local GID you would subtract firstTile from it: TKTileGID localGID = globalGID - tileset.firstTile;

@property TKTileGID firstTile

Declared In

TKTileset.h

  lastTile

The last tile’s global GID in this tileset. It’s the global GID assigned to the bottom-most, right-most tile in the tileset. Used to determin whether a certain global GID falls in the GID range of this tileset. If it does, the global GID is using this tileset’s texture.

@property (readonly) TKTileGID lastTile

Declared In

TKTileset.h

Image Properties

  imageFile

The image file and (relative) path of the (first) imageFile used by this tileset. When using “Collection of Images” for the tileset then refer to the imageFiles array.

@property (copy, nullable) NSString *imageFile

Declared In

TKTileset.h

  imageFiles

An array of image filenames and (relative) path used by this tileset. Normally only contains the one imageFile unless “Collection of Images” is used in Tiled. In that case for every local GID in the tileset there’s a corresponding imageFile in this array.

@property (readonly, nonnull) NSArray<NSString*> *imageFiles

Declared In

TKTileset.h

– addImageFile:

Adds an image file (with optional path) at the end of the imageFiles list. Adding an image also increases the lastTile property by one. That’s because the image file’s index is assumed to match the image file’s local GID.

- (void)addImageFile:(nonnull NSString *)imageFile

Parameters

imageFile

The image file & path string to add.

Declared In

TKTileset.h

  transparentColor

The color that’s supposed to be regarded as transparent in the image. Format is in 3-digit hex numbers, for example “ab99f0”.

@property (copy, nonnull) NSString *transparentColor

Declared In

TKTileset.h

  imageSize

The size of the image, in points.

@property TKSize imageSize

Discussion

Note: The image dimensions are determined by Tiled and will only reflect the tileset image used by Tiled, which is typically the standard-resolution (SD) image. The tileset’s image dimensions therefore remain the same even when providing high-resolution artwork and running the app on a high-resolution device.

Declared In

TKTileset.h

  spacing

How much space (in points) is between each tile in the tileset image. For example, if spacing equals 2 the tiles in the image are assumed to leave 2 points of empty (transparent) pixels to adjacent tiles in all directions.

@property NSInteger spacing

Declared In

TKTileset.h

  margin

The margin defines how much spacing (in points) there is from the image’s borders to the first and last tile row and column. Margin is the same for both horizontal and vertical borders. For example, a margin of 5 means there will be 5 points of empty space from the top, bottom, left and right before the first/last rows and columns of tiles.

@property NSInteger margin

Declared In

TKTileset.h

  tileCount

How many tiles total fit in this tileset’s image. The value takes the image’s dimensions, spacing and margin into account. This value equals tilesPerRow * tilesPerColumn and is provided for convenience.

@property (readonly) NSUInteger tileCount

Declared In

TKTileset.h

  isImageCollection

Is YES if the tileset is set up as “Collection of Images” in Tiled. In that case you’ll find the image file references in the imageFiles array. If NO, it’s a single tileset image assigned to the imageFile property.

@property (readonly) BOOL isImageCollection

Discussion

Note: To use isImageCollection tilesets correctly with Texture Atlases, the atlas' name must match the tileset’s name. For instance in SpriteKit the atlas images must be in the folder MyTileset.atlas if the tileset’s name is “MyTileset”.

Declared In

TKTileset.h

Working with Tiles

  tileSize

The size of tiles (in points).

@property TKSize tileSize

Declared In

TKTileset.h

  tileOffset

The offset of tiles (in points) determines how much tiles are shifted from their origin when drawn. Default: {0, 0}

@property TKPoint tileOffset

Declared In

TKTileset.h

– convertToLocalTile:

Converts a global tile GID to a tileset-local tile GID. In essence the conversion performs this: TKTileGID localTile = tile - firstTile;

- (TKTileGID)convertToLocalTile:(TKTileGID)tile

Parameters

tile

The global tile GID to be converted. The tile may have flags set.

Return Value

The local tile GID relative to this tileset’s firstTile property, or TKTileGIDInvalid (-1) if the tile could not be converted to a local tile (empty tile (0) or not within firstTile/lastTile range).

Declared In

TKTileset.h

– convertToTile:

Converts a local tile GID of the receiving tileset to a global tile GID. In essence the conversion performs this: TKTileGID tile = localTile + firstTile;

- (TKTileGID)convertToTile:(TKTileGID)localTile

Parameters

localTile

The local tile GID to be converted to a global GID. The tile may have flags set.

Return Value

The global tile GID.

Declared In

TKTileset.h

– textureRectForLocalTile:

Returns the texture rect (in points) within the tileset’s texture for the given tileset-local tile GID.

- (CGRect)textureRectForLocalTile:(TKTileGID)localTile

Parameters

localTile

The tileset-local tile GID to get the texture rect for.

Return Value

The tile’s texture rect.

Discussion

Warning: If the tile is not a valid tile of this tileset, the texture rect returned will be invalid and could lie outside the texture’s bounds.

Declared In

TKTileset.h

Working with Tileset and Tile Properties

  properties

The tileset’s TKProperties.

@property (nonnull) TKProperties *properties

Discussion

Note: These are properties for the tileset itself, not its tiles. For tile properties see [TKTileset tileProperties].

Declared In

TKTileset.h

  tileProperties

The TKProperties instances for tiles in the tileset. The keys are local TKTileGID values (as NSNumber).

@property (readonly, nonnull) NSDictionary<NSNumber*TKProperties*> *tileProperties

Declared In

TKTileset.h

– propertiesForLocalTile:

Obtains the properties for a given local tile in the tileset.

- (nullable TKProperties *)propertiesForLocalTile:(TKTileGID)localTile

Parameters

localTile

The tileset-local tile GID whose properties should be returned.

Return Value

The tile’s TKProperties, or nil if the tile does not have properties or the tile is invalid (ie empty tile, not a tile of this tileset, etc).

Declared In

TKTileset.h

– setProperties:forLocalTile:

Assigns properties to a specific local tile. If the tile already has properties the new properties will replace the existing ones (properties are not merged).

- (void)setProperties:(nonnull TKProperties *)properties forLocalTile:(TKTileGID)localTile

Parameters

properties

The TKProperties to assign to the tile.

localTile

The global tile GID to assign the properties to.

Discussion

Warning: If the tile is invalid or not part of this tileset the properties will still be set under this tile’s GID but those properties may be unobtainable.

Declared In

TKTileset.h

Working with Terrains

– addTerrain:

Adds a terrain to the tileset. The terrain must not already be added.

- (void)addTerrain:(nonnull TKTerrain *)terrain

Parameters

terrain

The TKTerrain to add.

Declared In

TKTileset.h

– removeTerrain:

Removes a terrain from the tileset.

- (void)removeTerrain:(nonnull TKTerrain *)terrain

Parameters

terrain

The terrain object to remove.

Declared In

TKTileset.h

– terrainNamed:

Obtains the first terrain found with a matching name.

- (nullable TKTerrain *)terrainNamed:(nonnull NSString *)name

Parameters

name

The name of the terrain to get.

Return Value

The first TKTerrain with a matching name, or nil if there’s no terrain with that name in this tileset.

Declared In

TKTileset.h

Working with Terrain Corners

– addTerrainCorners:forLocalTile:

Adds terrain corners to a given tile.

- (void)addTerrainCorners:(nonnull TKTerrainCorners *)corners forLocalTile:(TKTileGID)localTile

Parameters

corners

The TKTerrainCorners instance to add.

localTile

The tileset-local tile GID to assign the terrain corners to.

Declared In

TKTileset.h

– removeTerrainCornersForLocalTile:

Removes terrain corners from a given tile.

- (void)removeTerrainCornersForLocalTile:(TKTileGID)localTile

Parameters

localTile

The local tile GID to remove the TKTerrainCorners from.

Declared In

TKTileset.h

– terrainCornersForLocalTile:

Obtains terrain corners of a given tile.

- (nullable TKTerrainCorners *)terrainCornersForLocalTile:(TKTileGID)localTile

Parameters

localTile

The tileset-local tile GID to get the terrain corners for.

Return Value

The TKTerrainCorners for the tile, or nil if that tile has no terrain corners.

Declared In

TKTileset.h

Working with Tile Collision Layers

– addCollisionLayer:forLocalTile:

Adds a collision (object) layer to a given tile. The objects on the layer represent the tile’s collision shapes.

- (void)addCollisionLayer:(nonnull TKObjectLayer *)layer forLocalTile:(TKTileGID)localTile

Parameters

layer

The object layer to add.

localTile

The tileset-local tile GID to add the collision (object) layer to.

Declared In

TKTileset.h

– removeCollisionLayerForLocalTile:

Removes a collision (object) layer from a given tile.

- (void)removeCollisionLayerForLocalTile:(TKTileGID)localTile

Parameters

localTile

The tileset-local tile GID to remove the collision (object) layer from.

Declared In

TKTileset.h

– collisionLayerForLocalTile:

Obtains a collision (object) layer for a given tile.

- (nullable TKObjectLayer *)collisionLayerForLocalTile:(TKTileGID)localTile

Parameters

localTile

The tileset-local tile GID for which to get the collision (object) layer.

Return Value

The tile’s collision (object) layer, or nil if the tile has no collision layer.

Declared In

TKTileset.h