Quick Start

Getting Started with tmxlite

Below is a brief overview of getting started with the tmxlite library

Building

To build tmxlite first install cmake, then execute the cmakelists.txt included in the tmxlite sub directory. On linux and macOS it would look something like:

cd tmxlite && mkdir build && cd build
cmake ..
sudo make install

The cmake variable TMXLITE_STATIC_LIB can be set to TRUE to build tmxlite as a static library. The cmake file can also be used to generate projects for IDEs such as code::blocks or Visual Studio, although there is a Visual Studio 2017 solution included in the repository, which also has a project for building tmxlite on android, as well as Windows. Arch users can also find tmxlite in the AUR. Alternatively the source files in the repository can simply be added to an existing project - all dependencies are included and no special defines are required.

Since v1.4.0 you can optionally link to external pugixml and zlib libraries, instead of the included source. This allows you to choose your own version of the dependencies, as well as adding gzip compressed map support when using zlib. To enable this set the option USE_EXTLIBS to TRUE when configuring CMake or meson. From v1.4.1 this also includes Zstd support and requires Zstd libraries to be installed. Zstd support can also be enabled separately by substituting USE_EXTLIBS for USE_ZSTD.

Usage

The tmxlite library is designed to load and parse the *.tmx xml schema used by Tiled. It supports most features, but not all, such as wang tile sets. Support may or may not be added in the future, and community contributions are welcome via Github. The library is not meant as any kind of map renderer - it merely creates a series of C++ objects which mirror the xml nodes as logically as possible. There are examples of rendering with SFML and OpenGL/SDL included in the repository but please bear in mind these are only examples to get started and will not necessarily render any or all maps as-is. To get started and load a map, then read its layer properties and tile sets one would do something like:

#include <tmxlite/Map.hpp>
#include <tmxlite/Layer.hpp>
#include <tmxlite/TileLayer.hpp>
#include <tmxlite/ObjectGroup.hpp>

int main()
{
    tmx::Map map;
    if(map.load("path/to.tmx"))
    {
        const auto& layers = map.getLayers();
        for(const auto& layer : layers)
        {
            if(layer->getType() == tmx::Layer::Type::Object)
            {
                const auto& objectLayer = layer->getLayerAs<tmx::ObjectGroup>();
                const auto& objects = objectLayer.getObjects();
                for(const auto& object : objects)
                {
                    //do stuff with object properties
                }
            }
            else if(layer->getType() == tmx::Layer::Type::Tile)
            {
                const auto& tileLayer = layer->getLayerAs<tmx::TileLayer>();
                //read out tile layer properties etc...
            }
        }

        const auto& tilesets = map.getTilesets();
        for(const auto& tileset : tilesets)
        {
            //read out tile set properties, load textures etc...
        }
    }

    return 0;
}

Note that tmx::Map objects are generally not designed to be kept around, rather they are used to load and read map file data into a format which can be easily processed, before being disposed. Layers are returned as a vector of pointers to base class - their concrete type can be found with getType() and a reference gained by calling the templated function Layer::getLayerAs<T>() with the correct type. The parse test directory contains a more detailed example.

Full API documentation for all the classes can be found online here or generated using doxygen via the configuration file in the tmxlite/documentation/ directory of the repository.