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)