butano-tiled fixes for including object sizes

_butano-tiled tmx fixes

zlib License

(C) 2023 Adrien Plazas <[email protected]>

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

bntemplate.py

from __future__ import annotations

"""
Copyright (c) 2023 Adrien Plazas <[email protected]>
zlib License, see LICENSE file.
"""

include = '''\
/*
 * Copyright (c) 2023 Adrien Plazas <[email protected]>
 * zlib License, see LICENSE file.
 */

#ifndef BNTMX_MAP_H
#define BNTMX_MAP_H

#include <bn_affine_bg_item.h>
#include <bn_fixed_point.h>
#include <bn_fixed_size.h>
#include <bn_size.h>
#include <bn_span.h>
#include <bn_regular_bg_item.h>
#include <variant>

namespace bntmx
{

struct map_object
{
    bn::fixed_point position;
    uint16_t id;
    bn::fixed_size size;
};

typedef uint16_t map_tile;

class map
{

public:
    virtual constexpr ~map() {}

    /**
     * @brief Returns the dimensions of the map in pixels.
     */
    virtual constexpr bn::size dimensions_in_pixels() const = 0;

    /**
     * @brief Returns the dimensions of the map in tiles.
     */
    virtual constexpr bn::size dimensions_in_tiles() const = 0;

    /**
     * @brief Returns the dimensions of each tile of the map.
     */
    virtual constexpr bn::size tile_dimensions() const = 0;

    /**
     * @brief Returns the width of the map in pixels.
     */
    virtual constexpr int width_in_pixels() const = 0;

    /**
     * @brief Returns the height of the map in pixels.
     */
    virtual constexpr int height_in_pixels() const = 0;

    /**
     * @brief Returns the width of the map in tiles.
     */
    virtual constexpr int width_in_tiles() const = 0;

    /**
     * @brief Returns the height of the map in tiles.
     */
    virtual constexpr int height_in_tiles() const = 0;

    /**
     * @brief Returns the width of each tile of the map.
     */
    virtual constexpr int tile_width() const = 0;

    /**
     * @brief Returns the height of each tile of the map.
     */
    virtual constexpr int tile_height() const = 0;

    /**
     * @brief Returns the number of graphics layers of the map.
     */
    virtual constexpr int n_graphics_layers() const = 0;

    /**
     * @brief Returns the number of objects layers of the map.
     */
    virtual constexpr int n_objects_layers() const = 0;

    /**
     * @brief Returns the number of tiles layers of the map.
     */
    virtual constexpr int n_tiles_layers() const = 0;

    /**
     * @brief Returns the graphics layers of the map.
     */
    virtual constexpr  std::variant<std::monostate, bn::regular_bg_item, bn::affine_bg_item> graphics() const = 0;

    /**
     * @brief Returns the object with the given ID.
     * @param object_id ID of the objects.
     */
    virtual const bntmx::map_object object(int object_id) const = 0;

    /**
     * @brief Returns the classless objects of the given layer of the map.
     * @param objects_layer_index Index of the objects layer.
     */
    virtual const bn::span<const bntmx::map_object> objects(int objects_layer_index) const = 0;

    /**
     * @brief Returns the objects of the given class and layer of the map.
     * @param objects_layer_index Index of the objects layer.
     * @param objects_class Class of the objects.
     */
    virtual const bn::span<const bntmx::map_object> objects(int objects_layer_index, int objects_class) const = 0;

    /**
     * @brief Returns the tiles of the given layer of the map.
     * @param tiles_layer_index Index of the tiles layer.
     */
    virtual const bn::span<const bntmx::map_tile> tiles(int tiles_layer_index) const = 0;
};

}

#endif
'''

graphics = '''\
{{
    "type": "regular_bg",
    "bpp_mode": "bpp_4_auto",
    "height": {bg_height}
}}
'''

map_object = 'bntmx::map_object(bn::fixed_point({x}, {y}), {id}, bn::fixed_size({width}, {height}))'

objects_definition_template = '''\
    // Objects are sorted by layers, then within layers they are sorted by
    // classes (with classless objects first), then within classes they are
    // sorted in the order they are found.
    // Because object IDs are assigned in the same order, they are also sorted
    // by ID.
    static constexpr bntmx::map_object _objects[] = {objects};

    // This purposefully doesn't use bn::span so we can use smaller types,
    // saving ROM space.
    static constexpr struct {{uint16_t index; uint16_t length;}} _objects_spans[{n_objects_layers}][{n_objects_classes}] = {objects_spans};
'''

objects_definition_empty = '''\
    // There is no objects in this map.
'''

object_getter = '_objects[id]'

object_dummy = 'bntmx::map_object(bn::fixed_point(0, 0), 0, bn::fixed_size(0, 0))'

objects_getter_classless = 'bn::span(&_objects[_objects_spans[objects_layer_index][0].index], _objects_spans[objects_layer_index][0].length)'

objects_getter_with_class = 'bn::span(&_objects[_objects_spans[objects_layer_index][objects_class].index], _objects_spans[objects_layer_index][objects_class].length)'

objects_dummy = 'bn::span<const bntmx::map_object>()'

tiles_definition = '''\
    static const bntmx::map_tile _tiles[{n_tiles_layers}][{size}] = {tiles};
'''

tiles_getter = 'bn::span(_tiles[tiles_layer_index], {size})'

tiles_dummy = 'bn::span<const bntmx::map_tile>()'

object_classes_definition_empty = '''\
    // There is no object classes in this map.
'''

object_classes_definition_template = '''\
    enum object_class {object_classes};
'''

object_ids_definition_empty = '''\
    // There are no object IDs in this map.
'''

object_ids_definition_template = '''\
    enum object_id {object_ids};
'''

tile_ids_definition_empty = '''\
    // There are no tile IDs in this map.
'''

tile_ids_definition_template = '''\
    enum tile_id {tile_ids};
'''

header = '''\
#ifndef {guard}
#define {guard}

#include "bntmx.h"

{graphics_include}

namespace bntmx::maps
{{

class {map_name} : public bntmx::map
{{

public:
{object_classes_definition}
{object_ids_definition}
{tile_ids_definition}
    constexpr {map_name}() {{}}
    constexpr ~{map_name}() {{}}

    constexpr bn::size dimensions_in_pixels() const {{ return bn::size({width_in_pixels}, {height_in_pixels}); }}
    constexpr bn::size dimensions_in_tiles() const {{ return bn::size({width_in_tiles}, {height_in_tiles}); }}
    constexpr bn::size tile_dimensions() const {{ return bn::size({tile_width}, {tile_height}); }}
    constexpr int width_in_pixels() const {{ return {width_in_pixels}; }}
    constexpr int height_in_pixels() const {{ return {height_in_pixels}; }}
    constexpr int width_in_tiles() const {{ return {width_in_tiles}; }}
    constexpr int height_in_tiles() const {{ return {height_in_tiles}; }}
    constexpr int tile_width() const {{ return {tile_width}; }}
    constexpr int tile_height() const {{ return {tile_height}; }}
    constexpr int n_graphics_layers() const {{ return {n_graphics_layers}; }}
    constexpr int n_objects_layers() const {{ return {n_objects_layers}; }}
    constexpr int n_tiles_layers() const {{ return {n_tiles_layers}; }}
    constexpr std::variant<std::monostate, bn::regular_bg_item, bn::affine_bg_item> graphics() const {{ return {graphics}; }}

    const bntmx::map_object object(int id) const;
    const bn::span<const bntmx::map_object> objects(int objects_layer_index) const;
    const bn::span<const bntmx::map_object> objects(int objects_layer_index, int objects_class) const;
    const bn::span<const bntmx::map_tile> tiles(int tiles_layer_index) const;

}};

}}

#endif
'''

source = '''\
#include "{header_filename}"

namespace bntmx::maps
{{
{objects_definition}

{tiles_definition}

    const bntmx::map_object {map_name}::object(int id) const
    {{
        BN_ASSERT(id < {n_objects}, "Invalid object ID: ", id);
        return {object_getter};
    }}

    const bn::span<const bntmx::map_object> {map_name}::objects(int objects_layer_index) const
    {{
        BN_ASSERT(objects_layer_index < {n_objects_layers}, "Invalid objects layer index: ", objects_layer_index);
        return {objects_getter_classless};
    }}

    const bn::span<const bntmx::map_object> {map_name}::objects(int objects_layer_index, int objects_class) const
    {{
        BN_ASSERT(objects_layer_index < {n_objects_layers}, "Invalid objects layer index: ", objects_layer_index);
        BN_ASSERT(objects_class < {n_objects_classes}, "Invalid objects class: ", objects_class);
        return {objects_getter_with_class};
    }}

    const bn::span<const bntmx::map_tile> {map_name}::tiles(int tiles_layer_index) const
    {{
        BN_ASSERT(tiles_layer_index < {n_tiles_layers}, "Invalid tiles layer index: ", tiles_layer_index);
        return {tiles_getter};
    }}
}}
'''

template = {
    'header_template': header,
    'map_object_template': map_object,
    'object_classes_definition_empty': object_classes_definition_empty,
    'object_classes_definition_template': object_classes_definition_template,
    'object_ids_definition_empty': object_ids_definition_empty,
    'object_ids_definition_template': object_ids_definition_template,
    'object_dummy': object_dummy,
    'object_getter': object_getter,
    'objects_definition_empty': objects_definition_empty,
    'objects_definition_template': objects_definition_template,
    'objects_dummy': objects_dummy,
    'objects_getter_classless': objects_getter_classless,
    'objects_getter_with_class': objects_getter_with_class,
    'source_template': source,
    'tile_ids_definition_empty': tile_ids_definition_empty,
    'tile_ids_definition_template': tile_ids_definition_template,
    'tiles_definition_template': tiles_definition,
    'tiles_dummy': tiles_dummy,
    'tiles_getter_template': tiles_getter
}

bntmx.py

from __future__ import annotations

"""
Copyright (c) 2023 Adrien Plazas <[email protected]>
zlib License, see LICENSE file.
"""

from PIL import Image
from tmx import TMX
import argparse
import json
import os
import re
import bntemplate
import ctemplate

_targets = ['butano', 'c']

def write_to_file(filename: str, text: str):
    f = open(filename, "w")
    f.write(text)
    f.close()

def inline_c_array(l: list) -> str:
    """
    Return the inline C or C++ literal array or struct for the elements in the list.

    :param l: the list of the array elements
    :returns: the inline array literal
    """

    return "{" + ",".join(map(str, l)) + "}"

def multiline_c_array(l: list, indentation: str, depth: int) -> str:
    """
    Return the multiline C or C++ literal array or struct for the elements in the list.

    :param l: the list of the array elements
    :param indentation: the characters to use for an indentation level
    :param depth: the depth of the indentation
    :returns: the multiline array literal
    """

    outer_indentation = indentation * depth
    inner_indentation = indentation * (depth + 1)
    splitter = ",\n" + inner_indentation

    return "{\n" + inner_indentation + splitter.join(map(str, l)) + "\n" + outer_indentation + "}"

def bg_size(size: int):
    """
    Return a size rounded up to the next 256 multiple. This helps converting the
    size of a map into the size of its background images.

    :param size: the size of the map
    :returns: the size of the background that can fit the requested size
    """

    return size if size % 256 == 0 else (size // 256 + 1) * 256

def mangle(name: str) -> str:
    """
    Return the lowercase mangled C or C++ name for the given name.

    Names are mangled in the following way:
    - leading characters that aren't ASCII letters are trimmed
    - trailing characters that aren't ASCII letters or digits are trimmed
    - sequences of characters that aren't ASCII letters or digits are replaced
      by a single underscore character
    - letters are lowercased

    :param name: the name to mangle
    :returns: the lowercase mangled name
    """

    match = re.match('^[0-9_]*([a-z0-9_]+?)_*$', re.sub('[^a-z0-9]+', '_', name.lower()))
    return "" if match is None else match.group(1)

class TMXConverter:
    def __init__(self, target, tmx_filename):
        assert target in _targets

        self._target = target
        self._tmx = TMX(tmx_filename)
        self._basename = os.path.splitext(os.path.basename(tmx_filename))[0]
        self._name = mangle(self._basename)
        descriptor = open(os.path.splitext(tmx_filename)[0] + ".json")
        self._descriptor = json.load(descriptor)
        # Add empty lists so we don't ave to check their existence every time.
        if "graphics" not in self._descriptor:
            self._descriptor["graphics"] = []
        if "objects" not in self._descriptor:
            self._descriptor["objects"] = []
        if "tiles" not in self._descriptor:
            self._descriptor["tiles"] = []

        # The list of MapObjects for the list of object layers
        self._objects = list(map(lambda layer_path: self._tmx.objects(layer_path), self._descriptor["objects"] if "objects" in self._descriptor else []))
        self._assign_id_and_layer_to_objects()

    def _assign_id_and_layer_to_objects(self):
        object_classes = self._object_classes()
        id = 0

        # Layers are already sorted, let's first sort by layers
        for layer_index, layer_map_objects in enumerate(self._objects):
            objects = layer_map_objects.objects()

            # Then sort by classes
            for object_class in object_classes:
                if object_class not in objects:
                    continue

                # Then sort in whatever order the objects come in
                for object in objects[object_class]:
                    object.map_layer = layer_index
                    object.map_id = id
                    id += 1

    def _object_classes(self):
        # Return the sorted set of map object class names in the whole map, including the "" class
        # If there are no objects layers an empty list is returned, there is not even the "" class.

        return sorted(set([map_object_class for layer_map_objects in self._objects for map_object_class in layer_map_objects.objects().keys()]))

    def _object_classes_enum(self, namespace):
        # Return the list of enumeration definitions for the map object class names in the whole map, excluding the "" class

        return list(map(lambda i_and_object_class: namespace + mangle(i_and_object_class[1]).upper() + "=" + str(i_and_object_class[0]), enumerate(self._object_classes())))[1:]

    def _all_objects(self):
        # Return the list of map objects in the whole map

        return sorted([map_object for layer_map_objects in self._objects for _, map_objects in layer_map_objects.objects().items() for map_object in map_objects], key=lambda o: o.map_id)

    def _object_ids_enum(self, namespace):
        # Return the list of enumeration definitions for the map object ids in the whole map, excluding the None ids

        return [namespace + mangle(map_object.id).upper() + "=" + str(map_object.map_id) for map_object in self._all_objects() if map_object.id is not None]

    def _tile_ids_enum(self, namespace):
        # Return the list of enumeration definitions for the map tile ids in the whole map

        tile_ids = []
        for first, last, tsx in self._tmx.tilesets():
            enum_base = mangle(os.path.splitext(os.path.basename(tsx.filename()))[0]).upper()
            tile_ids.append(namespace + enum_base + "=" + str(first))
            tile_ids.append(namespace + enum_base + "_LAST=" + str(last))
        return tile_ids

    def _object_spans(self):
        # Return a list for each layer of lists of (index,length) pairs for each
        # object of a given class in the layer, so objects can be flattened but
        # they can still be found per layer and class.

        index_lengths = []
        index = 0
        object_classes = self._object_classes()
        for layer in self._objects:
            layer_index_lengths = []
            for object_class in object_classes:
                length = len(layer.objects()[object_class]) if object_class in layer.objects() else 0
                layer_index_lengths.append((index, length))
                index = index + length
            index_lengths.append(layer_index_lengths)
        return index_lengths

    def dependencies(self):
        return self._tmx.dependencies()

    def basename(self):
        # Return the basename of the map

        return self._basename

    def name(self):
        # Return the basename of the map

        return self._name

    def regular_bg_image(self):
        # Convert the TMX into its regular background image.

        if "graphics" not in self._descriptor or len(self._descriptor["graphics"]) == 0:
            return None

        # The size of the map, in pixels
        src_width, src_height = self._tmx.dimensions_in_pixels()
        # The size of each individual background
        bg_width, bg_height = bg_size(src_width), bg_size(src_height)

        # Compose the layers into a single background image
        n_layers = len(self._descriptor["graphics"])
        gfx_im = Image.new("RGBA", (bg_width, bg_height * n_layers), self._tmx.background_color())
        for i, layer_path in enumerate(self._descriptor["graphics"]):
            self._tmx.compose(gfx_im, layer_path, 0, bg_height * i)

        # Make the image paletted
        gfx_im = gfx_im.quantize(256)

        return gfx_im

    def regular_bg_descriptor(self):
        # Convert the TMX into its regular background descriptor.

        _, src_height = self._tmx.dimensions_in_pixels()
        bg_height = bg_size(src_height)

        return bntemplate.graphics.format(bg_height=bg_height)

    def butano_header(self):
        # Convert the TMX into its C++ header.

        n_graphics_layers = len(self._descriptor["graphics"]) if "graphics" in self._descriptor else 0
        n_objects_layers = len(self._descriptor["objects"]) if "objects" in self._descriptor else 0
        n_tiles_layers = len(self._descriptor["tiles"]) if "tiles" in self._descriptor else 0

        indentation = "    "
        if self._target == "butano":
            graphics = "bn::regular_bg_items::" + self._name if n_graphics_layers > 0 else "std::monostate()"
            graphics_include = "#include <bn_regular_bg_items_" + self._name + ".h>" if n_graphics_layers > 0 else ""
            indentation_depth = 1
            namespace = ""
            template = bntemplate.template
        elif self._target == "c":
            graphics = ""
            graphics_include = ""
            indentation_depth = 0
            namespace = "BNTMX_MAPS_" + self._name.upper() + "_"
            template = ctemplate.template

        guard = "BNTMX_MAPS_" + self._name.upper() + "_H"
        width_in_pixels, height_in_pixels = self._tmx.dimensions_in_pixels()
        width_in_tiles, height_in_tiles = self._tmx.dimensions_in_tiles()
        tile_width, tile_height = self._tmx.tile_dimensions()
        objects = self._objects

        object_classes = self._object_classes_enum(namespace)
        if len(object_classes) == 0:
            object_classes_definition = template['object_classes_definition_empty']
        else:
            object_classes_literal = multiline_c_array(object_classes, indentation, indentation_depth)
            object_classes_definition = template['object_classes_definition_template'].format(map_name=self._name, object_classes=object_classes_literal)

        object_ids = self._object_ids_enum(namespace)
        if len(object_ids) == 0:
            object_ids_definition = template['object_ids_definition_empty']
        else:
            object_ids_literal = multiline_c_array(object_ids, indentation, indentation_depth)
            object_ids_definition = template['object_ids_definition_template'].format(map_name=self._name, object_ids=object_ids_literal)

        tile_ids = self._tile_ids_enum(namespace)
        if len(tile_ids) == 0:
            tile_ids_definition = template['tile_ids_definition_empty']
        else:
            tile_ids_literal = multiline_c_array(tile_ids, indentation, indentation_depth)
            tile_ids_definition = template['tile_ids_definition_template'].format(map_name=self._name, tile_ids=tile_ids_literal)

        return template['header_template'].format(
            graphics=graphics,
            graphics_include=graphics_include,
            guard=guard,
            height_in_pixels=height_in_pixels,
            height_in_tiles=height_in_tiles,
            map_name=self._name,
            n_graphics_layers=n_graphics_layers,
            n_objects_layers=n_objects_layers,
            n_objects=len(objects),
            n_tiles_layers=n_tiles_layers,
            object_classes_definition=object_classes_definition,
            object_ids_definition=object_ids_definition,
            tile_height=tile_height,
            tile_ids_definition=tile_ids_definition,
            tile_width=tile_width,
            width_in_pixels=width_in_pixels,
            width_in_tiles=width_in_tiles)

    def butano_source(self):
        # Convert the TMX into its C++ source.

        indentation = "    "
        if self._target == "butano":
            indentation_depth = 1
            namespace = "bntmx::maps::" + self._name + "::"
            template = bntemplate.template
        elif self._target == "c":
            indentation_depth = 0
            namespace = "BNTMX_MAPS_" + self._name.upper() + "_"
            template = ctemplate.template

        header_filename = "bntmx_maps_" + self._name + ".h"

        width_in_tiles, height_in_tiles = self._tmx.dimensions_in_tiles()
        n_graphics_layers = len(self._descriptor["graphics"]) if "graphics" in self._descriptor else 0
        n_objects_layers = len(self._descriptor["objects"]) if "objects" in self._descriptor else 0
        n_tiles_layers = len(self._descriptor["tiles"]) if "tiles" in self._descriptor else 0
        size = width_in_tiles * height_in_tiles

        n_objects_classes = len(self._object_classes())
        objects_spans = multiline_c_array(map(lambda layer: multiline_c_array(map(inline_c_array, layer), indentation, indentation_depth + 1), self._object_spans()), indentation, indentation_depth)
        objects = self._all_objects()
        n_objects = len(objects)
        object_to_cpp_literal = lambda o: template['map_object_template'].format(x=o.x, y=o.y, id=o.map_id if o.id is None else namespace + str(o.id), width=o.width, height=o.height)
        objects_literal = multiline_c_array(list(map(object_to_cpp_literal, objects)), indentation, indentation_depth)

        # Get the C or C++ array literal for the given list of tiles, matching lines and columns of the map for readability.
        tiles_to_array_literal = lambda tiles: multiline_c_array([",".join(tiles[i:i + width_in_tiles]) for i in range(0, len(tiles), width_in_tiles)], indentation, indentation_depth + 1)
        # Get the C or C++ array literal of tiles for the given tiles layer path.
        tiles_layer_path_to_array_literal = lambda layer_path: tiles_to_array_literal(self._tmx.tiles(layer_path))
        # Get the C or C++ array literal of tiles layers for the given tiles layer paths.
        tiles_literal = multiline_c_array(list(map(tiles_layer_path_to_array_literal, self._descriptor["tiles"] if "tiles" in self._descriptor else [])), indentation, indentation_depth)

        if n_objects == 0 or n_objects_classes == 0 or n_objects_layers == 0:
            object_getter = template['object_dummy']
            objects_definition = template['objects_definition_empty']
            objects_getter_classless = template['objects_dummy']
            objects_getter_with_class = template['objects_dummy']
        else:
            object_getter = template['object_getter']
            objects_definition = template['objects_definition_template'].format(
                n_objects_classes=n_objects_classes,
                n_objects_layers=n_objects_layers,
                objects=objects_literal,
                objects_spans=objects_spans)
            objects_getter_classless = template['objects_getter_classless']
            objects_getter_with_class = template['objects_getter_with_class']

        if size == 0 or n_tiles_layers == 0:
            tiles_definition = ''
            tiles_getter = template['tiles_dummy']
        else:
            tiles_definition = template['tiles_definition_template'].format(
                n_tiles_layers=n_tiles_layers,
                size=size,
                tiles=tiles_literal)
            tiles_getter = template['tiles_getter_template'].format(size=size)

        return template['source_template'].format(
            header_filename=os.path.basename(header_filename),
            map_name=self._name,
            n_objects_classes=n_objects_classes,
            n_objects_layers=n_objects_layers,
            n_objects=n_objects,
            n_tiles_layers=n_tiles_layers,
            object_getter=object_getter,
            objects_getter_classless=objects_getter_classless,
            objects_getter_with_class=objects_getter_with_class,
            objects_definition=objects_definition,
            size=size,
            tiles_definition=tiles_definition,
            tiles_getter=tiles_getter,
            tiles=tiles_literal)

def process(target, maps_dirs, build_dir):
    assert target in _targets

    build_graphics_dir = os.path.join(build_dir, "graphics")
    build_include_dir = os.path.join(build_dir, "include")
    build_src_dir = os.path.join(build_dir, "src")

    if not os.path.exists(build_dir):
        os.makedirs(build_dir)
    if not os.path.exists(build_graphics_dir):
        os.makedirs(build_graphics_dir)
    if not os.path.exists(build_include_dir):
        os.makedirs(build_include_dir)
    if not os.path.exists(build_src_dir):
        os.makedirs(build_src_dir)

    # Export the global header
    include_filename = os.path.join(build_dir, "include", "bntmx.h")
    if target == "butano":
        include = bntemplate.include
    elif target == "c":
        include = ctemplate.include
    write_to_file(include_filename, include)

    for maps_dir in maps_dirs:
        for map_file in os.listdir(maps_dir):
            if map_file.endswith('.tmx') and os.path.isfile(os.path.join(maps_dir, map_file)):
                tmx_filename = os.path.join(maps_dir, map_file)
                converter = TMXConverter(target, tmx_filename)
                map_basename = converter.basename()
                map_name = converter.name()

                tmx_json_filename = os.path.join(maps_dir, map_basename + ".json")
                bmp_filename = os.path.join(build_dir, "graphics", map_name + ".bmp")
                bmp_json_filename = os.path.join(build_dir, "graphics", map_name + ".json")
                header_filename = os.path.join(build_dir, "include", "bntmx_maps_" + map_name + ".h")
                if target == "butano":
                    source_filename = os.path.join(build_dir, "src", "bntmx_maps_" + map_name + ".cpp")
                elif target == "c":
                    source_filename = os.path.join(build_dir, "src", "bntmx_maps_" + map_name + ".c")

                # Don't rebuild unchanged files
                input_mtime = max(map(lambda filename : os.path.getmtime(filename) if os.path.isfile(filename) else 0, [tmx_filename, tmx_json_filename] + converter.dependencies()))
                output_mtime = min(map(lambda filename : os.path.getmtime(filename) if os.path.isfile(filename) else 0, [bmp_filename, bmp_json_filename, header_filename, source_filename]))
                if input_mtime < output_mtime:
                    continue

                # Export the image
                gfx_im = converter.regular_bg_image()
                if gfx_im is not None:
                    gfx_im.save(bmp_filename, "BMP")
                    # Export the graphics descriptor
                    if target == "butano":
                        write_to_file(bmp_json_filename, converter.regular_bg_descriptor())

                # Export the C++ header
                write_to_file(header_filename, converter.butano_header())

                # Export the C++ source
                write_to_file(source_filename, converter.butano_source())

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Compile Tiled maps into code and data usable by the game engine.')
    parser.add_argument('--target', choices=_targets, required=True, help='build target')
    parser.add_argument('--build', required=True, help='build directory path')
    parser.add_argument('mapsdirs', metavar='mapsdir', nargs='+',
                        help='maps directories paths')
    args = parser.parse_args()
    process(args.target, args.mapsdirs, args.build)

ctemplate.py

from __future__ import annotations

"""
Copyright (c) 2023 Adrien Plazas <[email protected]>
zlib License, see LICENSE file.
"""

include = '''\
/*
 * Copyright (c) 2023 Adrien Plazas <[email protected]>
 * zlib License, see LICENSE file.
 */

#ifndef BNTMX_H
#define BNTMX_H

#include <stddef.h>
#include <stdint.h>

typedef struct
{
    int x;
    int y;
    uint16_t id;
} bntmx_map_object;

typedef uint16_t bntmx_map_tile;

typedef struct
{
    const void* data;
    size_t length;
} bntmx_span;

#endif
'''

map_object = '(bntmx_map_object) {{{x}, {y}, {id}, {width}, {height}}}'

objects_definition_template = '''\
/* Objects are sorted by layers, then within layers they are sorted by classes
 * (with classless objects first), then within classes they are sorted in the
 * order they are found.
 * Because object IDs are assigned in the same order, they are also sorted by
 * ID.
 */
static const bntmx_map_object _objects[] = {objects};

/* This purposefully doesn't use bntmx_span so we can use smaller types, saving
 * ROM space.
 */
static const struct {{uint16_t index; uint16_t length;}} _objects_spans[{n_objects_layers}][{n_objects_classes}] = {objects_spans};
'''

objects_definition_empty = '''\
/* There is no objects in this map. */
'''

object_getter = '_objects[id]'

object_dummy = '(bntmx_map_object) {0, 0, 0}'

objects_getter = '(bntmx_span) {&_objects[_objects_spans[objects_layer_index][objects_class].index], _objects_spans[objects_layer_index][objects_class].length}'

objects_dummy = '(bntmx_span) {NULL, 0}'

tiles_definition = '''\
static const bntmx_map_tile _tiles[{n_tiles_layers}][{size}] = {tiles};
'''

tiles_getter = '(bntmx_span) {{_tiles[tiles_layer_index], {size}}}'

tiles_dummy = '(bntmx_span) {NULL, 0}'

object_classes_definition_empty = '''\
/* There are no object classes in this map. */
'''

object_classes_definition_template = '''\
typedef enum {object_classes} bntmx_maps_{map_name}_object_class;
'''

object_ids_definition_empty = '''\
/* There are no object IDs in this map. */
'''

object_ids_definition_template = '''\
typedef enum {object_ids} bntmx_maps_{map_name}_object_id;
'''

tile_ids_definition_empty = '''\
/* There are no tile IDs in this map. */
'''

tile_ids_definition_template = '''\
typedef enum {tile_ids} bntmx_maps_{map_name}_tile_id;
'''

header = '''\
#ifndef {guard}
#define {guard}

#include "bntmx.h"

{object_classes_definition}
{object_ids_definition}
{tile_ids_definition}
#define bntmx_maps_{map_name}_height_in_pixels() ({height_in_pixels})
#define bntmx_maps_{map_name}_width_in_tiles() ({width_in_tiles})
#define bntmx_maps_{map_name}_height_in_tiles() ({height_in_tiles})
#define bntmx_maps_{map_name}_tile_width() ({tile_width})
#define bntmx_maps_{map_name}_tile_height() ({tile_height})
#define bntmx_maps_{map_name}_n_graphics_layers() ({n_graphics_layers})
#define bntmx_maps_{map_name}_n_objects_layers() ({n_objects_layers})
#define bntmx_maps_{map_name}_n_tiles_layers() ({n_tiles_layers})

const bntmx_map_object bntmx_maps_{map_name}_object(int id);
const bntmx_span bntmx_maps_{map_name}_objects(int objects_layer_index, int objects_class);
const bntmx_span bntmx_maps_{map_name}_tiles(int tiles_layer_index);

#endif
'''

source = '''\
#include "{header_filename}"

#include <assert.h>

{objects_definition}

{tiles_definition}

const bntmx_map_object bntmx_maps_{map_name}_object(int id)
{{
    assert(id < {n_objects});
    return {object_getter};
}}

const bntmx_span bntmx_maps_{map_name}_objects(int objects_layer_index, int objects_class)
{{
    assert(objects_layer_index < {n_objects_layers});
    assert(objects_class < {n_objects_classes});
    return {objects_getter_with_class};
}}

const bntmx_span bntmx_maps_{map_name}_tiles(int tiles_layer_index)
{{
    assert(tiles_layer_index < {n_tiles_layers});
    return {tiles_getter};
}}
'''

template = {
    'header_template': header,
    'map_object_template': map_object,
    'object_classes_definition_empty': object_classes_definition_empty,
    'object_classes_definition_template': object_classes_definition_template,
    'object_ids_definition_empty': object_ids_definition_empty,
    'object_ids_definition_template': object_ids_definition_template,
    'object_dummy': object_dummy,
    'object_getter': object_getter,
    'objects_definition_empty': objects_definition_empty,
    'objects_definition_template': objects_definition_template,
    'objects_dummy': objects_dummy,
    'objects_getter_classless': objects_getter,
    'objects_getter_with_class': objects_getter,
    'source_template': source,
    'tile_ids_definition_empty': tile_ids_definition_empty,
    'tile_ids_definition_template': tile_ids_definition_template,
    'tiles_definition_template': tiles_definition,
    'tiles_dummy': tiles_dummy,
    'tiles_getter_template': tiles_getter
}

tmx.py

from __future__ import annotations

"""
Copyright (c) 2023 Adrien Plazas <[email protected]>
zlib License, see LICENSE file.
"""

from PIL import Image
import logging
import os
import PIL
import xml.etree.ElementTree as ET

def _bg_size(size: int):
    """
    Return a size rounded up to the next 256 multiple. This helps converting the
    size of a map into the size of its background images.

    :param size: the size of the map
    :returns: the size of the background that can fit the requested size
    """

    return size if size % 256 == 0 else (size // 256 + 1) * 256

def _object_position(object_node: ET.Element) -> tuple[int,int]:
    """
    Return the center position of an object.

    :param object_node: the node of the object
    :returns: the abscissa and ordinate of the center of the object
    """

    # While the origin of maps is their top-left corner, the origin of
    # objects is their bottom left one, hence we have to substract half
    # their height and not add it to get their center.
    x = int(float(object_node.get("x"))) + int(float(object_node.get("width"))) // 2
    y = int(float(object_node.get("y"))) - int(float(object_node.get("height"))) // 2
    return x, y

def _object_size(object_node: ET.Element) -> tuple[int,int]:
    """
    Return the size of an object.

    :param object_node: the node of the object
    :returns: the width and height of the object
    """

    width = int(float(object_node.get("width")))
    height = int(float(object_node.get("height")))
    return width, height

def _objects_layer_path_to_xpath(layer_path: str) -> str:
    """
    Return the XPath to the node of the given objects layer path from the JSON descriptor.

    :param layer_path: the path to the objects layer
    :returns: the XPath
    """

    layer_path_elements = layer_path.split("/")
    xpath = "."
    for group in layer_path_elements[:-1]:
        xpath += "/group[@name='" + group + "']"
    xpath += "/objectgroup[@name='" + layer_path_elements[-1] + "']"

    return xpath

def _tiles_layer_path_to_xpath(layer_path: str) -> str:
    """
    Return the XPath to the node of the given tiles layer path from the JSON descriptor.

    :param layer_path: the path to the tiles layer
    :returns: the XPath
    """

    layer_path_elements = layer_path.split("/")
    xpath = "."
    for group in layer_path_elements[:-1]:
        xpath += "/group[@name='" + group + "']"
    xpath += "/layer[@name='" + layer_path_elements[-1] + "']"

    return xpath

class MapObject:
    def __init__(self, x: int, y: int, id: int, object_class: str, width: int, height: int):
        """
        :param x: the abscissa of the center of the object
        :param y: the ordinate of the center of the object
        :param id: the ID of the oject
        :param object_class: the class of the object
        :param width: the width of the object
        :param height: the height of the object
        """

        self.x = x
        self.y = y
        self.id = id
        self.object_class = object_class
        self.width = width
        self.height = height

class MapObjects:
    def __init__(self):
        self._map_objects = {"": []}

    def add(self, map_object: MapObject):
        """
        Add an object for the given class.

        :param map_object: the object
        """

        if map_object.object_class in self._map_objects:
            self._map_objects[map_object.object_class].append(map_object)
        else:
            self._map_objects[map_object.object_class] = [map_object]

    def ids(self) -> list[int]:
        """
        Return a list the ids of all map objects.

        :returns: a list the ids of all map objects
        """

        return [map_object.id for _, map_objects_list in self._map_objects.items() for map_object in map_objects_list]

    def objects(self) -> dict[str,list[MapObject]]:
        """
        Return the dict of objects per class.

        :returns: the dict of objects per class
        """

        return self._map_objects

class TSX:
    def __init__(self, filename: str):
        """
        :param filename: the filename of the *.tsx file to parse
        """

        self._filename = os.path.realpath(filename)
        self._root = ET.parse(filename)

        self._n_tiles = int(self._root.find(".").get("tilecount"))
        self._tile_width = int(self._root.find(".").get("tilewidth"))
        self._tile_height = int(self._root.find(".").get("tileheight"))
        self._columns = int(self._root.find(".").get("columns"))
        self._lines = self._n_tiles // self._columns
        self._image = Image.open(self.image_filename())

    def filename(self) -> str:
        """
        Return the filename of the *.tsx file.

        :returns: the filename of the *.tsx file
        """

        return self._filename

    def image_filename(self) -> str:
        """
        Return the filename of the tileset's image.

        :returns: the filename of the tileset's image
        """

        directory = os.path.dirname(self._filename)
        return os.path.join(directory, self._root.find("./image").get("source"))

    def n_tiles(self) -> int:
        """
        Return the number of tiles in the set.

        :returns: the number of tiles in the set
        """

        return self._n_tiles

    def compose(self, dst_image: PIL.Image.Image, tile_id: int, x: int, y: int):
        """
        Compose a tile on an image.

        :param dst_image: the image to draw the tile on
        :param tile_id: the ID of the tile to draw
        :param x: the abscissa of the top-left corner from which to draw
        :param y: the ordinate of the top-left corner from which to draw
        """

        src_x = (tile_id % self._columns) * self._tile_width
        src_y = (tile_id // self._columns) * self._tile_height
        dst_image.alpha_composite(self._image, (x, y), (src_x, src_y, src_x + self._tile_width, src_y + self._tile_height))

class TMX:
    def __init__(self, filename: str):
        """
        :param filename: the filename of the *.tmx file to parse
        """

        self._filename = os.path.realpath(filename)
        self._root = ET.parse(self._filename)

        self._columns = int(self._root.find(".").get("width"))
        self._lines = int(self._root.find(".").get("height"))

        self._tile_width = int(self._root.find(".").get("tilewidth"))
        self._tile_height = int(self._root.find(".").get("tileheight"))

        directory = os.path.dirname(self._filename)
        self._tilesets = []
        for tileset in self._root.findall("./tileset"):
            source = tileset.get("source")
            if source and not os.path.basename(source).startswith("_"):
                tsx = TSX(os.path.join(directory, source))
                first_id = int(tileset.get("firstgid"))
                last_id = first_id + tsx.n_tiles() - 1
                self._tilesets.append((first_id, last_id, tsx))

    def dependencies(self) -> list[str]:
        """
        Return the list of filenames the map depends on.

        :returns: the list of filenames the map depends on
        """

        deps = []
        for first, last, tsx in self._tilesets:
            deps.append(tsx.filename())
            deps.append(tsx.image_filename())
        return deps

    def dimensions_in_pixels(self) -> tuple[int,int]:
        """
        Return the width and height of the map in pixels.

        :returns: the width and height of the map in pixels
        """

        return (self._columns * self._tile_width, self._lines * self._tile_height)

    def dimensions_in_tiles(self) -> tuple[int,int]:
        """
        Return the width and height of the map in tiles.

        :returns: the width and height of the map in tiles
        """

        return (self._columns, self._lines)

    def tile_dimensions(self) -> tuple[int,int]:
        """
        Return the width and height of the tiles in pixel.

        :returns: the width and height of the tiles in pixel
        """

        return (self._tile_width, self._tile_height)

    def background_color(self) -> str:
        """
        Return the background color hex code of the map, with the # prefix.

        :returns: the background color hex code
        """

        return self._root.find(".").get("backgroundcolor")

    def tilesets(self) -> list[tuple[int,int,TSX]]:
        """
        Return the list of tilesets consisting of their first ID in the map,
        their last ID in the map, and their TSX object.

        :returns: the tilesets
        """

        return self._tilesets

    def objects(self, layer_paths: list[str]|str) -> MapObjects:
        """
        Return the objects of layers. The objects are sorted by class in a dict.

        :param layer_paths: the paths (or single path) to the objects layers
        :returns: the objects
        """

        if isinstance(layer_paths, str):
            layer_paths = [layer_paths]

        objects = MapObjects()
        for layer_path in layer_paths:
            layer_xpath = _objects_layer_path_to_xpath(layer_path)
            layer_node = self._root.find(layer_xpath)
            if layer_node is None:
                logging.critical(self._filename + ": " + layer_path + ": Not an objects layer path")
                exit(1)

            xpath = layer_xpath + "/object"
            for item_node in self._root.findall(xpath):
                item_id = item_node.get("name")
                item_class = item_node.get("type")
                item_class = "" if item_class is None else item_class
                item_x, item_y = _object_position(item_node)
                item_width, item_height = _object_size(item_node)
                objects.add(MapObject(item_x, item_y, item_id, item_class, item_width, item_height))
        return objects

    def compose(self, dst_image: PIL.Image.Image, layer_paths: list[str]|str, x: int, y: int):
        """
        Compose layers on an image. Each layer in composed over the previous ones.

        :param dst_image: the image to draw the layers on
        :param layer_paths: the paths (or single path) to the graphics layers
        :param x: the abscissa of the top-left corner from which to draw
        :param y: the ordinate of the top-left corner from which to draw
        """

        if isinstance(layer_paths, str):
            layer_paths = [layer_paths]

        for layer_path in layer_paths:
            layer_xpath = _tiles_layer_path_to_xpath(layer_path)
            layer_node = self._root.find(layer_xpath)
            if layer_node is None:
                logging.critical(self._filename + ": " + layer_path + ": Not a graphics layer path")
                exit(1)

            xpath = layer_xpath + "/data[@encoding='csv']"
            node = self._root.find(xpath)
            if node is None:
                logging.critical(self._filename + ": " + layer_path + ": Invalid graphics layer path, expected CSV-encoded data")
                exit(1)

            # The size of the map, in pixels
            src_width, src_height = self.dimensions_in_pixels()
            # The size of each individual background
            bg_width, bg_height = _bg_size(src_width), _bg_size(src_height)
            # The offset to center the layer on the background
            offset_x, offset_y = (bg_width - src_width) // 2, (bg_height - src_height) // 2

            y2 = 0
            for line in iter(node.text.splitlines()):
                if line == '':
                    continue;

                x2 = 0
                for tile_id in line.split(","):
                    if tile_id == '':
                        continue;

                    tile_id = int(tile_id)

                    if tile_id != 0:
                        for first, last, tsx in self._tilesets:
                            if tile_id >= first and tile_id <= last:
                                tsx.compose(dst_image, tile_id - first, x + x2 * self._tile_width + offset_x, y + y2 * self._tile_height + offset_y)

                    x2 = x2 + 1
                y2 = y2 + 1

    def _tiles(self, layer_path: str) -> list[str]:
        """
        Return the tiles of a layer.

        :param layer_path: the path to the tiles layer
        :returns: the tiles
        """

        # Parse the CSV tiles data to turn in into a Python list of tile IDs.
        line_is_not_empty = lambda line: line != ''

        layer_xpath = _tiles_layer_path_to_xpath(layer_path)
        layer_node = self._root.find(layer_xpath)
        if layer_node is None:
            logging.critical(self._filename + ": " + layer_path + ": Not a tiles layer path")
            exit(1)

        xpath = layer_xpath + "/data[@encoding='csv']"
        node = self._root.find(xpath)
        if node is None:
            logging.critical(self._filename + ": " + layer_path + ": Invalid tiles layer path, expected CSV-encoded data")
            exit(1)

        lines = filter(line_is_not_empty, node.text.splitlines())
        tiles = [str(int(tile)) for line in lines for tile in line.strip(",").split(",")]

        # Check the list of tile IDs is valid.
        n_tiles = len(tiles)
        expected_n_tiles = self._columns * self._lines
        if n_tiles != expected_n_tiles:
            logging.critical(self._filename + ": " + layer_path + ": Invalid number of tiles, expected " + str(expected_n_tiles) + ", got " + str(n_tiles))
            exit(1)

        return tiles

    def tiles(self, layer_paths: list[str]|str) -> list[str]:
        """
        Return the tiles of layers. The latest non-empty tile is used for each layer.

        :param layer_paths: the paths (or single path) to the tiles layers
        :returns: the tiles
        """

        if isinstance(layer_paths, str):
            return self._tiles(layer_paths)

        n_tiles = self._columns * self._lines
        n_layers = len(layer_paths)
        # Reversed so we can look for non-empty tiles starting from the topmost layer
        tiles_layers = reversed(list(map(self._tiles, layer_paths)))
        tiles = []
        for i in range(0, n_tiles):
            tile = '0'
            for tiles_layer in tiles_layers:
                if tiles_layer[i] != '0':
                    tile = tiles_layer[i]
                    # We can stop here because we look from the topmost layer
                    break
            tiles.append(tile)

        return tiles