Tileson

Tileson is a modern and helpful cross-platform json-parser for C++, used for parsing Tiled maps.

Tileson utilizes modern C++ (C++17) to create a stable, safe and helpful, but fast, parser for Tiled maps. Including classes and functions to make it easier to use the Tiled data in your game. Tileson supports Tiled maps up to version 1.10.2, but will probably be able to parse maps made with newer versions of Tiled just as well.

Be sure to take a look at the release notes to see what's new!

Tileson is header-only

This means that all you need is one file, tileson.hpp to have Tileson going in your project! The single-file is generated using only ~7000 lines of code with everything included. There is also a tileson_min.hpp where no Json parser is bundled. See the extras folder for supported Json backends.

You may alternatively copy the include directory and all its contents if you want to have every component in their own file. This will probably be less heavy on your IDE, but you will still only need to include the tileson.h file in the top level.

Content:

• Tileson
  • Tileson is header-only
• Documentation
  • IMPORTANT: Tileson requires that everything it needs in a map is embedded into it, to be able to resolve their related objects (with the exception of external Tilesets, which is supported in json format since v1.3.0). Maps having dependencies to external objects etc. will not work properly.
• How to contribute
• Unreleased features available in the master-branch
• What is new in v1.4.0
• Tiled features not yet supported
• What is Tiled?
• How to parse Tiled maps
  • Another quick example to showcase how to get data that can be used to produce drawable objects:
  • Parsing worlds
  • Parsing Tiled-projects
  • Using Tiled's class and enum types in Tiled-projects
  • Parsing LZMA compressed maps
  • Using an alternative Json parser
• Compiling
  • Windows
    • Locate the CMakeLists.txt in the root of this project
    • Configure build to be x86 or x64
    • And then
    • Output after full build
  • Linux
  • OSX
• Examples
• Generating the single-header
• Libraries used by Tileson
  • Optional Json parsers supported by Tileson
• Libraries used in examples

Documentation

There is a Doxygen generated documentation of Tileson that can be found HERE

IMPORTANT: Tileson requires that everything it needs in a map is embedded into it, to be able to resolve their related objects (with the exception of external Tilesets, which is supported in json format since v1.3.0). Maps having dependencies to external objects etc. will not work properly.

How to contribute

You are free to post any issue requesting new features, reporting bugs or asking questions at any time. If you want to contribute in the development of Tileson, make sure you read the CONTRIBUTION GUIDELINES before you start doing anything.

Unreleased features available in the master-branch

• Added support for Image Collection Tilesets (#117, #30) - Thanks to twje
• Fix: Demo - Tiles rotated to 90 and 270 degrees display incorrectly (#116) - Thanks to twje
• Generated tiles are now considering local IDs (#112, #114) - Thanks to twje
• Tile::getDrawingRect() is now based on tile grid size (previously map grid size) (#109) - Thanks to tmpsantos
• A new function Tileset::getFullImagePath() to retrieve a full path to an image based on the loaded map. Tileset::getImagePath() still returns a relative path. (#107) - Thanks to tmpsantos
• Attributes of classes set as properties return zero where overridden (#105) - Thanks to tmpsantos

What is new in v1.4.0

• Fixed bug where template objects did not correctly override properties (#100) - Thanks to jpeletier
• Fixed bugs related to not being able to resolve TiledEnums in certain contexts (#98)
• Fix: Only include external_libs folder if examples or tests are required (#96) - Thanks to Laguna1989
• Tests are now stricter and treats warnings as errors (#90) - Thanks to dmlary
• CI improvements: Added MacOS, separated CI by system and added Clang 12 and 13 support on Linux (#88)
• Fixed some Apple Clang 13 compile warnings (#84) - Thanks to dmlary
• Added quom as amalgamate tool for OSX (#82) - Thanks to dmlary
• Added missing properties to tson::Text (#75)
• Tiled 1.9 support (#68)
• Tiled 1.8 support (#60)
• C++20 support (#53) - Thanks to gamecoder-nz
• Updated Catch2 to support GCC 11.2 (#59)
• Tile properties should now be properly loaded when using multiple tilesets. (#54) - Thanks to Laguna1989
• Now using Github Actions instead of Travis for CI (#50) - Thanks to Laguna1989
• Added missing virtual destructor to IJson and IDecompressor. (#47) - Thanks to matthew-nagy

Tiled features not yet supported

• Isometric maps are untested, and most likely does not work 100% (#97)

What is Tiled?

Tiled is a general purpose map editor developed by Thorbjørn Lindeijer. Tiled is perfect if you want to create any map for 2D games, and is very popular. Many commercial games have used it as their goto map editor. A few popular games that have used Tiled: Shovel Knight, Axiom Verge and ScubaDiver.

Tiled can be found here:

• Homepage
• GitHub

How to parse Tiled maps

Parsing a Tiled json

#include "tileson.hpp"

//Tileson uses an alias fs for std::filesystem.
int main()
    tson::Tileson t;
    std::unique_ptr<tson::Map> map = t.parse(tson_files::_ULTIMATE_TEST_JSON, tson_files::_ULTIMATE_TEST_JSON_SIZE);

    if(map->getStatus() == tson::ParseStatus::OK)
    {
        //Get color as an rgba color object
        tson::Colori bgColor = map->getBackgroundColor(); //RGBA with 0-255 on each channel

        //This color can be compared with Tiled hex string
        if (bgColor == "#ffaa07")
            printf("Cool!");

        //Or you can compare them with other colors
        tson::Colori otherColor{255, 170, 7, 255};
        if (bgColor == otherColor)
            printf("This works, too!