Crate tiled

Expand description

§rs-tiled

tiled = "0.14.0"

A crate for reading TMX (map) and TSX (tileset) files from the Tiled Map Editor into Rust. It provides a huge set of features as well as a strong wrapper over internal features such as GIDs.

Documentation is available on docs.rs.

Code contributions are welcome as are bug reports, documentation, suggestions and criticism.

The minimum supported TMX version is 0.13.

§Example

use tiled::Loader;

fn main() {
    let mut loader = Loader::new();
    let map = loader.load_tmx_map("assets/tiled_base64_external.tmx").unwrap();
    println!("{:?}", map);
    println!("{:?}", map.tilesets()[0].get_tile(0).unwrap().probability);
    
    let tileset = loader.load_tsx_tileset("assets/tilesheet.tsx").unwrap();
    assert_eq!(*map.tilesets()[0], tileset);
}

§FAQ

§How do I embed a map into my executable? / How do I read a file from anywhere else that isn’t the filesystem’s OS?

The crate does all of its reading through the read_from function of the ResourceReader that you create the loader with. By default, this reader is set to FilesystemResourceReader and all files are read through the OS’s filesystem. You can however change this.

Here’s an example mostly taken from Loader::with_reader’s documentation:

use tiled::{DefaultResourceCache, Loader};

let mut loader = Loader::with_reader(
    // Specify the reader to use. We can use anything that implements `ResourceReader`, e.g. FilesystemResourceReader.
    // Any function that has the same signature as `ResourceReader::read_from` also implements it.
    // Here we define a reader that embeds the map at "assets/tiled_xml.csv" into the executable, and allow
    // accessing it only through "/my-map.tmx"
    // ALL maps, tilesets and templates will be read through this function, even if you don't explicitly load them
    // (They can be dependencies of one you did want to load in the first place).
    // Doing this embedding is useful for places where the OS filesystem is not available (e.g. WASM applications).
    |path: &std::path::Path| -> std::io::Result<_> {
        if path == std::path::Path::new("/my-map.tmx") {
            Ok(std::io::Cursor::new(include_bytes!("assets/tiled_csv.tmx")))
        } else {
            Err(std::io::ErrorKind::NotFound.into())
        }
    }
);

If the closure approach confuses you or you need more flexibility, you can always implement ResourceReader on your own structure.

§How do I get the crate to work on WASM targets?

The crate supports WASM, but since it does not currently support asynchronous loading, there are some gotchas.

First, to make it work on any WASM target, enable the wasm feature, like so:

[dependencies]
# ...
tiled = { version = ".....", features = ["wasm"] }

Second, since you cannot use the filesystem as normally on the web, you cannot use FilesystemResourceReader. As such, you’ll need to implement your own ResourceReader. This is a pretty simple task, as you just need to return anything that is Readable when given a path, e.g.:

use std::io::Cursor;

struct MyReader;

impl tiled::ResourceReader for MyReader {
    type Resource = Cursor<&'static [u8]>;
    type Error = std::io::Error;

    // really dumb example implementation that just keeps resources in memory
    fn read_from(&mut self, path: &std::path::Path) -> std::result::Result<Self::Resource, Self::Error> {
        if path == std::path::Path::new("my_map.tmx") {
            Ok(Cursor::new(include_bytes!("assets/tiled_xml.tmx")))
        } else {
            Err(std::io::Error::new(std::io::ErrorKind::NotFound, "file not found"))
        }
    }
}

You can also use a function with the same signature as tiled::ResourceReader::read_from; check the ResourceReader docs for more information.

§Licences

assets/tilesheet.png by Buch

Licenced under MIT

Structs§

Chunk: Part of an InfiniteTileLayer.
ChunkData: Part of an infinite tile layer’s data.
Color: Represents a RGBA color with 8-bit depth on each channel.
DefaultResourceCache: A cache that identifies resources by their path, storing them in a HashMap.
FilesystemResourceReader: A ResourceReader that reads from File handles.
FiniteTileLayer: A TileLayer with a defined bound (width and height).
FiniteTileLayerData: The raw data of a FiniteTileLayer. Does not include a reference to its parent Map.
Frame: A structure describing a frame of a TMX tile animation.
GroupLayer: A group layer, used to organize the layers of the map in a hierarchy. Also see the TMX docs.
GroupLayerData: The raw data of a GroupLayer. Does not include a reference to its parent Map.
Image: A reference to an image stored somewhere within the filesystem.
ImageLayer: A layer consisting of a single image. Also see the TMX docs.
ImageLayerData: The raw data of an ImageLayer. Does not include a reference to its parent Map.
InfiniteTileLayer: A TileLayer with no bounds, internally stored using Chunks.
InfiniteTileLayerData: The raw data of a InfiniteTileLayer. Does not include a reference to its parent Map.
Layer: A generic map layer, accessed via Map::layers().
LayerData: The raw data of a Layer. Does not include a reference to its parent Map.
LayerTile: An instance of a Tile present in a TileLayer.
LayerTileData: Stores the internal tile gid about a layer tile, along with how it is flipped.
Loader: A type used for loading Maps and Tilesets.
Map: All Tiled map files will be parsed into this. Holds all the layers and tilesets.
Object: Wrapper over an ObjectData that contains both a reference to the data as well as to the map it is contained in.
ObjectData: Raw data belonging to an object. Used internally and for tile collisions.
ObjectLayer: Also called an “object group”. Used for storing Objects in a map.
ObjectLayerData: Raw data referring to a map object layer or tile collision data.
ObjectTile: An instance of a Tile present in an Object.
ObjectTileData: Stores the internal tile gid about a layer tile, along with how it is flipped.
OrientationParseError: An error arising from trying to parse an Orientation that is not valid.
StaggerAxisError: An error arising from trying to parse an StaggerAxis that is not valid.
StaggerIndexError: An error arising from trying to parse an StaggerIndex that is not valid.
Template: A template, consisting of an object and a tileset
Tile: Points to a tile belonging to a tileset.
TileData: Raw data belonging to a tile.
Tileset: A collection of tiles for usage in maps and template objects.
WangColor: Stores the data of the Wang color.
WangId: The Wang ID, stored as an array of 8 u8 values.
WangSet: Raw data belonging to a WangSet.
WangTile: Stores the Wang ID.

Enums§

CsvDecodingError: Errors that can occur while decoding csv data.
Error: Errors which occurred when parsing the file
HorizontalAlignment: The horizontal alignment of an ObjectShape::Text.
InvalidTilesetError: Errors that can occur parsing a Tileset.
LayerType: Represents some kind of map layer.
ObjectShape: A structure describing an Object’s shape.
Orientation: Represents the way tiles are laid out in a map.
PropertyValue: Represents a custom property’s value.
StaggerAxis
StaggerIndex
TileLayer: A map layer containing tiles in some way. May be finite or infinite.
TilesetLocation: The location of the tileset this tile is in
VerticalAlignment: The vertical alignment of an ObjectShape::Text.
WangSetType: Wang set’s terrain brush connection type.

Traits§

ResourceCache: A trait identifying a data type that holds resources (such as tilesets) and maps them to a ResourcePath to prevent loading them more than once. Normally you don’t need to use this type yourself unless you want to create a custom caching solution to, for instance, integrate with your own.
ResourceReader: A trait defining types that can load data from a ResourcePath.

Type Aliases§

Properties: A custom property container.
ResourcePath: A reference type that is used to refer to a resource. For the owned variant, see ResourcePathBuf.
ResourcePathBuf: An owned type that is used to refer to a resource. For the non-owned variant, see ResourcePath.
Result: A result with an error variant of crate::Error.
TileId: A tile ID, local to a tileset.

Crate tiledCopy item path