tinytmx

Description

A C++17 library to parse maps generated by Tiled Map Editor. Fully supports TMX Map Format version 1.5.

Features

• Conformity with the TMX specification page.
  • (Currently supports TMX Map Format version 1.5. Earlier versions are not officially supported.)

Requirements

The library requires C++17 to build, including compiler and standard library support.

Dependencies

Library	Version
TinyXML2	9.0.0
zlib	1.3.1
zstd	1.5.2

Build with Docker (recommended for isolated builds)

If you prefer not to install Conan and build dependencies on your host machine, use the provided Dockerfile and docker-compose.yml.

Prerequisites:

• Docker
• Docker Compose plugin (docker compose)

From the repository root:

# Build the image, install dependencies in-container, configure, build, and run tests.
docker compose up --build

What this does:

• Builds inside a Debian-based container.
• Resolves C++ dependencies with Conan inside the container.
• Writes project build artifacts to the host build/ directory through the bind mount.
• Runs tests with CTest.

Expected success output includes:

• Built target tinytmx
• Built target tinytmxlibtest
• 100% tests passed

Install and artifact location with Docker

If you also want an installed layout (headers, library, CMake package files), run:

docker compose run --rm tinytmx bash -lc "
/opt/venv/bin/conan profile detect --force &&
/opt/venv/bin/conan install . --output-folder=build -pr:h=default -pr:b=default -s build_type=Release -s compiler.libcxx=libstdc++11 -s compiler.cppstd=17 --build=missing &&
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=/workspace/build/conan_toolchain.cmake -DCMAKE_INSTALL_PREFIX=/workspace/dist &&
cmake --build build &&
cmake --install build
"

Because the repository is bind-mounted as /workspace in the container, the install output appears on the host at ./dist.

Notes:

• Project build artifacts are in ./build.
• Conan dependency packages are in the container Conan cache (for example /root/.conan2) unless a dedicated Conan cache volume is mounted.

Installation

This describes the installation process using cmake. As pre-requisites, you'll need git and cmake installed.

# Check out the library.
$ git clone https://github.com/KaseyJenkins/tinytmx.git
# Go to the library root directory
$ cd tinytmx
# Make a build directory to place the build output.
$ cmake -E make_directory "build"
# Generate build system files with cmake.
$ cmake -E chdir "build" cmake -DCMAKE_BUILD_TYPE=Release ../
# or, starting with CMake 3.13, use a simpler form:
# cmake -DCMAKE_BUILD_TYPE=Release -S . -B "build"
# Build the library.
$ cmake --build "build" --config Release

If you want to install the library globally, run:

sudo cmake --build "build" --config Release --target install

Usage

Basic usage

Parsing a Tiled TMX Map:

#include <string>
#include "tinytmx.hpp"

int main(int argc, char * argv[]) {
    
    tinytmx::Map *map = new tinytmx::Map();
    std::string fileName = "assets/FiniteOrthogonalMap.tmx";
    map->ParseFile(fileName);
    
}

Usage with CMake

If using CMake, it is recommended to link against the project-provided tinytmx::tinytmx target using target_link_libraries.

It is possible to use find_package to import an installed version of the library.

find_package(tinytmx REQUIRED)

Alternatively, add_subdirectory will incorporate the library directly into one's CMake project.

add_subdirectory(tinytmx)

Either way, link to the library as follows.

target_link_libraries(MyTarget tinytmx::tinytmx)