Creates SpriteKit game maps from TMX Map files.

PEMTileMap is a Swift package that generates SpriteKit game maps from TMX Map files. Maps, layers, tiles and objects are automatically rendered as SKNodes on the SKScene. TMX Map files can be created and edited with Tiled.

Based on the JSTileMap project which was famously used in Ray Wenderlichs SpriteKit SuperKoalio tutorial but no longer seems to be maintained. I hope to make a light-weight framework that supports iOS, macOS and tvOS.

I also made a Swift version of the SuperKoalio game, which uses PEMTileMap to generate the map and also supports iOS, macOS and tvOS.

TMX Features

Not (yet) supported

PEMTileMap Features

Swift code
Objective-C compatibility
iOS (>13.6), macOS (>10.15), tvOS (>13.4)
generate TMX maps as SKNode objects with child elements as SKNode subclasses (eg. a tile as a SKSpriteNode, a polygon object as an SKShapeNode, etc.)
both nearest neighbor and linear texture antialiasing
camera tilt and zoom
access layers, tiles, objects
parallax scroll
anti-tearing (removing tear lines between tiles)

Known issues

Please refer to the issue tracker on GitHub. All bugs reports, feature requests and comments are welcome.

Documentation

Check out the documentation on this page.

Installation

Swift package

In Xcode project settings, under "Package Dependencies" add the PEMTileMap repository.

URL: https://github.com/hotdogsoup-nl/PEMTileMap.git
Dependency rule: branch
Branch: master

Cocoapods & Carthage

These dependency managers are not supported and will not be supported in the future.

Usage

Loading the map

The tilemap should be loaded in your SKScene referring the map file name and the associated SKView.

  if let newMap = PEMTileMap(mapName: "superkoalio.tmx", view: skView!) {
    // center the map on the screen
    newMap.position = CGPoint(x: newMap.mapSizeInPoints().width * -0.5, y: newMap.mapSizeInPoints().height * -0.5)
    addChild(newMap)
  }

The map will now render and appear on the scene as an SKNode. It will contain child nodes for all TMX Map layers and groups which contain the tiles and other objects as children.

Accessing map functions

PEMTileMap has several public properties and functions that can be use to access map properties such as its orientation, highest used zPosition, map size (in tiles or in points) and for converting scene coordinates to map coordinates and vice versa. Check out the documentation.

Accessing layers, tiles, objects

PEMTileMap has several functions to access layers, tiles, and objects on the map. Check out the documentation.

Using a camera

You are responsible for creating and controlling the camera in your scene. PEMTileMap does however have basic moveCamera functions to move the camera around the map. Set the cameraNode property to point to your camera before calling moveCamera.

Use the background color

To set the background color of your SKScene to match the map background color:

    if newMap.backgroundColor != nil {
        backgroundColor = newMap.backgroundColor!
    }

Build the Demo app

Download the repository and open the PEMTileMap Xcode project. Build any of the iOS, macOS or tvOS targets. Depending on the platform choice, you may get a build error stating that a provisioning profile is required. In "Signing and Capabilities", make sure each target has either automatic signing enabled or select the correct provisioning profile.

If a build error occurs stating Resource fork, Finder information, or similar detritus not allowed there is an issue with image files in the project. Run sudo xattr -cr * on all image file folders in the project and clean the build folder to fix.