Whew, this was a bigger change than I thought it would be. I've made a few assumptions about the best way to design and implement things, so feel free to let me know if it should be restructured any.

Relates to #145

======

This patch adds support for templates. Templates are a property on Objects that specify an external file to load object properties by default. In this implementation, templates are not visible to the end user, their behaviour happens "automatically".

As it parses, the Map will generate a list of templates, with each being identified by their ID.

Templates introduce the concept of a tile that is bound to a tileset that is not part of the main map's list of tilesets. For this reason, the tileset_index() function now returns Option. Internally, an enum is used to signify whether the tileset is map or template bound.

I had to change the signature of the Resource cache, because the generator function now needs access to the cache.

Adds a rough demo using SFML for rendering. Closes #35.

Extremely WIP. Right now the example is really long because a lot of boilerplate is required. If you realize any way to reduce this boilerplate without making the example more specific, let me know.

Adds a rendering demo for ggez. Supports multiple layers, multiple tilesets, and parallax. Also draws basic shape objects.

You can middle mouse + drag to pan around and scroll to zoom. Right click also toggles a demo animation that makes the tiles move around.

It has pretty good performance because it uses ggez's SpriteBatches for tile rendering. It could be better by caching and reusing the batches but I figured I'd leave that out to simplify a bit.

I made a nicer example map for testing locally but I'll make a separate PR for that I think. Since the current example map is large and mostly empty, and this centers it in the window at the start, you need to zoom out or pan in order to see it (the other nicer map has a more reasonable size).

(this does not properly hook into ggez's filesystem for loading external tilesets/images as that would still require something like #100 I believe)

This could probably still use a bit more clean up and commenting

related: #134

Tileset::tiles only contains tiles that have some kind of custom attribute. This makes it confusing to use since it's not mentioned in the field docs.

Why

Closes #234

In Tiled 1.9 the "type" property was renamed to "class". My PR addresses this.

How

In addition to "type", the "class" property is parsed. If the former is not present, the latter takes its place. This way, the solution is compatible with both 1.9+ and older maps.

After the below conversation, this is what I did:

• Deprecated obj_type for Objects and tile_type for Tiles in favor of user_type. Added deprecation notices
• Added user_type to Maps, Tilesets and Layers.
• Both class and type XML params now resolve to user_type everywhere.

Support for type/class is now implemented for the following entities:

• Tiles in tileset (Tile)
• Objects
• Maps
• Tilesets
• Layers

These are all places that I'm aware of.

Test plan

Tested locally on both old and new maps. I didn't add tests as I haven't found any existing ones (nor test fixtures) which have the "type" or "class" property set. Eventually, I can create/modify one if requested.

Right now all of our examples and test code uses a default &mut FilesystemResourceCache for loading, as it only handles a single map. It would be wise to expose a loading method that doesn't take in a cache and another one that does (with a _cached postfix) as it would confuse new users less and would result in less boilerplate for small applications and whatnot.

Looking at the open pull requests, there are evidently quite a few people who would like to contribute improvements to this crate, but are unable to do so because unfortunately @mattyhall had not much time for reviews in the past months, as mentioned in https://github.com/mattyhall/rs-tiled/issues/103#issuecomment-940909303.

I would like to propose we move this create into the mapeditor organization, and to gather a few co-maintainers that can help with pull requests. We can set up a review policy that every change needs at least one reviewer, to help ensure the quality of the crate.

Personally I've only done a minimum amount of Rust coding, but I would be interested in helping to keep this crate up to date. I also think it would be nice if we could achieve to have "json" and "tmx" supported as features of the same crate, rather than having separate crates.

Who would be interested in helping to maintain this crate? And what do you think about this, @mattyhall?

Hi, I'm working on a game using the amethyst game engine and I'm planning on using this lib to do the map. It seems like it might be something useful to push back up stream so I wanted to create an issue to see if you wanted such a feature to get merged into this or a companion crate, and if so if you have any input on how you think it should be designed.

I'm not exactly an expert with this library or amethyst or game development in general but my initial idea is to have a function that takes a tiled::Map and either returns an amethyst::renderer::SpriteSheet or output serialized data (possibly writing it to a file) that matches https://www.amethyst.rs/doc/latest/doc/amethyst_renderer/struct.SpriteSheetFormat.html.

The first option seems more straightforward and efficient but it doesn't match the examples which are always loading sprite-sheets from files and it creates a common dependency between rs-tiled and part of amethyst, though it can be conditionally compiled with a feature. I'm not really sure which one is best.

The function would also need to return something like a Vec<(Transform, SpriteRender)> which can be easily iterated over and added to the world as entities.

If I'm way off base on this just let me know :)

An experiment. Exposes data types but implements Deref<Target=TData> for wrapper types, leaving practically the same interface but also allowing the user to also use data types in more performance-critical parts.

Closes #168.

Global tile IDs appear frequently in the codebase but I feel like they are not explained throughout, and they lack their own type so they can be confused with local (tileset) IDs.

A minor update to support Tiled parallax information.

The asset/tiled_parallax.tmx provides a map with three layers (Background, Middle, and Foreground), each with different parallax information (Middle being the default Tiled (1.0, 1.0)).

The tests/test contains an example:

fn test_parallax_layers() {
    let r = read_from_file_with_path(&Path::new("assets/tiled_parallax.tmx")).unwrap();
    for (i, layer) in r.layers.iter().enumerate() {
        match i {
            0 => {
                assert_eq!(layer.name, "Background");
                assert_eq!(layer.parallax_x, 0.5);
                assert_eq!(layer.parallax_y, 0.75);
            }
            1 => {
                assert_eq!(layer.name, "Middle");
                assert_eq!(layer.parallax_x, 1.0);
                assert_eq!(layer.parallax_y, 1.0);
            }
            2 => {
                assert_eq!(layer.name, "Foreground");
                assert_eq!(layer.parallax_x, 2.0);
                assert_eq!(layer.parallax_y, 2.0);
            }
            _ => panic!("unexpected layer"),
        }
    }
}

The version is bumped to 0.9.6 to indicate the extended information.

Thanks for a great crate by the way!

Out of the box, adding tiled as a dependency of my project broke my WASM builds because zstd's default build does not support it. While I eventually learned that zstd is an optional feature in tiled, this does not appear to be documented anywhere, and there aren't good interfaces for discovering crate features.

I've seen #228, and I have a couple possibilities to make the default experience better:

• keep zstd as an optional feature but default disabled
• replace zstd with another implementation that supports WASM (branch that implements this)
• expose zstd's wasm crate feature somehow and document how to build for WASM? This is the least thought through of the alternatives because I haven't looked into it at all; I just saw that it exists.
• clearly document how to get a wasm-capable build (and the limitations around embedded tilesets), but otherwise make no changes to the status quo

Probably the biggest reason people from <=0.9.5 aren't switching over to newer versions is that they rely on GIDs. Even if they are an internal detail of the TMX format, I'm beginning to believe removing them was a mistake. Even though they aren't reliable and may change when editing the map, they do function well by assigning unique numbers to tiles used within a map, which may be helpful when rendering or working on small projects.

Maybe we should introduce them again as an optional feature?

https://docs.rs/tiled/latest/tiled/struct.FiniteTileLayer.html#method.get_tile

Resulting in a single layer with just a couple of tiles overrides all layers under with tile id 0 when rendered.

Improves crate ergonomics. Most of the time when parsing you are only interested in one layer type at a time so it's much nicer to use layer.layer_type().as_tiles() than the whole match block. Specially nice for closures in filters:

// Old
let tile_layers = self
    .map
    .layers()
    .filter_map(|l|
        match l.layer_type() {
            tiled::LayerType::Tiles(tl) => Some((l, tl)),
            _ => None,
        }
    );

// New
let tile_layers = self
    .map
    .layers()
    .filter_map(|l| Some((l, l.layer_type().as_tiles()?)));

Crates like serde_json do this with some of their enums.

WIP. This PR moves all internal functions to the parse module. This has the advantage of providing a clear interface to the user & developers, as the structure of Tiled objects are now defined completely separate from how they are parsed. However, this PR still doesn't answer questions like "Should we make the parse functions public?" "How should we present the parse functions internally?" etc. For now the definitions have been moved literally to the XML/"common" module.

Stopped mid-way since I realized a huge mistake with wangsets (The WangSetType type isn't accessible from outside and the compiler didn't complain somehow, even with the wang_set_type public WangSet member). Fixing this now in current. I wish we'd have implemented wangsets in next instead. Oh well.

The crate won't work on Web Assembly even with zstd disabled, because the load_tmx_map_from function internally calls File::open, which returns an error on wasm targets.