Inherits from NSObject
Declared in KKTilemap.h

Overview

Represents a TMX Tilemap “map”, ie global properties. The tilemap is usually created from a TMX file via the parseTMXFile method.

Properties

backgroundColor

The tilemap’s background color. Seen only if there are empty tiles on all layers. Defaults to black.

@property (atomic) SKColor *backgroundColor

Return Value

The background color.

Discussion

TILED-EDITABLE

Declared In

KKTilemap.h

gridSize

The size of tiles. Can be set in Tiled when a new tilemap is created. In the New Map dialog the gridSize is referred to as “Tile Size”.

@property (atomic) CGSize gridSize

Return Value

The size of the grid (tiles) in points.

Declared In

KKTilemap.h

highestGid

The highest valid gid from all tilesets. Updated when tilesets load their textures. Equal to the lastGid property of the “last” tileset. Mainly needed for bounds checks, don’t change this value.

@property (atomic) gid_t highestGid

Return Value

The highest-numbered (theoretical) gid considering all tilesets.

Declared In

KKTilemap.h

iPadScaleFactor

By how much to scale the tilemap if the app is running on an iPad device. Defaults to 1.0f (no scaling, ie iPad displays larger portion of the map). Recommended value: 2.0f.

@property (atomic) float iPadScaleFactor

Return Value

The iPad scale factor.

Discussion

Caution: Some combination of values and scale factor may cause inaccuracies, and possibly visual glitches. For example a scale factor of 1.5 and a odd-numbered tile size of 25x25 would make the upscaled tilesize 37.5x37.5 - but tile sizes should remain integer values this will affect tile positions and subsequently may introduce issues (this has not been tested, and is not recommended - tile sizes really should remain integer values).

Notes on what this does and what is required to make it work:

  • The -ipad and -ipadhd tileset image’s width & height must be scaled accordingly. For example by factor of 2.0f for a scaleFactor of 2.0f.
  • Tileset images' spacing and margin properties must also be scaled accordingly if scaleTilesetSpacingAndMargin is set to YES. See its description for when to use it.

TILED-EDITABLE

Declared In

KKTilemap.h

largestTileSize

This is the tileSize of the tileset with the largest tile size. Will be the same as gridSize for tilemaps whose tilesets all use the same tile size. But if you use tilesets of different tile sizes (ie 32x32 and 128x128) this will be the largest (ie 128x128). Mainly used internally to make sure tiles of all sizes properly appear on the screen and do not “pop in/out” near the screen borders. Valid only after tilesets have loaded their textures.

@property (atomic) CGSize largestTileSize

Return Value

The largest tile size found in the tilesets used by this tilemap.

Declared In

KKTilemap.h

layers

List of layers (KKTilemapLayer) used by this map, in the draw order respectively the reverse order they appear in Tiled’s Layers list (bottom-most = first, top-most = last).

@property (atomic, readonly) NSArray *layers

Return Value

An array of KTTilemapLayer objects.

Declared In

KKTilemap.h

modified

Is set whenever the tilemap changes in a way that requires an immediate redraw in the current frame (tile gid change or tilesets swapped). The modified state is reset automatically by the renderer. You don’t normally need to modify it yourself.

@property (atomic) BOOL modified

Declared In

KKTilemap.h

orientation

The orientiation (type) of tilemap.

@property (atomic) KKTilemapOrientation orientation

Return Value

The map’s KKTilemapOrientation.

Declared In

KKTilemap.h

properties

The map’s global properties. Editable in Tiled from the menu: Map -> Map Properties.

@property (atomic, readonly) KKTilemapProperties *properties

Return Value

The dictionary of properties.

Declared In

KKTilemap.h

scaleTilesetSpacingAndMargin

If set to YES, will also scale each tileset’s spacing & margin properties. This can be used if you simply upscale an iPhone tileset with an image program, which will also increase any existing spacing & margin accordingly. If you use a texture atlas program, it usually generates the same spacing and margin for all texture atlas files regardless of the contained image’s scale factor. Defaults to NO (ie for use with a texture atlas program). Can be ignored for texture atlases which have neither spacing between tiles nor margin between outermost tiles and texture border.

@property (atomic) BOOL scaleTilesetSpacingAndMargin

Return Value

Whether to also scale up spacing and margin if iPadScaleFactor is > 1.0.

Discussion

TILED-EDITABLE

Declared In

KKTilemap.h

size

The size of the map, in tiles.

@property (atomic) CGSize size

Return Value

The size of the map, in tiles.

Declared In

KKTilemap.h

tilesets

List of tilesets (KKTilemapTileset) used by this map.

@property (atomic, readonly) NSArray *tilesets

Return Value

An array of KTTilemapTileset objects.

Declared In

KKTilemap.h

Class Methods

tilemapWithContentsOfFile:

Parse and create a KKTilemap from a file. The file must be in TMX format.

+ (id)tilemapWithContentsOfFile:(NSString *)tmxFile

Parameters

tmxFile

The name of a TMX file in the bundle, or an absolute path to a TMX file in a non-bundle directory.

Return Value

A new instance of KTTilemap initialized with the contents of the TMX file.

Declared In

KKTilemap.h

tilemapWithOrientation:mapSize:gridSize:

Creates an empty tilemap. Use this if you want to create your tilemap world entirely in code.

+ (id)tilemapWithOrientation:(KKTilemapOrientation)orientation mapSize:(CGSize)mapSize gridSize:(CGSize)gridSize

Parameters

orientation

The orientation (type) of tilemap.

mapSize

The size of the tilemap, in tiles.

gridSize

The grid size (tile size) of the tilemap.

Return Value

A new, empty instance of KTTilemap.

Declared In

KKTilemap.h

Instance Methods

addLayer:

Adds a layer to the list of layers.

- (void)addLayer:(KKTilemapLayer *)layer

Parameters

layer

The layer to add.

Declared In

KKTilemap.h

addTileset:

Adds a tileset to the list of tilesets. Only needed when creating or changing a tilemap at runtime.

- (void)addTileset:(KKTilemapTileset *)tileset

Parameters

tileset

The tileset to add to the tilemap.

Declared In

KKTilemap.h

applyIpadScaleFactor

Applies the iPadScaleFactor property. You only need to call this if you’re creating a tilemap from scratch at runtime, after your map was completely set up. And only if you actually use iPadScaleFactor other than the default.

- (void)applyIpadScaleFactor

Declared In

KKTilemap.h

layerNamed:

The name identifying a layer, as edited in Tiled.

- (KKTilemapLayer *)layerNamed:(NSString *)name

Parameters

name

The name identifying a layer, as edited in Tiled.

Return Value

The first layer with the given name, or nil if there’s no layer with that name. Layer names are case-sensitive!

Declared In

KKTilemap.h

replaceTileset:withTileset:

Replaces a tileset with another (actually: it creates an alias) so that tiles drawn with the originalTileset will now be drawn using the otherTileset. This can be used to change the atmosphere of the tilemap, perhaps by changing from summer to winter, from “before attack” to “after attack”, and so on.

- (void)replaceTileset:(KKTilemapTileset *)originalTileset withTileset:(KKTilemapTileset *)otherTileset

Parameters

originalTileset

The tileset you want to replace.

otherTileset

The tileset you want to replace it with.

Discussion

@warning: Both tilesets need to be compatible (ie same tile size) and the otherTileset should have the same number of tiles in the same place as the originalTileset to prevent rendering issues (ie empty tiles, wrong tiles, crashes at the worst).

Declared In

KKTilemap.h

restoreTileset:

If tileset was replaced with replaceTileset: method, will restore it so that tiles will be drawn from this tileset again.

- (void)restoreTileset:(KKTilemapTileset *)originalTileset

Parameters

originalTileset

The tileset to restore.

Declared In

KKTilemap.h

tilesetForGid:

Returns the tileset for a specific gid. Mainly to access that tile’s properties. Will return nil for invalid gids (gid that points to a non-existing tileset, or if gid is 0).

- (KKTilemapTileset *)tilesetForGid:(gid_t)gid

Parameters

gid

The GID of a tile.

Return Value

The tileset the gid is part of, or nil if the GID is out of bounds.

Declared In

KKTilemap.h

tilesetForGidWithoutFlags:

Returns the tileset for a specific gid without flags. Mainly to access that tile’s properties. Will return nil for invalid gids (gid that points to a non-existing tileset, or if gid is 0).

- (KKTilemapTileset *)tilesetForGidWithoutFlags:(gid_t)gidWithoutFlags

Parameters

gid

The GID of a tile. Must not have any flags set.

Return Value

The tileset the gid is part of, or nil if the GID is out of bounds.

Declared In

KKTilemap.h

tilesetNamed:

The name of a tileset as displayed in Tiled.

- (KKTilemapTileset *)tilesetNamed:(NSString *)name

Parameters

name

The name of a tileset as displayed in Tiled.

Return Value

the tileset with the given name. Returns nil if there’s no tileset with this name.

Declared In

KKTilemap.h

writeToFile:

Writes the tilemap to a file path. The resulting file will be in TMX format.

- (void)writeToFile:(NSString *)path

Parameters

path

An absolute path to a file in a writable directory (ie AppData or Documents).

Declared In

KKTilemap.h