{"id":1145,"url":"https://github.com/mfessenden/SKTiled","last_synced_at":"2025-07-30T20:32:58.294Z","repository":{"id":47056911,"uuid":"68841565","full_name":"mfessenden/SKTiled","owner":"mfessenden","description":"Swift framework for working with Tiled assets in SpriteKit","archived":false,"fork":false,"pushed_at":"2023-01-10T23:52:36.000Z","size":56155,"stargazers_count":261,"open_issues_count":20,"forks_count":33,"subscribers_count":16,"default_branch":"master","last_synced_at":"2024-11-28T11:39:44.874Z","etag":null,"topics":["game-development","ios","spritekit","swift","swift5","tiled","tiled-map-editor"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mfessenden.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-09-21T17:30:41.000Z","updated_at":"2024-11-12T14:42:45.000Z","dependencies_parsed_at":"2023-02-08T20:45:25.590Z","dependency_job_id":null,"html_url":"https://github.com/mfessenden/SKTiled","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfessenden%2FSKTiled","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfessenden%2FSKTiled/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfessenden%2FSKTiled/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mfessenden%2FSKTiled/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mfessenden","download_url":"https://codeload.github.com/mfessenden/SKTiled/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228187558,"owners_count":17882325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-development","ios","spritekit","swift","swift5","tiled","tiled-map-editor"],"created_at":"2024-01-05T20:15:39.863Z","updated_at":"2024-12-04T20:31:04.834Z","avatar_url":"https://github.com/mfessenden.png","language":"Swift","funding_links":[],"categories":["Games"],"sub_categories":["Getting Started","Other free courses","Linter"],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"Docs/images/doc-banner-centered.svg\" alt=\"SKTiled\" title=\"SKTiled\" width=\"881\" height=\"81\"/\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://swift.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Swift-5.5-brightgreen.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://developer.apple.com/download/more/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Xcode-11.0-orange.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://travis-ci.org/mfessenden/SKTiled\"\u003e\u003cimg src=\"https://travis-ci.org/mfessenden/SKTiled.svg?branch=master\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/mfessenden/SKTiled/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"http://www.apple.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/platforms-iOS%20%7C%20tvOS%20%7C%20macOS-red.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Carthage/Carthage/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Carthage-compatible-4BC51D.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://cocoapods.org/pods/SKTiled\"\u003e\u003cimg src=\"https://img.shields.io/cocoapods/v/SKTiled.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n**SKTiled** is a framework for integrating [Tiled][tiled-url] assets with [Apple's SpriteKit][spritekit-url], 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 \u0026 object types.\n\n![Demo Image](Docs/images/demo-iphone.png?raw=true)\n\n\nCheck out the [**Official Documentation**][sktiled-12-doc-url].\n\n## Features\n\n- [x] iOS \u0026 macOS versions\n- [x] tvOS version\n- [x] parses inline \u0026 external tilesets\n- [x] translates custom properties for maps, layers, objects \u0026 tiles\n- [x] renders all projections: (orthogonal, isometric, hexagonal \u0026 isometric staggered)\n- [x] renders all layer types: (tile, object, image, group)\n- [x] supports all compression types: (base64, zlib, gzip)\n- [x] renders animated and flipped tiles\n- [x] pre-loading of tilesets\n- [x] group nodes\n- [x] tile objects\n- [x] text objects\n- [x] template objects\n- [x] custom tile \u0026 object classes\n- [x] generate `GKGridGraph` graphs from custom attributes\n- [x] user-definable cost properties for `GKGridGraph` nodes\n- [ ] infinite maps\n- [ ] tile collision objects\n- [ ] Zstandard compression support\n- [ ] layer tinting\n- [ ] file properties\n\n\n## Requirements\n\n- iOS 12\n- tvOS 12\n- macOS 11\n- Xcode 11/Swift 5\n\n## Installation\n\n\n\n### Carthage\n\nFor Carthage installation, create a Cartfile in the root of your project:\n\n    github \"mfessenden/SKTiled\" ~\u003e 1.2\n\n\nTo use the new **[binary framework][binary-frameworks-url]** format, pass the **`--use-xcframeworks`** parameter to the build command:\n\n\tcarthage update --use-xcframeworks\n\nFor more information, see the **[Carthage Installation][docs-carthage-url]** documentation.\n\n\n### CocoaPods\n\n\nFor CocoaPods, install via a reference in your podfile:\n\n    pod 'SKTiled', '~\u003e 1.2'\n\n\n## Usage\n\nLoading a tilemap is very straightforward:\n\n```swift\nif let tilemap = SKTilemap.load(tmxFile: \"sample-map\") {\n    scene.addChild(tilemap)\n}\n```\nOnce loaded, the rendered [`SKTilemap`][sktilemap-url] node reflects the various properties defined in the originating scene:\n\n- `SKTilemap.size`: size of the map in tiles.\n- `SKTilemap.tileSize`: size of individual tiles.\n- `SKTilemap.orientation`: map orientation (ie orthogonal, isometric, etc).\n\n\nThe [`SKTilemap`][sktilemap-url] node also gives users access to child layers, tilesets, objects or individual tiles.\n\n### Working with Layers\n\nLayers represent containers that hold various types of data:\n\n- tile layers hold an array of tile sprites and associated tileset data\n- object groups contain vector shape objects\n- image layers display a single image\n- group layers encapsulate other layers\n\nAll **SKTiled** layer types are subclasses of the base [`SKTiledLayerObject`][sktiledlayerobject-url] object and provide access to coordinate transformation and positioning information. Additionally, every layer type can have individual offset transforms and rendering flags.  \n\nLayers can be accessed by type, name or index:\n\n```swift\n// query layers by type\nlet tileLayers = tilemap.tileLayers\nlet objectGroups = tilemap.objectGroups\nlet imageLayers = tilemap.imageLayers\nlet groupLayers = tilemap.groupLayers\n\n// query named layers\nlet groundLayers = tilemap.getLayers(named: \"Ground\") as! [SKTileLayer]\nlet objectGroups = tilemap.getLayers(named: \"Objects\") as! [SKObjectGroup]\nlet hudLayers = tilemap.getLayers(named: \"HUD\") as! [SKImageLayer]\n\n// query layer at a specific index\nif let firstLayer = tilemap.getLayer(atIndex: 1) as! SKTileLayer {\n    firstLayer.visible = true\n}\n```\n\n\n### Working with Tiles\n\nThere are a number of ways to access and manipulate tile objects. Tiles can be queried from the [`SKTilemap`][sktilemap-url] node, or the parent [`SKTileLayer`][sktilelayer-url] layer:\n\n```swift\n// access a tile via CGPoint\nlet tileCoord = CGPoint(x: 7, y: 12)\nif let tile = groundLayer.tileAt(coord: tileCoord) {\n    tile.tileData.tileOffset.x += 8\n}\n\n// access a tile with integer coordinates\nif let tile = groundLayer.tileAt(7, 12) {\n    tile.tileData.tileOffset.x += 8\n}\n\n// query tiles at a specific coordinate (all layers)\nlet tiles = tilemap.tilesAt(2, 4)\n```\n\nTiles assigned custom properties in **Tiled** can be accessed in **SKTiled**:\n\n```swift\n// query tiles of a certain type\nif let fireTiles = tilemap.getTiles(ofType: \"fire\") {\n    // do something fiery here...\n}\n```\n\nYou can also return tiles with a specific ID value:\n\n```swift\nif let waterTiles = waterLayer.getTiles(globalID: 17) {\n    // do something watery here...\n}\n```\n\n### Working with Objects\n\n`SKTileObject` objects can be queried from both the [`SKTilemap`][sktilemap-url] and [`SKObjectGroup`][skobjectgroup-url] nodes:\n\n```swift\nlet allObjects = tilemap.getObjects()\nlet allTreeObjects = tilemap.getObjects(named: \"Tree\")\nlet allCollisionObjects = tilemap.getObjects(ofType: \"Collision\")\n\n// get objects from the objects group layer\nlet entrances = objectsLayer.getObjects(ofType: \"Entrance\")\n```\n\n### Acessing Tile Data\n\nThe [`SKTilemap`][sktilemap-url] node stores an array of individual tilesets parsed from the original **Tiled** document. Individual tile data is accessible from either the [`SKTileset`][sktileset-url] object:\n\n```swift\nlet tileSet = tilemap.getTileset(\"spritesheet-16x16\")\n// get data for a specific id\nlet tileData = tileSet.getTileData(globalID: 177)\n```\n\nand the parent [`SKTilemap`][sktilemap-url]:\n\n```swift\nlet tileData = tilemap.getTileData(globalID: 177)\n```\n\n\n## Adding Nodes\n\nTile data includes texture data, and [`SKTile`][sktile-url] objects are [`SKSpriteNode`][skspritenode-url] subclasses that can be initialized with tileset data:\n\n```swift\nlet newTile = SKTile(data: tileData)\nscene.addChild(newTile)\n```\n\nCoordinate information is available from each layer via the [`SKTiledLayerObject.pointForCoordinate`][sktiledlayerobject-pointforcoordinate-url] method:\n\n```swift\nlet tilePoint = groundLayer.pointForCoordinate(4, 5)\ntile.position = tilePoint\n```\n\nNew nodes (any [`SKNode`][sknode-url] type) can be added directly to any layer. All [`SKTiledLayerObject`][sktiledlayerobject-url] layer types have expanded convenience methods for adding child nodes with coordinates and z-position.\n\n```swift\nlet roadRoot = SKNode()\ngroundLayer.addChild(roadRoot, 4, 5, zpos: 100.0)\n```\n\n**SKTiled** also provides methods for getting coordinate data from [`UITouch`][uitouch-url] and [`NSEvent`][nsevent-url] mouse events:\n\n```swift\n// get the coordinate at the location of a touch event\nlet touchLocation: CGPoint = objectsLayer.coordinateAtTouchLocation(touch)\n```\n\n## Animated Tiles\n\nTiles with animation will animate automatically when the tilemap node is added to the [`SKScene.update`][skscene-update-url] method. Animated tiles can be accesssed from the either the [`SKTilemap`][sktilemap-url] node or the parent layer.\n\n\n```swift\n// get all animated tiles, including nested layers\nlet allAnimated = tilemap.animatedTiles(recursive: true)\n\n// pause/unpause tile animation\nfor tile in allAnimated {\n    tile.isPaused = true\n}\n\n// run animation backwards\nfor tile in allAnimated {\n    tile.speed = -1.0\n}\n\n// get animated tiles from individual layers\nlet layerAnimated = groundLayer.animatedTiles()\n```\n\n\n## Custom Properties\n\nCustom properties are supported on all object types. All **SKTiled** objects conform to the [`SKTiledObject`][sktiledobject-url] protocol and allow access to and parsing of custom properties.\n\nAny property added to an object in **Tiled** will be translated and stored in the `SKTiledObject.properties` dictionary.\n\n```swift\nlet layerDepth = groundLayer.getValue(forProperty: \"depth\")\ngroundLayer.setValue(12.5, forProperty: \"depth\")\n```\n\nTo query tiles of a given type:\n\n```swift\nlet waterTiles = groundLayer.getTiles(ofType: \"water\")\nlet allWaterTiles = tilemap.getTiles(ofType: \"water\")\n```\n\nFor specific property/value types:\n\n```swift\nlet groundWalkable = groundLayer.getTilesWithProperty(\"walkable\", true)\nlet allWalkable = tilemap.getTilesWithProperty(\"walkable\", true\")\n```\n\n## Acknowledgments\n\n- [Thorbjørn Lindeijer](https://github.com/bjorn): creator of *Tiled*\n- [GZipSwift](https://github.com/1024jp/GzipSwift): zlib decompression extensions\n- [Steffen Itterheim](http://www.learn-cocos2d.com): Author of TilemapKit, the inspiration for this project\n- [Kenney Vleugels](http://www.kenney.nl): demo spritesheet assets\n- [Amit Patel](http://www-cs-students.stanford.edu/~amitp/gameprog.html): tile-based game logic\n- [Clint Bellanger: Isometric Tiles Math](http://clintbellanger.net/articles/isometric_math)\n\n[swift5-image]:https://img.shields.io/badge/Swift-5.3-brightgreen.svg\n[swift4-image]:https://img.shields.io/badge/Swift-4.2-brightgreen.svg\n[swift3-image]:https://img.shields.io/badge/Swift-3.2-brightgreen.svg\n[swift-url]: https://swift.org/\n[license-image]:https://img.shields.io/badge/License-MIT-blue.svg\n[license-url]:https://github.com/mfessenden/SKTiled/blob/master/LICENSE\n[travis-image]:https://travis-ci.org/mfessenden/SKTiled.svg?branch=master\n[travis-url]:https://travis-ci.org/mfessenden/SKTiled\n[platforms-image]:https://img.shields.io/badge/platforms-iOS%20%7C%20tvOS%20%7C%20macOS-red.svg\n[platforms-url]:http://www.apple.com\n[carthage-image]:https://img.shields.io/badge/Carthage-compatible-4BC51D.svg\n[carthage-url]:https://github.com/Carthage/Carthage\n[pod-image]:https://img.shields.io/cocoapods/v/SKTiled.svg\n[mailto-url]:(mailto:michael.fessenden@gmail.com?subject=[SKTiled]%20Projects)\n\n[xcode11-image]:https://img.shields.io/badge/Xcode-11.0-orange.svg\n[xcode10-image]:https://img.shields.io/badge/Xcode-10.0-orange.svg\n[xcode-downloads-url]:https://developer.apple.com/download/more/\n\n[pod-url]:https://cocoapods.org/pods/SKTiled\n\n[branch-master-url]:https://github.com/mfessenden/SKTiled\n[branch-xcode8-url]:https://github.com/mfessenden/SKTiled/tree/xcode8\n[branch-xcode9-url]:https://github.com/mfessenden/SKTiled/tree/xcode9\n\n[header-image]:https://mfessenden.github.io/SKTiled/1.2/images/header.png\n[demo-mac-image]:https://mfessenden.github.io/SKTiled/1.2/images/demo-macos-iso.png\n[demo-iphone-img]:https://mfessenden.github.io/SKTiled/1.2/images/demo-iphone.png\n\n\n[demo-phone-img2]:/Docs/images/demo-iphone.png\n\n\n\u003c!--- Documentation ---\u003e\n\n[sktiled-gh-url]:https://mfessenden.github.io/SKTiled\n[sktiled-12-doc-url]:https://mfessenden.github.io/SKTiled/1.2/index.html\n[sktilemap-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTilemap.html\n[sktiledobject-url]:https://mfessenden.github.io/SKTiled/1.2/Protocols/SKTiledObject.html\n[sktile-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTile.html\n[skobjectgroup-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKObjectGroup.html\n[sktiledlayerobject-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTiledLayerObject.html\n[sktiledlayerobject-pointforcoordinate-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTiledLayerObject.html\n[sktilelayer-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTileLayer.html\n[sktileobject-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTileObject.html\n[sktileset-url]:https://mfessenden.github.io/SKTiled/1.2/Classes/SKTileset.html\n[docs-carthage-url]:https://mfessenden.github.io/SKTiled/1.3/getting-started.html#carthage-installation\n\n\u003c!--- Tiled ---\u003e\n\n[tiled-url]:http://www.mapeditor.org\n[group-layers-url]:http://doc.mapeditor.org/manual/layers/#group-layers\n\n\u003c!--- Apple ---\u003e\n\n[spritekit-url]:https://developer.apple.com/documentation/spritekit\n[sknode-url]:https://developer.apple.com/documentation/spritekit/sknode\n[skspritenode-url]:https://developer.apple.com/documentation/spritekit/skspritenode\n[skscene-url]:https://developer.apple.com/documentation/spritekit/skscene\n[skscene-update-url]:https://developer.apple.com/documentation/spritekit/skscene/1519802-update\n[uitouch-url]:https://developer.apple.com/documentation/uikit/uitouch\n[nsevent-url]:https://developer.apple.com/documentation/appkit/nsevent\n[swift-package-doc-url]:https://developer.apple.com/documentation/swift_packages\n[binary-frameworks-url]:https://developer.apple.com/videos/play/wwdc2019/416/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfessenden%2FSKTiled","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmfessenden%2FSKTiled","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmfessenden%2FSKTiled/lists"}