Skip to content
Swift framework for working with Tiled assets in SpriteKit
Swift Other
  1. Swift 99.7%
  2. Other 0.3%
Branch: master
Clone or download

Latest commit

mfessenden updated bundle, access levels
  - disable render/camera callbacks by default in demo
  - remove assets added to macOS framework target
  - fix delegate errors in parser tests
  - add `ColorTests` module
  - `SKTileObject.tile` access level is now public (get only)
  - `TileUpdateMode` access level is now public
  - add `SKTile.enableAnimation` flag
  - add `SKTileObject.enableAnimation` flag
Latest commit 155743f Jan 13, 2019

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Assets update project to fix travis errors Nov 26, 2018
Demo updated bundle, access levels Jan 13, 2019
SKTiled.xcodeproj updated bundle, access levels Jan 13, 2019
Sources updated bundle, access levels Jan 13, 2019
Tests updated bundle, access levels Jan 13, 2019
iOS updated bundle, access levels Jan 13, 2019
macOS updated bundle, access levels Jan 13, 2019
scripts Merge branch 'release/1.20' Nov 18, 2018
tvOS updated bundle, access levels Jan 13, 2019
.gitignore Merge branch 'release/1.20' Nov 18, 2018
.swift-version Merge branch 'release/1.20' Nov 18, 2018
.travis.yml update project to fix travis errors Nov 26, 2018
CHANGELOG.md updated bundle, access levels Jan 13, 2019
LICENSE.md object dynamics update Oct 30, 2016
README.md back macOS requirements back to 10.12, add coordinates test Dec 7, 2018
SKTiled.podspec Update pod spec for tvOS support Jan 5, 2019

README.md

SKTiled

SKTiled is a Swift framework for using Tiled assets with Apple's SpriteKit.

Swift Version Xcode Version Build Status License Platforms Carthage Compatible CocoaPods Compatible

SKTiled is a framework for using 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.

Demo Image

This branch is for Xcode 10 & Swift 4.2.

  • for Swift 3.3, see the xcode8 branch

Check out the Official Documentation.

Features

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

Requirements

  • iOS 11
  • tvOS 12
  • macOS 10.12
  • Xcode 10/Swift 4.2

Installation

Carthage & CocoaPods Support

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

github "mfessenden/SKTiled" ~> 1.20

For CocoaPods, install via a reference in your podfile:

pod 'SKTiled', '~> 1.20'

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

You can’t perform that action at this time.