Project

public class Project

Projects are the primary entry point for TiledKit. The project represents the root of all Maps and TileSets and the resources (such as images) that support them. The default Project will use the main Bundle as its root, making it very easy to include in a Swift Package Manager or Xcode module.

    let myMap = Project.default.get("mymap")

The above code will retrieve a file named ‘mymap.tmx’ from the root of the main Bundle. You may create instances of Projects that have a different root (such as an actual Tiled project directory, or different Bundle) using the standard constructurs.

Projects are critical as they enable the relative processing of any resources referenced in the Tiled files and provide the key entry point for specializing TiledKit for a a specific game engine. Specializations only require the registration of a specific ResourceLoader for the type of object required by the game engine. See SKTiledKit for an example of a specialization.

Projects also provide resource caching capabilities, ensuring that the contents of any URL are loaded only once. If you add your own ResourceLoader for types you can specify that if the created object should be cached or not.

  • The object types associated with the project

    Declaration

    Swift

    public var objectTypes: ObjectTypes

  • The location the project defines for storing the ObjectTypes file

    Declaration

    Swift

    public var objectTypesUrl: URL

  • The default Project which uses the Bundle.main as its resource root

    Declaration

    Swift

    public static let `default`: Project

  • Creates a new instance of a Project that uses a different bundle as a root.

    Declaration

    Swift

    public init(using bundle: Bundle, searchForProjectFile autodiscover: Bool = true)

    Parameters

    bundle

    The Bundle to use
    autodiscover

    Will do a deep search in the bundle for a .tiled-project file and if found load it and set the base URL to the folder containing it.

  • Creates a new instance of a Project that uses the specied directory as its root

    Declaration

    Swift

    public init(at rootDirectory: URL, searchForProjectFile autodiscover: Bool = true)

    Parameters

    rootDirectory

    The URL of a directory on the local machine
    autodiscover

    Will do a deep search in the folder for a .tiled-project file and if found load it and set the base URL to the folder containing it.

  • Creates a new instance of a Project that uses the specified project file URL to provide both the root of the project for relative paths, and will load the contents of the file to provide the object types and folders

    Throws

    If the file does not exist or cannot be decoded

    Declaration

    Swift

    public init(from projectFile: URL) throws

    Parameters

    rootDirectory

    The URL of the .tiled-project file

  • Retrieves the URL for a resource within the project

    Declaration

    Swift

    public func url(for file: String, in subDirectory: String? = nil, of type: FileType? = nil) -> URL?

    Parameters

    file

    The name of the file, excluding any extension
    subDirectory

    The sub-directory path if it is not located at the root
    type

    The type of file

    Return Value

    A URL for the file in the Project or nil if it could not be found

  • Resources a url within the project, if it may be relative, then you should supply the URL it is relative to

    Declaration

    Swift

    public func resolve(_ url: URL, relativeTo baseUrl: URL?) -> URL?

    Parameters

    url

    The URL to be resolved (it does not need to be in the project if it is a fully specified URL)
    relativeTo

    If the URL could be or is relative, then this will be used as the base

    Return Value

    A URL or nil if the the URL is not reachable

  • Loads a Map from the project with the specied name (and optionally subdirectory). Note that you do not have to include the file extension .tmx in the name (although if you do the Map will still be loaded).

    Throws

    Any errors finding or loading the Map will be thrown here

    Declaration

    Swift

    public func retrieve(map name: String, in subdirectory: String? = nil) throws -> Map

    Parameters

    name

    The name of the map’s file. You can ommit the “.tmx ” extension, but it is acceptable to include it.
    subdirectory

    The sub-directory path (from the root of the project)

    Return Value

    The desired Map

  • Loads a TileSet from the project with the specied name (and optionally subdirectory). Note that you do not have to include the file extension .tsx in the name (although if you do the TileSet will still be loaded).

    Throws

    Any errors finding or loading the TileSet will be thrown here

    Declaration

    Swift

    public func retrieve(tileset name: String, in subdirectory: String? = nil) throws -> TileSet

    Parameters

    name

    The name of the tileset’s file. You can ommit the “.tsx ” extension, but it is acceptable to include it.
    subdirectory

    The sub-directory path (from the root of the project)

    Return Value

    The desired TileSet

  • Loads a URL for a resource (which can be relative to another resource in the project, very useful as Tiled often uses relative paths within projects, or across Maps and Tile Sets).

    Throws

    Any errors thrown while the resource is being retreived (for example, the resource can’t be found)

    Declaration

    Swift

    public func retrieve<R>(asType: R.Type, from resourceUrl: URL, relativeTo baseUrl: URL? = nil) throws -> R where R : Loadable

    Parameters

    asType

    The desired type
    resourceUrl

    The URL of the resource (can be relative)
    baseUrl

    The URL to use as the starting point if resourceURL is relative. Otherwise the project root will be used

    Return Value

    An instance of the resource

  • Undocumented

    Declaration

    Swift

    public func retrieve<R>(asType: R.Type, from fileName: String, in subdirectory: String? = nil, of type: FileType? = nil) throws -> R where R : Loadable

  • Stores an asset in the Projects resource cache for later retreival via the supplied URL. In this way ResourceLoaders can exploit the ability to create common cached assets

    Declaration

    Swift

    public func store<R>(_ asset: R, as assetUrl: URL) where R : Loadable

    Parameters

    asset

    The asset
    assetUrl

    The URL of the asset/resource

  • Retreive a specialized map for a specific game engine. Note that the exact specialization will be determined by the receiving variable, so you must ensure the type is explicit. For example:

    let level : CoolEngineScene = try Project.default.retrieve(specializedMap: "Level 1")

    You may wish to wrap this in further extensions to project (e.g. func retrieve(coolEngineMap:String))

    Throws

    Errors from loading

    Declaration

    Swift

    func retrieve<EngineType>(_ engine: EngineType.Type, mapNamed name: String, in subdirectory: String? = nil) throws -> EngineType.MapType where EngineType : Engine

    Parameters

    name

    The name of the map which will be resolved to a specific tiled Map file using the standard Project methodology
    subdirectory

    The subdirectory the map is stored in relative to the Project root

    Return Value

    An instance of the specialized map