mfessenden / Sktiled

SKTiled is a framework for integrating Tiled assets with Apple's SpriteKit, built from the ground up with Swift. This project began life as an exercise to learn Apple's new programming language for a game project, but I've decided to release it as open source with the hopes that others will find it useful. SKTiled is up-to-date and supports Tiled's major features, including all map & object types.

Check out the Official Documentation.

Features

• [x] iOS & macOS versions
• [x] tvOS version
• [x] parses inline & external tilesets
• [x] translates custom properties for maps, layers, objects & tiles
• [x] renders all projections: (orthogonal, isometric, hexagonal & isometric staggered)
• [x] renders all layer types: (tile, object, image, group)
• [x] supports all compression types: (base64, zlib, gzip)
• [x] renders animated and flipped tiles
• [x] pre-loading of tilesets
• [x] group nodes
• [x] tile objects
• [x] text objects
• [x] template objects
• [x] custom tile & object classes
• [x] generate GKGridGraph graphs from custom attributes
• [x] user-definable cost properties for GKGridGraph nodes
• [ ] infinite maps
• [ ] tile collision objects
• [ ] Zstandard compression support

Requirements

• iOS 12
• tvOS 12
• macOS 10.12
• Xcode 11/Swift 5

Installation

Carthage & CocoaPods Support

For Carthage installation, create a Cartfile in the root of your project:

github "mfessenden/SKTiled" ~> 1.22

For CocoaPods, install via a reference in your podfile:

pod 'SKTiled', '~> 1.22'

Usage

Loading a tilemap is very straightforward:

if let tilemap = SKTilemap.load(tmxFile: "sample-map") {
    scene.addChild(tilemap)
}

Once loaded, the rendered SKTilemap node reflects the various properties defined in the originating scene:

• SKTilemap.size: size of the map in tiles.
• SKTilemap.tileSize: size of individual tiles.
• SKTilemap.orientation: map orientation (ie orthogonal, isometric, etc).

The SKTilemap node also gives users access to child layers, tilesets, objects or individual tiles.

Working with Layers

Layers represent containers that hold various types of data:

• tile layers hold an array of tile sprites and associated tileset data
• object groups contain vector shape objects
• image layers display a single image

All SKTiled layer types are subclasses of the base SKTiledLayerObject object and provide access to coordinate transformation and positioning information. Additionally, every layer type can have individual offset transforms and rendering flags.

Layers can be accessed by type, name or index:

// query layers by type
let tileLayers = tilemap.tileLayers
let objectGroups = tilemap.objectGroups
let imageLayers = tilemap.imageLayers
let groupLayers = tilemap.groupLayers

// query named layers
let groundLayers = tilemap.getLayers(named: "Ground") as! [SKTileLayer]
let objectGroups = tilemap.getLayers(named: "Objects") as! [SKObjectGroup]
let hudLayers = tilemap.getLayers(named: "HUD") as! [SKImageLayer]

// query layer at a specific index
if let firstLayer = tilemap.getLayer(atIndex: 1) as! SKTileLayer {
    firstLayer.visible = true
}

Working with Tiles

There are a number of ways to access and manipulate tile objects. Tiles can be queried from the SKTilemap node, or the parent SKTileLayer layer:

// access a tile via CGPoint
let tileCoord = CGPoint(x: 7, y: 12)
if let tile = groundLayer.tileAt(coord: tileCoord) {
    tile.tileData.tileOffset.x += 8
}

// access a tile with integer coordinates
if let tile = groundLayer.tileAt(7, 12) {
    tile.tileData.tileOffset.x += 8
}

// query tiles at a specific coordinate (all layers)
let tiles = tilemap.tilesAt(2, 4)

Tiles assigned custom properties in Tiled can be accessed in SKTiled:

// query tiles of a certain type
if let fireTiles = tilemap.getTiles(ofType: "fire") {
    // do something fiery here...
}

You can also return tiles with a specific ID value:

if let waterTiles = waterLayer.getTiles(globalID: 17) {
    // do something watery here...
}

Working with Objects

SKTileObject objects can be queried from both the SKTilemap and SKObjectGroup nodes:

let allObjects = tilemap.getObjects()
let allTreeObjects = tilemap.getObjects(named: "Tree")
let allCollisionObjects = tilemap.getObjects(ofType: "Collision")

// get objects from the objects group layer
let entrances = objectsLayer.getObjects(ofType: "Entrance")

Acessing Tile Data

The SKTilemap node stores an array of individual tilesets parsed from the original Tiled document. Individual tile data is accessible from either the SKTileset object:

let tileSet = tilemap.getTileset("spritesheet-16x16")
// get data for a specific id
let tileData = tileSet.getTileData(globalID: 177)

and the parent SKTilemap:

let tileData = tilemap.getTileData(globalID: 177)

Adding Nodes

Tile data includes texture data, and SKTile objects are SKSpriteNode subclasses that can be initialized with tileset data:

let newTile = SKTile(data: tileData)
scene.addChild(newTile)

Coordinate information is available from each layer via the SKTiledLayerObject.pointForCoordinate method:

let tilePoint = groundLayer.pointForCoordinate(4, 5)
tile.position = tilePoint

New nodes (any SKNode type) can be added directly to any layer. All SKTiledLayerObject layer types have expanded convenience methods for adding child nodes with coordinates and z-position.

let roadRoot = SKNode()
groundLayer.addChild(roadRoot, 4, 5, zpos: 100.0)

SKTiled also provides methods for getting coordinate data from UITouch and NSEvent mouse events:

// get the coordinate at the location of a touch event
let touchLocation: CGPoint = objectsLayer.coordinateAtTouchLocation(touch)

Animated Tiles

Tiles with animation will animate automatically when the tilemap node is added to the SKScene.update method. Animated tiles can be accesssed from the either the SKTilemap node or the parent layer.

// get all animated tiles, including nested layers
let allAnimated = tilemap.animatedTiles(recursive: true)

// pause/unpause tile animation
for tile in allAnimated {
    tile.isPaused = true
}

// run animation backwards
for tile in allAnimated {
    tile.speed = -1.0
}

// get animated tiles from individual layers
let layerAnimated = groundLayer.animatedTiles()

Custom Properties

Custom properties are supported on all object types. All SKTiled objects conform to the SKTiledObject protocol and allow access to and parsing of custom properties.

Any property added to an object in Tiled will be translated and stored in the SKTiledObject.properties dictionary.

let layerDepth = groundLayer.getValue(forProperty: "depth")
groundLayer.setValue(12.5, forProperty: "depth")

To query tiles of a given type:

let waterTiles = groundLayer.getTiles(ofType: "water")
let allWaterTiles = tilemap.getTiles(ofType: "water")

For specific property/value types:

let groundWalkable = groundLayer.getTilesWithProperty("walkable", true)
let allWalkable = tilemap.getTilesWithProperty("walkable", true")

Acknowledgments

• Thorbjørn Lindeijer: creator of Tiled
• GZipSwift: zlib decompression extensions
• Steffen Itterheim: Author of TilemapKit, the inspiration for this project
• Kenney Vleugels: demo spritesheet assets
• Amit Patel: tile-based game logic
• Clint Bellanger: Isometric Tiles Math