TKMapNode Class Reference

Inherits from TKNode
Declared in TKMapNode.h

Overview

Renders a tilemap and provides access to tilemap data.

Children

When added as child, the tilemap node generates TKTileLayerNode, TKObjectLayerNode and TKImageLayerNode instances in the order they appear in the [TKMap layers] list, and adds them as children to itself.

Note: The tilemap only allows subclasses of TKLayerNode as children. If you want to add nodes of your own, you will need to add them either to a specific child node (one of the layers) or to the tilemap node’s parent if the added node’s position should be independent of the tilemap’s and its layer’s positions.

Render Size

The node’s renderSize is used to allocate just enough space to fill the render area with tiles plus an additional row and column to allow for seamless scrolling of the tilemap.

Note: The tilemap does not clip its contents to the render size. You can draw a frame image around the tilemap’s borders to cover up any tiles seen sticking outside the renderSize bounds, or use a crop/clip node to cut off contents.

Coordinate System

The tilemap is drawn from the node’s position extending upwards and to the right (along positive X/Y).

Grid coordinates have their origin (0,0) in the upper-left corner. For non-staggered isometric tilemaps, the topmost tile represents the origin in grid coordinates.

Properties

Upon loading of a TKMapNode, the map, layer and object properties prefixed with “self.” are automatically assigned to instances of TKMapNode, TKLayerNode and to all nodes that represent a TKObject. Meaning: you can set these objects properties straight from Tiled by using properties like self.zPosition and assigning them a value of the correct (or convertible) type.

Creating a Tilemap Node

+ mapNodeWithContentsOfFile:

Creates and initializes a tilemap node with the given file (in TMX format).

+ (nonnull instancetype)mapNodeWithContentsOfFile:(nonnull NSString *)file

Parameters

file

File and (optional, relative to bundle) path to a file in tMX format.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

+ mapNodeWithContentsOfFile:renderSize:

Creates and initializes a tilemap node with the given file (in TMX format) and desired render size.

+ (nonnull instancetype)mapNodeWithContentsOfFile:(nonnull NSString *)file renderSize:(CGSize)size

Parameters

file

File and (optional, relative to bundle) path to a file in tMX format.

size

The desired render size.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

+ mapNodeWithContentsOfFile:renderSize:delegate:

Creates and initializes a tilemap node with an existing TKMap instance, desired render size and a TKMapNodeDelegate.

+ (nonnull instancetype)mapNodeWithContentsOfFile:(nonnull NSString *)file renderSize:(CGSize)size delegate:(nullable id<TKMapNodeDelegate>)delegate

Parameters

file

File and (optional, relative to bundle) path to a file in tMX format.

size

The desired render size.

delegate

An object implementing the TKMapNodeDelegate protocol.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

– initWithContentsOfFile:renderSize:delegate:

Initializes a tilemap node with the given file (in TMX format) and desired render size.

- (nonnull instancetype)initWithContentsOfFile:(nonnull NSString *)file renderSize:(CGSize)size delegate:(nullable id<TKMapNodeDelegate>)delegate

Parameters

file

File and (optional, relative to bundle) path to a file in tMX format.

size

The desired render size.

delegate

An object implementing the TKMapNodeDelegate protocol.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

+ mapNodeWithMap:

Creates and initializes a tilemap node with an existing TKMap instance.

+ (nonnull instancetype)mapNodeWithMap:(nonnull TKMap *)map

Parameters

map

An instance of TKMap.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

+ mapNodeWithMap:renderSize:

Creates and initializes a tilemap node with an existing TKMap instance and desired render size.

+ (nonnull instancetype)mapNodeWithMap:(nonnull TKMap *)map renderSize:(CGSize)size

Parameters

map

An instance of TKMap.

size

The desired render size.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

+ mapNodeWithMap:renderSize:delegate:

Creates and initializes a tilemap node with an existing TKMap instance, desired render size and a TKMapNodeDelegate.

+ (nonnull instancetype)mapNodeWithMap:(nonnull TKMap *)map renderSize:(CGSize)size delegate:(nullable id<TKMapNodeDelegate>)delegate

Parameters

map

An instance of TKMap.

size

The desired render size.

delegate

An object implementing the TKMapNodeDelegate protocol.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

– initWithMap:renderSize:delegate:

Creates and initializes a tilemap node with an existing TKMap instance and desired render size.

- (nonnull instancetype)initWithMap:(nonnull TKMap *)map renderSize:(CGSize)size delegate:(nullable id<TKMapNodeDelegate>)delegate

Parameters

map

An instance of TKMap.

size

The desired render size.

delegate

An object implementing the TKMapNodeDelegate protocol.

Return Value

The new tilemap node.

Declared In

TKMapNode.h

Accessing Map Model and Delegate

  map

The TKMap instance holding the tilemap’s data.

@property (readonly, nonnull) TKMap *map

Declared In

TKMapNode.h

  delegate

An object implementing the TKMapNodeDelegate protocol. The delegate is not retained (weak).

@property (weak, readonly, nullable) id<TKMapNodeDelegate> delegate

Declared In

TKMapNode.h

Accessing Layer Nodes

– layerNodeNamed:

Obtains a layer node by its name.

- (nullable TKLayerNode *)layerNodeNamed:(nonnull NSString *)name

Parameters

name

The name of a layer node.

Return Value

The TKLayerNode instance for the given name, or nil if there’s no layer with that name.

Declared In

TKMapNode.h

– tileLayerNodes

Obtains all tile layer nodes.

- (nonnull NSArray<TKTileLayerNode*> *)tileLayerNodes

Return Value

An array containing the tilemap’s TKTileLayerNode instances.

Declared In

TKMapNode.h

– objectLayerNodes

Obtains all object layer nodes.

- (nonnull NSArray<TKObjectLayerNode*> *)objectLayerNodes

Return Value

An array containing the tilemap’s TKObjectLayerNode instances.

Declared In

TKMapNode.h

– imageLayerNodes

Obtains all image layer nodes.

- (nonnull NSArray<TKImageLayerNode*> *)imageLayerNodes

Return Value

An array containing the tilemap’s TKImageLayerNode instances.

Declared In

TKMapNode.h

Render Settings

+ normalMapSuffix

Returns the current normal map suffix for tileset images. Defaults to empty string, which indicates that normal maps should not be used.

+ (nonnull NSString *)normalMapSuffix

Return Value

The normal map suffix used to lookup normal map tileset images.

Declared In

TKMapNode.h

+ setNormalMapSuffix:

Set the normal map suffix of tileset images. The default is an empty string, which indicates that normal maps should not be used.

+ (void)setNormalMapSuffix:(nonnull NSString *)suffix

Parameters

suffix

The new normal map suffix to look up normal map images.

Discussion

If you want to use normal-map enabled lighting you need to supply image files of the same name as the tileset image, plus this suffix. As long as the normalMapSuffix is an empty string, map nodes will not load normal textures.

For example, if the tileset is named “tileset.png” and normal map suffix is set to “-normal” your normal map image file must be named “tileset-normal.png”. Then TKMapNode will load the normal map image and use the resulting normal map texture to enable normal map lighting for all tiles of this tileset.

You would then set the normal map suffix like so:

[TKMapNode setNormalMapSuffix:@"-normal"];

// Swift
TKMapNode.setNormalMapSuffix("-normal")

Note: You must set the normal map suffix before initializing the first TKMapNode if you don’t intend to use the default suffix. It suffices (not: suffixes) to set the normal map suffix once during startup, as it is a static variable not tied to specific instances of TKMapNode.

Declared In

TKMapNode.h

  renderSize

The size of the visible area, in points. Only tiles within this area are drawn. If size is 0,0 the entire map is drawn, regardless of whether tiles are outside the screen area. Typically for a fullscreen tilemap you would pass in the view’s (scene’s) size.

@property (readonly) CGSize renderSize

Declared In

TKMapNode.h

  tileOverlap

Specifies the amount (in points) that tiles should overlap. This helps prevent visible seams from appearing when scaling the map. Value needs to be determined by experimentation, as it highly depends on the map, the tileset and its spacing/margin, the map’s background and possibly other factors. Start by experimenting with known good values like 0.1, 0.25, 0.5 or 1.0. You may go as high as you want but there’s probably no benefit going above 2.0 and going below 0.0 will simply make seams more visible.

@property CGFloat tileOverlap

Discussion

Note: If the map is scaled by a factor of two value (ie 2.0, 4.0, 8.0 but also 0.5, 0.25, 0.125) you should not notice visible seams.

Warning: Unless you notice visible seams on your map (specifically when scaling) you should leave this value at its default (0.0). If seams only appear temporarily (ie while scaling) it is best to enable tileOverlap only during the operation that can cause seams. The downside of using tileOverlap is that tiles will be stretched slightly, which may or may not introduce other (albeit hardly noticable) artifacts.

Declared In

TKMapNode.h

  textureFilteringEnabled

Whether texture (linear) filtering is enabled. Defaults to NO.

@property BOOL textureFilteringEnabled

Discussion

If set to YES, tilemap tiles will have a texture filtering applied to them which makes them look less pixelated / smoother. However in tilemaps texture filtering often makes the maps appear blurred or introduces artifacts that make the map’s grid stand out, hence texture filtering is off by default.

Declared In

TKMapNode.h

  multiThreadedRendering

Whether tile layers should be updated using a concurrent dispatch queue, effectively using all available CPU cores when updating tile layers. Defaults to YES.

@property BOOL multiThreadedRendering

Declared In

TKMapNode.h

Curing Line Artifacts

– clampPositionToNearestPixel

Clamps the position to the closest pixel coordinate. This fixes the commonly occuring “line flicker” artifacts (visible/flickering seams) between tiles. You should call this method post-update if you either set the position manually or run position-modifying actions on the tilemap node.

- (void)clampPositionToNearestPixel

Discussion

Note: For non-Retina devices the nearest pixel coordinate is the nearest integer coordinate. On Retina devices it’s any .5 point coordinate.

Declared In

TKMapNode.h

– clampPositionToNearestPixelRecursively

Clamps the position to the closest pixel coordinate for all nodes below and above the tilemap node in the scene hierarchy. Use this if a simple clampPositionToNearestPixel is not enough to fix the line artifacts.

- (void)clampPositionToNearestPixelRecursively

Declared In

TKMapNode.h

Drawing Debug Information

  debugDrawEnabled

Whether debug drawing is enabled. Defaults to NO. If set to YES, debugging info will be drawn over the map, such as the viewable area (defined by renderSize) and other debugging info.

@property BOOL debugDrawEnabled

Declared In

TKMapNode.h

  debugDrawOptions

Defines what kind of debug info is drawn. The debugDrawEnabled property must be set to YES for any of the debug drawings to be visible. See TKDebugDrawOptions for a list of options.

@property TKDebugDraw debugDrawOptions

Declared In

TKMapNode.h

DebugDraw Methods

– drawGraph:

Draws a graph and adds it to the TKMapNode’s parent at the same position, scale and rotation as the TKMapNode.

- (nonnull TKNode *)drawGraph:(nonnull GKGraph *)graph

Parameters

graph

The graph to draw.

Return Value

The container node containing the TKShapeNode instances used to draw the graph. Use this node if you need to tweak the graph further or need to provide additional detail.

Declared In

TKMapNode+DebugDraw.h