TMX documentation on orientations is non-existent

[onpon4]

I find the documentation for TMX to be quite lacking and neglected in general. Implementing a renderer for TMX is excessively time-consuming, at least for me, because I often don't feel sure at all what I'm supposed to do with something. Someone working on Tiled needs to make more of an effort to keep this documentation up-to-date and thorough.

But this is easily the most problematic fault of it right now: far as I can see, there is no documentation indicating how tiles are rendered in each orientation. I didn't even think anything of it until recently; the TMX Map Format wiki page only mentions the existence of the various possible orientations and mentions where the origin of objects is, so I, not currently having a use for isometric maps, ended up writing my TMX renderer (xsge_tmx) in a way that only works for orthogonal maps. I'm working on fixing that now, but this would be a lot easier if the way the tiles are supposed to be rendered was written down somewhere, rather than me having to either perform tests (upgrading Tiled in the process, since I have Tiled 0.10.2 still) or traverse Tiled's source code.

[bjorn]

Yes, this is definitely something that really needs improvement. When I started Tiled, my idea was that generally people would make Tiled do whatever their engine was doing so the compliance was kind of the other way around and I just needed to decide which options made sense to have in Tiled (of course, Tiled is still lacking many options, but it covers most common situations at least). Basically, Tiled is not trying to set a standard but rather to adapt to existing approaches.

As it turns out, the main way people are using Tiled is by relying on a 3rd party framework to render their Tiled map correctly. This puts the compliance effort on the writer of the framework, and it would certainly help to document Tiled's behavior in more detail for their sake. Basically, Tiled did become a standard after all.

So yes, I find the docs are lacking too. What I'm lacking though is time. And in allocating that resource the docs seem to always get left behind in preference to bug fixing and improving Tiled or answering people's questions. Now that I can look forward to spending more time on Tiled thanks to support from patrons, I'll have to reserve part of that time for improving the documentation.

[onpon4]

I've added some docstrings to python-tmx indicating what I think I know about how rendering works for orthogonal and isometric layouts (I don't know about the others yet). This is what I've come up with so far describing their layouts:

• "orthogonal" -- Each tile in a row is rendered to the left or right of the previous tile, depending on the map's renderorder attribute, at a distance of the map's tilewidth attribute from the previous tile's location. Each row is up or down compared to the previous row, depending on the map's renderorder attribute, at a distance of the map's tileheight attribute from the previous tile's location.
• "isometric" -- Each tile in a row has a horizontal distance of half the map's tilewidth attribute and a vertical distance of half the map's tileheight attribute from the previous tile's location. If the map's renderorder attribute indicates "right", each tile is to the right and down compared to the previous tile. If the map's renderorder attribute indicates "left", each tile is to the left and up compared to the previous tile. The distance between rows is the same as the distance between tiles. If the map's renderorder attribute indicates "down", each row is to the left and down compared to the previous row. If the map's renderorder attribute indicates "up", each row is to the right and up compared to the previous row.

Just in case that's helpful.

[bjorn]

@onpon4 The isometric renderer at the moment does not support the render order attribute.

In general I'd advice against attempting more detailed documentation like this at a library like python-tmx. This kind of stuff really belongs in a kind of Tiled specification since if it's spread out in other places then it will be much harder to make sure it is correct and up to date. So I would say try keep it short and hopefully soon you will be able to refer to some official documentation for the details.

[onpon4]

OK, then. What do you propose I put in python-tmx's documentation, exactly? I don't see how I can write documentation that's helpful without future changes rendering what is said out of date. Perhaps, if that's such a problem, the TMX format should be stabilized.

[bjorn]

@onpon4 I'm trying to keep the TMX format as stable as possible. Changes are usually small, but even things like dropping attributes when they have their default value, or changing number values from integer to float have already been causing problems for some libraries.

However, I didn't mean the format would actually change much, just that the descriptions should be accurate and updated to include new features. I can't review the documentation of all the various libraries supporting TMX maps, hence we should aim for complete docs on the Tiled wiki for example, which could be referred to for details.

Once this documentation would be available, you could in python-tmx docs just say which values you're supporting and refer to the TMX documentation for the actual behavior.

[kheftel-old]

Do you need help writing documentation? I've written a renderer for my orthogonal game at least, and could try my hand at improving things.

[bjorn]

@kheftel Well, if you want to start on something feel free to do so. I'm considering to use MkDocs and will host on either github pages or readthedocs, but to start with you could just improve existing wiki pages here or start new ones.

[kheftel-old]

cool! is there any kind of review process? Do you just get notified of all edits and have the chance to approve/revert them?

[bjorn]

@kheftel I don't get notified, but it's stored in a git repository so eventually I'll notice all the changes and review them. :-)

[kheftel-old]

cool. I'll see what I can do when I have some time. Any guidance on pages that need it more than others?

[bjorn]

@kheftel Sorry I can't provide any guidance at this point. Feel free to start with the issue this thread started about.

[kheftel-old]

no worries

[bjorn]

I've started adding the official documentation to the Tiled repository at https://github.com/bjorn/tiled/tree/master/docs. The documentation is hosted at http://doc.mapeditor.org/. I will link it from the main Tiled website when it at least provides a rough skeleton for the manual and some more pages have been ported over (like the Keyboard Shortcuts and Automapping pages).

In the few hours I've used mkdocs it's been a pleasant experience especially since it makes the browser automatically refresh when changing any files (using mkdocs serve).

Contributions are welcome and should now be done via pull requests.

I've made some minor improvements to the TMX Map Format page, but nothing yet that addresses the missing information pointed out in this issue.

[onpon4]

Some time ago, I wrote some paragraphs describing how the first three orientations work, after studying them. I see such explanations still don't exist in the specification, so feel free to derive such explanations from mine, or just use mine directly.

Explanation for orthogonal:

The list is split into rows of tiles. Each tile in a row is rendered to the right of the previous tile's location at a distance of the map's tilewidth attribute. Each row is rendered below the previous row's location at a distance of the map's tileheight attribute.

Explanation for isometric:

The list is split into rows of tiles. Each tile in a row is rendered to the right of the previous tile's location at a distance of half the map's tilewidth attribute and below the previous tile's location at a distance of half the map's tileheight attribute. Each row is rendered to the left of the previous row's location at a distance of half the map's tilewidth attribute and below the previous row's location at a distance of half the map's tileheight attribute.

Explanation for staggered:

The list is split into rows of tiles. Each tile in a row is rendered to the right of the previous tile's location at a distance of the map's tilewidth attribute. Each row is rendered below the previous row's location at a distance of half the map's tileheight attribute. Assuming that the first row is assigned an index of 0, the rows with odd-numbered indexes are rendered to the right of the location of rows with even-numbered indexes at a distance of half the map's tilewidth attribute.