2. Getting Started - Overview Document

Previous: Installation Guide - Next: Quickstart GuideReturn to Index

TilemapKit is separated into model (ie TKMap) and view/node (ie TKMapNode) classes. The class hierarchy image below shows how the model classes all subclass NSObject whereas the view classes subclass from TKNode (SKNode or CCNode, depending on engine).

Click the image to view the up-to-date class hierarchy:

Model Classes

The TilemapKit model classes strictly do not depend on any rendering engine or view constructs. This is ensured by developing the model classes in a separate target that does not link with nor include any headers of either SpriteKit or Cocos2D.

The model classes essentially are what a physics engine is to a rendering engine: data with game logic, completely decoupled from anything view-related.

The class hierarchy of the main model classes looks as follows:

Whereas the object model (where you’ll find instances of which classes) looks quite different. It was carefully modelled to resemble the actual data structure of the TMX map format.

Each indentation level indicates “one or more instances accessible via the parent class” with (m-n) indicating how many instances of that class you’ll find. This is the object relationship diagram:


  • (0-n) = No instance or many.
  • (0-1) = No instance or one.
  • (1-n) = At least one instance, or many.

Note that each instance of TKProperties may in itself contain (0-n) keyed values, where keys are NSString objects and values are either NSNumber, if the properties value string is convertible to a number, or NSString objects.

The tiles array is special because it’s not wrapped in a class of its own but rather it’s a C memory buffer (array) of tile GIDs.

The TKMapReader and TKMapWriter classes are not part of the model. They are utility classes used to read/write a TKMap from/to a TMX file.

View (Node) Classes

In both SpriteKit and Cocos2D, nodes resemble the view classes and are used to build the view (scene) hierarchy. The TilemapKit node classes are tasked to render the map, and to give convenient access to the underlying model classes.

The node classes are only available if either TK_RENDERER_SPRITEKIT or TK_RENDERER_COCOS2D are defined at compile-time.

The class hierarchy of the TilemapKit node classes looks as follows:

And if you view it as an object model you’ll see how each node contains its corresponding model instance:

The TKLayer instance has customized accessors tileLayer, objectLayer and imageLayer depending on the tile of TKLayerNode.

Through the TKLayer and TKMap instances you get access to the entire TilemapKit model classes. Changes in the model will be picked up by the node classes (ie affects how the map is drawn).

By adding nodes as children of individual layers, the node inherits the corresponding layer’s draw order (zPosition/zOrder). Furthermore, the node’s position will be relative to the position of the layer, which helps a great deal when parallax scrolling as each layer’s nodes will automatically follow the layer’s movement.

You can also easily enumerate an object layer’s nodes (or the TKObjectLayer objects) to create custom nodes based on object type information or properties.

Previous: Installation Guide - Next: Quickstart GuideReturn to Index