mapeditor / mapeditor/tiled

JSON & TMX Format Documentation is Missing the Maths

Open
#1,608 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
C++
Stars
12.9k
Forks
2k
Avg merge
4h 27m
Merged PRs (30d)
8

Description

The math behind how to derive the X and Y offset for a tile is missing from the documentation. While anyone with a computer science degree or anyone that has been doing game programming for a while should be able to just figure this out, this does leave a gap of information for people that haven't been doing this.

I propose adding a math section the breaks down the process maybe. Something in the following format.

## Normalizing the (tile id) GID
`normalized_tile_id = tile_id - firstgid`
## Solving for the X Offset
`normalized_tile_id * tilewidth % tileset_width`
## Solving for the Y Offset
`Math.floor( ( normalized_tile_id * tilewidth ) / tileset_width) * tileheight`
## Considerations for Margins
_not 100% sure on the math for this_

Something like this would be helpful to anyone that just wants to be able to parse in maps made with Tiled because it lowers the threshold to entry, which in turn makes it more likely for support to be more wide-spread.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Locate the JSON and TMX format documentation and identify where tile GID normalization and tile offsets are explained. Add a math section covering the proposed X and Y calculations, then verify the formulas and document how margins affect them; the documentation should let readers derive offsets without prior game-programming experience.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.