KKTilemap Class Reference
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.
Tasks
Map Properties
-
size
property -
gridSize
property -
largestTileSize
property -
properties
property -
orientation
property -
backgroundColor
property -
highestGid
property
Scaling
-
iPadScaleFactor
property -
scaleTilesetSpacingAndMargin
property -
– applyIpadScaleFactor
Creating a Tilemap
Writing a Tilemap
Working with tilesets
-
tilesets
property -
– addTileset:
-
– tilesetForGid:
-
– tilesetForGidWithoutFlags:
-
– tilesetNamed:
-
– replaceTileset:withTileset:
-
– restoreTileset:
Working with Layers
-
layers
property -
– addLayer:
-
– layerNamed:
-
modified
property
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
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.
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