Карта из Tiled в браузерной игре: формат JSON, слои тайлов и объекты

Коротко

Карта из Tiled в формате JSON (TMJ) — это размеры сетки, массив слоёв и массив тайлсетов: в слое тайлов на каждую клетку приходится одно число GID, в слое объектов — список объектов с координатами в пикселях и свойствами. Чтобы нарисовать клетку, из GID сначала снимают четыре старших бита флагов отражения, потом выбирают тайлсет с наибольшим firstgid, не большим GID, и вычисляют место тайла в картинке по columns, margin и spacing. У тайлового объекта точка привязки — нижний левый угол, у прямоугольника — верхний левый, а слои рисуют в том порядке, в каком они лежат в массиве. При загрузке проверяют, что в data ровно width × height чисел и что каждый GID попадает в свой тайлсет.

Содержание

  1. Что такое TMJ и как его получить
  2. Из чего состоит файл карты
  3. GID: какой тайл стоит в клетке
  4. Где тайл лежит в картинке: columns, margin, spacing
  5. Слой объектов: координаты и свойства
  6. Коллизии: отдельный слой или свойство тайла
  7. Порядок отрисовки слоёв
  8. Проверка данных при загрузке
  9. Если data — строка: base64 и сжатие
  10. Код на JavaScript
  11. Проверка в Node.js
  12. Что показал прогон: пять ловушек
  13. Что не подтвердилось и где мы поправили себя по документации
  14. Практический сценарий: подключить карту левел-дизайнера
  15. Когда вам это не подойдёт

Что такое TMJ и как его получить

TMJ — это карта Tiled, сохранённая в формате JSON; расширения .tmj для карт, .tsj для тайлсетов и .tj для шаблонов редактор принимает с версии 1.8 (февраль 2022 года). По документации, карту в JSON сохраняют через File > Export As с типом файла JSON или из командной строки с ключом --export-map, а сам формат поддерживает все возможности Tiled. Документация прямо пишет, что в браузере и вообще в JavaScript формат JSON загружать проще, чем TMX: это обычный JSON.parse, без разбора XML.

Чем тайловая сетка удобна и как устроены тайловые миры вообще, мы разбирали в статье про тайловые сетки. Здесь — практика: как прочитать то, что сохранил редактор, и нарисовать это на canvas.

Из чего состоит файл карты

Файл карты — объект с размерами сетки, массивом layers и массивом tilesets; всё остальное для простой ортогональной карты можно пока не читать. Ниже — поля, которые нужны нашему загрузчику, с описанием по странице JSON Map Format документации Tiled 1.12.2.

ГдеПолеЧто значит
картаwidth, heightчисло столбцов и строк в клетках
картаtilewidth, tileheightразмер клетки сетки в пикселях
картаorientationorthogonal, isometric, oblique, staggered или hexagonal
картаrenderorderпорядок клеток внутри слоя: right-down (по умолчанию), right-up, left-down, left-up; только для ортогональных карт
слойtypetilelayer, objectgroup, imagelayer или group
tilelayerdataмассив GID или строка base64
tilelayerencoding, compressioncsv (по умолчанию) или base64; zlib, gzip, zstd или пусто
objectgroupobjects, draworderсписок объектов; topdown (по умолчанию) или index
тайлсетfirstgidGID первого тайла этого набора
тайлсетimage, imagewidth, imageheightкартинка набора и её размер
тайлсетcolumns, tilecountстолбцов тайлов в картинке и всего тайлов
тайлсетmargin, spacingотступ от края картинки до первого тайла и зазор между тайлами, px
тайлсетtilesнеобязательный список тайлов со свойствами, анимацией или формами коллизий

Наша синтетическая карта в прогоне — 32×18 клеток по 16×16 px, то есть 512×288 px, с тремя тайлсетами и четырьмя слоями: ground (фон и стены), deco (украшения), скрытый collision и слой объектов objects. Все числа ниже — из прогона на этой карте, её генерирует сам тест, внешних файлов нет.

GID: какой тайл стоит в клетке

В клетке слоя тайлов лежит GID — номер тайла, общий для всех тайлсетов карты, а 0 означает пустую клетку. Клетки идут по строкам: клетка (x, y) — элемент data[y * width + x]. Документация описывает порядок разбора GID так: сначала прочитать и снять флаги отражения, потом определить тайлсет, потом номер тайла в нём.

Флаги отражения в старших битах

Четыре старших бита 32-битного GID — флаги, и их снимают до поиска тайлсета. По документации: бит 32 — отражение по горизонтали, бит 31 — по вертикали; на ортогональных и изометрических картах бит 30 — отражение по диагонали (через него Tiled делает повороты), а бит 29 можно не читать. На гексагональных картах бит 30 означает поворот на 60° по часовой стрелке, а бит 29 — на 120°.

БитМаскаОртогональная и изометрическая картаГексагональная карта
320x80000000отражение по горизонтали (H)то же
310x40000000отражение по вертикали (V)то же
300x20000000отражение по диагонали (D)поворот на 60°
290x10000000не используется, но снимать обязательноповорот на 120°

Бит 29 нужно снимать и на обычной карте: документация предупреждает, что Tiled сохраняет этот флаг, даже если ориентацию карты поменяли, и без снятия получится неверный номер тайла. Пример из прогона: число 2684354565 — это 0xA0000005, то есть GID 5 с флагами H и D.

gid = raw & 0x0FFFFFFF        // снять все четыре флага
h = raw & 0x80000000;  v = raw & 0x40000000;  d = raw & 0x20000000

В JavaScript побитовые операции работают со знаковыми 32-битными числами, поэтому результат приводят к беззнаковому через >>> 0 — иначе 0x80000000 превратится в отрицательное число.

Рисуют отражённый тайл в строгом порядке: по документации, для ортогональных и изометрических тайлов сначала выполняют диагональное отражение (оно меняет местами нижний левый и верхний правый углы — по сути, обмен осей x и y), а потом горизонтальное и вертикальное. На canvas это значит, что преобразование диагонали должно стоять ближе всего к drawImage: последнее заданное преобразование применяется к точкам картинки первым.

Тайлсет по firstgid

Тайлсет клетки — тот, у которого наибольший firstgid, не больший GID, а номер тайла внутри набора — GID минус этот firstgid. У первого тайлсета firstgid всегда 1. Пример из документации: при наборах с firstgid 1, 65 и 115 тайл с GID 72 принадлежит второму набору и имеет в нём номер 7.

В нашей карте: terrain — firstgid 1, GID 1–64; deco — firstgid 65, GID 65–80; tall — firstgid 81, GID 81–88, тайлы 16×32. GID 70 — это deco №5, GID 85 — tall №4. Документация отдельно напоминает: GID «глобальны» только внутри одной карты — в другой карте с другим набором или порядком тайлсетов тот же тайл получит другой номер.

Где тайл лежит в картинке: columns, margin, spacing

Тайл с номером local лежит в картинке в столбце local % columns и строке floor(local / columns), а его левый верхний угол считается с учётом отступа от края и зазоров между тайлами:

sx = margin + (local % columns) × (tilewidth + spacing)
sy = margin + floor(local / columns) × (tileheight + spacing)

У terrain в нашей карте margin 1 и spacing 2, картинка 144×144 px: тайл №0 начинается в точке (1, 1), а тайл №63 в правом нижнем углу — в точке (127, 127). Без зазоров формула дала бы (112, 112) — на 15 px левее и выше. В документации к учебному примеру сказано, что тайлсет с отступом и зазором встречается редко и обычно оба значения оставляют равными 0, но если они заданы, их обязательно учитывать. Как картинки тайлсетов занимают видеопамять и зачем их собирают в атласы, разобрано в статье про память текстур.

Слой объектов: координаты и свойства

У объекта в слое objectgroup координаты x и y — в пикселях карты (дробные числа), а что именно они обозначают, зависит от вида объекта. У прямоугольника это верхний левый угол. У тайлового объекта — объекта с полем gid, который рисуется картинкой тайла, — на ортогональной карте это нижний левый угол, на изометрической — середина нижнего края. С Tiled 1.4 у тайлсета есть поле objectalignment; по умолчанию оно unspecified, и тогда действует то же правило: bottomleft для ортогональной карты и bottom для изометрической.

прямоугольник:     верх = y,           низ = y + height
тайловый объект:   верх = y − height,  низ = y
точка (point):     x, y — сама точка, width и height равны 0

В прогоне персонаж player — тайловый объект 16×32 с x 48 и y 272: его рамка — от y 240 до y 272, ноги стоят на верхней грани нижней стены. Прямоугольник exit с x 464, y 224 и размером 32×48 занимает y 224–272.

Свойства объекта, слоя, карты или тайла в JSON — не объект, а массив записей {name, type, value}; тип — string (по умолчанию), int, float, bool, color, file, object или class. Удобнее сразу превратить массив в обычный объект: из [{name: "hp", type: "int", value: 5}] получится {hp: 5}. Как связывать объекты уровня между собой через свойства-ссылки, мы показывали в статье про связи объектов в данных уровня — здесь только чтение.

Коллизии: отдельный слой или свойство тайла

Твёрдые клетки берут либо из отдельного слоя тайлов, который не рисуют, либо из свойства самого тайла в тайлсете. Документация называет оба пути: информацию о коллизиях часто передают через специальный тайлсет в слое тайлов, а в тайлсете можно задать тайлам свойства и формы коллизий в редакторе Tile Collision Editor.

  • Слой коллизий. Скрытый слой collision (visible: false): любая непустая клетка — стена. Левел-дизайнер может поставить невидимый барьер, не меняя картинку.
  • Свойство тайла. В tiles тайлсета у стен свойство solid: true; твёрдость клетки берут из тайла в слое ground. Стена всегда там, где нарисована стена.

Поле tiles — разреженный список: в нём только тайлы, у которых что-то задано, и номер тайла лежит в поле id, а не в позиции в массиве. В нашем terrain 9 записей на 64 тайла, и tiles[1] — это тайл №8. Готовая сетка твёрдых клеток подходит и для поиска пути — как в статье про A* на тайловой сетке.

Порядок отрисовки слоёв

Слои рисуют в том порядке, в каком они лежат в массиве layers: первый — самый нижний. Так сказано и в руководстве (порядок слоёв определяет порядок отрисовки), и в описании TMX, поля которого по смыслу совпадают с JSON. Группы слоёв (type: "group") раскрывают по порядку, вложенные слои — внутри группы.

Внутри слоя тайлов порядок клеток задаёт renderorder; он важен, только когда тайлы перекрываются. По описанию TMX, тайлы крупнее клетки сетки растут вверх и вправо от нижнего левого угла клетки — поэтому высокий тайл 16×32 налезает на клетку над собой. Порядок объектов в слое задаёт draworder: topdown — по координате y, index — по порядку в списке; наш код рисует объекты по порядку в списке, как index.

Проверка данных при загрузке

Карту проверяют сразу после загрузки, до первой отрисовки: формат data, её длину и каждый GID. Пример кода в документации прямо советует проверять размер данных, и это дешевле, чем потом искать, почему уровень съехал на одну клетку.

  1. data — массив, а не строка; если строка, слой сохранён в base64 (о нём — ниже).
  2. data.length === width × height для слоёв конечной карты.
  3. Каждый ненулевой GID после снятия флагов попадает в тайлсет: GID − firstgid < tilecount.

В прогоне на испорченной копии карты проверка нашла все три подложенные ошибки: GID 200 в клетке (8,1), GID 90 в клетке (9,1) (последний тайлсет кончается на 88) и 575 чисел вместо 576 в слое deco.

Если data — строка: base64 и сжатие

Мы разбираем только формат слоя CSV, когда data в JSON — обычный массив чисел; base64 и сжатие наш загрузчик честно отклоняет с сообщением. По документации, data бывает массивом GID или строкой base64 с необязательным сжатием zlib, gzip или zstd (zstd с Tiled 1.3); в base64 каждый GID занимает 4 байта в порядке little-endian. Формат слоя тайлов (Tile layer format) выбирают в диалоге New Map, и, по документации, его можно поменять позже — поставьте CSV, и в JSON окажется массив.

В прогоне base64 без сжатия раскодировался в те же 576 чисел, что и массив, так что GID и флаги в нём те же. Нужен ли он вам — вопрос размера файла: данные слоя ground в массиве заняли 1693 символа, в base64 — 3072, в base64 со сжатием zlib — 744.

Не путайте с отдельным экспортом в CSV (File > Export As > CSV): он сохраняет только слои тайлов, по файлу на слой, и пустые клетки там записаны как -1, а не 0.

Код на JavaScript

Пример — два файла: tiledmap.mjs с загрузчиком и test.mjs, который строит синтетическую карту и прогоняет проверки по разделам. Нужен Node.js 24; запуск — node test.mjs. Случайность только из генератора с зерном, файлов и сети нет, поэтому вывод повторяется байт в байт.

Опции включают ошибки для ловушек: keepFlags — флаги не снимаются, threeFlags — снимаются только H, V и D без бита 29, firstOnly — всегда первый тайлсет, noGaps — без margin и spacing, tileTopLeft — тайловый объект по верхнему левому углу, byIndex — свойства тайла по позиции в tiles, diagonalLast — диагональ после H и V.

// tiledmap.mjs — чтение карты Tiled в формате JSON (TMJ) и отрисовка на canvas; без зависимостей
// Флаги отражения — четыре старших бита 32-битного GID (документация Tiled, Global Tile IDs)
export const FLIP_H = 0x80000000;    // бит 32: отражение по горизонтали
export const FLIP_V = 0x40000000;    // бит 31: отражение по вертикали
export const FLIP_D = 0x20000000;    // бит 30: диагональ (в гексах — поворот на 60°)
export const ROT_120 = 0x10000000;   // бит 29: поворот на 120° в гексах, снимать всегда
export const ALL_FLAGS = (FLIP_H | FLIP_V | FLIP_D | ROT_120) >>> 0;

// Снять флаги: номер тайла и отдельно три признака отражения
export function decodeGid(raw, opts = {}) {
  const u = raw >>> 0;
  const mask = opts.threeFlags ? (FLIP_H | FLIP_V | FLIP_D) >>> 0 : ALL_FLAGS;  // ошибка: забыт бит 29
  return {
    gid: opts.keepFlags ? u : (u & ~mask) >>> 0,  // ошибка для ловушки: флаги не сняты
    h: (u & FLIP_H) !== 0,
    v: (u & FLIP_V) !== 0,
    d: (u & FLIP_D) !== 0,
  };
}

// Тайлсет — тот, у которого наибольший firstgid, не больший gid; номер в нём — gid − firstgid
export function findTileset(tilesets, gid, opts = {}) {
  if (gid === 0) return null;  // 0 — пустая клетка
  let best = null;
  if (opts.firstOnly) {        // ошибка для ловушки: всегда первый тайлсет
    best = tilesets[0];
  } else {
    for (const ts of tilesets) if (ts.firstgid <= gid && (!best || ts.firstgid > best.firstgid)) best = ts;
  }
  if (!best) return null;
  const local = gid - best.firstgid;
  return { ts: best, local, known: local < best.tilecount };
}

// Где тайл лежит в картинке тайлсета: columns, margin, spacing
export function tileRect(ts, local, opts = {}) {
  const margin = opts.noGaps ? 0 : ts.margin;   // ошибка для ловушки: забыты margin и spacing
  const spacing = opts.noGaps ? 0 : ts.spacing;
  const col = local % ts.columns;
  const row = Math.floor(local / ts.columns);
  return {
    sx: margin + col * (ts.tilewidth + spacing),
    sy: margin + row * (ts.tileheight + spacing),
    w: ts.tilewidth,
    h: ts.tileheight,
  };
}

// Свойства в TMJ — массив {name, type, value}; превращаем в обычный объект
export function props(list) {
  const out = {};
  for (const p of list || []) out[p.name] = p.value;
  return out;
}

// Свойства тайла: tiles — разреженный массив, искать по полю id, а не по номеру в массиве
export function tileProps(ts, local, opts = {}) {
  const tiles = ts.tiles || [];
  const t = opts.byIndex ? tiles[local] : tiles.find((x) => x.id === local);  // byIndex — ошибка
  return t ? props(t.properties) : {};
}

// Проверка при загрузке: формат data, размер, неизвестные GID
export function validateMap(map) {
  const errors = [];
  const flat = flattenLayers(map.layers);
  for (const layer of flat) {
    if (layer.type !== "tilelayer") continue;
    if (typeof layer.data === "string") {
      errors.push("слой «" + layer.name + "»: data — строка (" + (layer.encoding || "?") +
        (layer.compression ? ", " + layer.compression : "") + "), нужен CSV-массив");
      continue;
    }
    if (layer.data.length !== map.width * map.height) {
      errors.push("слой «" + layer.name + "»: в data " + layer.data.length + " чисел, ждали " +
        map.width + "×" + map.height + " = " + map.width * map.height);
    }
    layer.data.forEach((raw, i) => {
      const { gid } = decodeGid(raw);
      if (gid === 0) return;
      const hit = findTileset(map.tilesets, gid);
      if (!hit || !hit.known) {
        errors.push("слой «" + layer.name + "»: неизвестный GID " + gid + " в клетке (" +
          (i % map.width) + "," + Math.floor(i / map.width) + ")");
      }
    });
  }
  return errors;
}

// Группы слоёв раскрываем по порядку: порядок в массиве — порядок отрисовки снизу вверх
export function flattenLayers(layers) {
  const out = [];
  for (const l of layers) {
    if (l.type === "group") out.push(...flattenLayers(l.layers));
    else out.push(l);
  }
  return out;
}

// Рамка объекта в пикселях карты: у тайлового (с gid) y — нижний край, у прямоугольника — верхний
export function objectBox(obj, opts = {}) {
  const top = obj.gid && !opts.tileTopLeft ? obj.y - obj.height : obj.y;  // tileTopLeft — ошибка
  return { x: obj.x, y: top, w: obj.width, h: obj.height };
}

// Список команд отрисовки: слой за слоем, клетка за клеткой (right-down), потом объекты
export function buildDrawList(map, opts = {}) {
  const cmds = [];
  const stats = { cells: 0, drawn: 0, lost: 0 };
  for (const layer of flattenLayers(map.layers)) {
    if (layer.visible === false) continue;
    if (layer.type === "tilelayer") {
      layer.data.forEach((raw, i) => {
        if (raw === 0) return;
        stats.cells += 1;
        const f = decodeGid(raw, opts);
        const hit = findTileset(map.tilesets, f.gid, opts);
        if (!hit || !hit.known) { stats.lost += 1; return; }
        const src = tileRect(hit.ts, hit.local, opts);
        const dx = (i % map.width) * map.tilewidth;
        const dy = Math.floor(i / map.width) * map.tileheight + map.tileheight - src.h;  // высокий тайл растёт вверх
        cmds.push({ layer: layer.name, cell: i, image: hit.ts.image, src, dx, dy, h: f.h, v: f.v, d: f.d });
        stats.drawn += 1;
      });
    } else if (layer.type === "objectgroup") {
      for (const obj of layer.objects) {
        if (!obj.gid) continue;
        const f = decodeGid(obj.gid);
        const hit = findTileset(map.tilesets, f.gid);
        if (!hit || !hit.known) { stats.lost += 1; continue; }
        const box = objectBox(obj, opts);
        cmds.push({ layer: layer.name, cell: -1, image: hit.ts.image, src: tileRect(hit.ts, hit.local), dx: box.x, dy: box.y,
          h: f.h, v: f.v, d: f.d });
        stats.drawn += 1;
      }
    }
  }
  return { cmds, stats };
}

// Отрисовка на canvas: сначала диагональ, потом горизонталь и вертикаль (так велит документация)
export function drawToCanvas(ctx, images, cmds, opts = {}) {
  for (const c of cmds) {
    const w = c.src.w;
    const h = c.src.h;
    ctx.save();
    ctx.translate(c.dx + w / 2, c.dy + h / 2);
    if (opts.diagonalLast && c.d) ctx.transform(0, 1, 1, 0, 0, 0);  // ошибка порядка для сравнения
    ctx.scale(c.h ? -1 : 1, c.v ? -1 : 1);
    if (!opts.diagonalLast && c.d) ctx.transform(0, 1, 1, 0, 0, 0);  // ближе всего к картинке — выполняется первой
    ctx.drawImage(images[c.image], c.src.sx, c.src.sy, w, h, -w / 2, -h / 2, w, h);
    ctx.restore();
  }
}

// Сетка твёрдых клеток: из отдельного слоя коллизий или из свойства solid у тайла
export function solidFromLayer(map, name) {
  const layer = flattenLayers(map.layers).find((l) => l.name === name);
  return layer.data.map((raw) => decodeGid(raw).gid !== 0);
}

export function solidFromTiles(map, layerName, opts = {}) {
  const layer = flattenLayers(map.layers).find((l) => l.name === layerName);
  return layer.data.map((raw) => {
    const hit = findTileset(map.tilesets, decodeGid(raw).gid);
    return hit ? tileProps(hit.ts, hit.local, opts).solid === true : false;
  });
}
// test.mjs — node test.mjs; карта синтетическая, генератор с зерном, Math.random и файлы не используются
import { deflateSync } from "node:zlib";
import { FLIP_H, FLIP_V, FLIP_D, ROT_120, decodeGid, findTileset, tileRect, props, tileProps, validateMap,
  flattenLayers, objectBox, buildDrawList, drawToCanvas, solidFromLayer, solidFromTiles } from "./tiledmap.mjs";

const out = [];
const say = (s) => out.push(s);
const hex = (n) => "0x" + (n >>> 0).toString(16).toUpperCase().padStart(8, "0");

// Генератор с зерном (LCG на Math.imul)
function makeRng(seed) {
  let s = seed >>> 0;
  const next = () => { s = (Math.imul(s, 1664525) + 1013904223) >>> 0; return s / 4294967296; };
  return { next, int: (n) => Math.floor(next() * n) };
}

// Синтетическая карта в том виде, в каком её сохраняет Tiled в JSON
function makeMap(seed) {
  const rng = makeRng(seed);
  const W = 32;
  const H = 18;
  const terrainTiles = [{ id: 3, properties: [{ name: "sound", type: "string", value: "grass" }] }];
  for (let id = 8; id < 16; id++) terrainTiles.push({ id, properties: [{ name: "solid", type: "bool", value: true }] });
  const tilesets = [
    { firstgid: 1, name: "terrain", image: "terrain.png", imagewidth: 144, imageheight: 144, tilewidth: 16,
      tileheight: 16, columns: 8, tilecount: 64, margin: 1, spacing: 2, tiles: terrainTiles },
    { firstgid: 65, name: "deco", image: "deco.png", imagewidth: 64, imageheight: 64, tilewidth: 16,
      tileheight: 16, columns: 4, tilecount: 16, margin: 0, spacing: 0 },
    { firstgid: 81, name: "tall", image: "tall.png", imagewidth: 64, imageheight: 64, tilewidth: 16,
      tileheight: 32, columns: 4, tilecount: 8, margin: 0, spacing: 0 },
  ];
  const isWall = (x, y) => x === 0 || y === 0 || x === W - 1 || y === H - 1 ||
    (y === 12 && x >= 6 && x <= 12) || (y === 8 && x >= 18 && x <= 26);
  const ground = [];
  const deco = [];
  const coll = [];
  const combos = [FLIP_H, FLIP_V, FLIP_D, FLIP_H | FLIP_V, FLIP_H | FLIP_D, FLIP_V | FLIP_D, FLIP_H | FLIP_V | FLIP_D];
  for (let y = 0; y < H; y++) {
    for (let x = 0; x < W; x++) {
      if (isWall(x, y)) { ground.push(9 + rng.int(8)); deco.push(0); coll.push(9); continue; }
      let g = 1 + rng.int(8);
      if (rng.int(8) === 0) g = (g | combos[rng.int(combos.length)]) >>> 0;
      ground.push(g);
      let d = 0;
      if (rng.int(6) === 0) {
        d = 65 + rng.int(16);
        if (rng.int(4) === 0) d = (d | (rng.int(2) ? FLIP_H : FLIP_V)) >>> 0;
      }
      deco.push(d);
      coll.push(0);
    }
  }
  // Бит 29 на трёх клетках: Tiled сохраняет его, даже если карта когда-то была гексагональной
  for (const i of [2 * W + 3, 5 * W + 10, 14 * W + 27]) ground[i] = (ground[i] | ROT_120) >>> 0;
  // Высокие тайлы 16×32 (деревья) над стенами; над ними в том же слое — тайл декора
  for (const [x, y, k] of [[4, 16, 4], [9, 11, 5], [24, 7, 6]]) { deco[y * W + x] = 81 + k; deco[(y - 1) * W + x] = 65 + k; }
  // Невидимые барьеры: только в слое коллизий
  for (const [x, y] of [[15, 16], [15, 15], [28, 7]]) coll[y * W + x] = 9;
  const objects = [
    { id: 1, name: "player", type: "Player", gid: 81, x: 48, y: 272, width: 16, height: 32,
      properties: [{ name: "hp", type: "int", value: 5 }] },
    { id: 2, name: "slime", type: "Enemy", gid: 82, x: 128, y: 192, width: 16, height: 32,
      properties: [{ name: "patrol", type: "int", value: 48 }] },
    { id: 3, name: "bat", type: "Enemy", gid: 83, x: 352, y: 128, width: 16, height: 32, properties: [] },
    { id: 4, name: "slime", type: "Enemy", gid: 82, x: 208, y: 272, width: 16, height: 32, properties: [] },
    { id: 5, name: "exit", type: "Trigger", x: 464, y: 224, width: 32, height: 48,
      properties: [{ name: "target", type: "string", value: "level2" }, { name: "once", type: "bool", value: true }] },
    { id: 6, name: "spawn", type: "", point: true, x: 56, y: 270, width: 0, height: 0, properties: [] },
  ];
  return {
    type: "map", orientation: "orthogonal", renderorder: "right-down",
    infinite: false, width: W, height: H, tilewidth: 16, tileheight: 16, nextlayerid: 5, nextobjectid: 7,
    tilesets,
    layers: [
      { id: 1, name: "ground", type: "tilelayer", width: W, height: H, x: 0, y: 0, visible: true, opacity: 1, data: ground },
      { id: 2, name: "deco", type: "tilelayer", width: W, height: H, x: 0, y: 0, visible: true, opacity: 1, data: deco },
      { id: 3, name: "collision", type: "tilelayer", width: W, height: H, x: 0, y: 0, visible: false, opacity: 1, data: coll },
      { id: 4, name: "objects", type: "objectgroup", draworder: "topdown", x: 0, y: 0, visible: true, opacity: 1, objects },
    ],
  };
}

const SEED = 77;
const map = makeMap(SEED);
const layer = (name) => flattenLayers(map.layers).find((l) => l.name === name);
const flagsOf = (f) => (f.h ? "H" : "") + (f.v ? "V" : "") + (f.d ? "D" : "") || "-";

say("# 0. Карта");
say("карта " + map.width + "×" + map.height + " клеток по " + map.tilewidth + "×" + map.tileheight + " px = " +
  map.width * map.tilewidth + "×" + map.height * map.tileheight + " px, " + map.orientation + ", " + map.renderorder + ", зерно " + SEED);
for (const ts of map.tilesets) {
  say("тайлсет " + ts.name + ": firstgid " + ts.firstgid + ", тайлов " + ts.tilecount + " (GID " + ts.firstgid + "–" +
    (ts.firstgid + ts.tilecount - 1) + "), тайл " + ts.tilewidth + "×" + ts.tileheight + ", columns " + ts.columns +
    ", margin " + ts.margin + ", spacing " + ts.spacing + ", картинка " + ts.imagewidth + "×" + ts.imageheight);
}
for (const l of map.layers) {
  if (l.type === "tilelayer") {
    say("слой " + l.name + " (tilelayer" + (l.visible ? "" : ", скрыт") + "): data " + l.data.length + " чисел, непустых " +
      l.data.filter((g) => g !== 0).length);
  } else {
    say("слой " + l.name + " (objectgroup): объектов " + l.objects.length + ", из них с gid " + l.objects.filter((o) => o.gid).length);
  }
}
say("строка 1 слоя ground, первые 8 чисел: " + layer("ground").data.slice(32, 40).join(", "));

say("");
say("# 1. GID → тайлсет, номер тайла и место в картинке");
for (const raw of [1, 13, layer("ground").data.find((g) => g > FLIP_H), 70, (65 | FLIP_V) >>> 0, 85, 0]) {
  const f = decodeGid(raw);
  const hit = findTileset(map.tilesets, f.gid);
  if (!hit) { say(raw + " → пустая клетка"); continue; }
  const r = tileRect(hit.ts, hit.local);
  say(raw + " (" + hex(raw) + ") → GID " + f.gid + ", флаги " + flagsOf(f) + ", " + hit.ts.name + " №" + hit.local +
    ", в картинке x " + r.sx + ", y " + r.sy);
}

say("");
say("# 2. Ловушка: флаги не сняты");
{
  const all = buildDrawList(map);
  const keep = buildDrawList(map, { keepFlags: true });
  const three = buildDrawList(map, { threeFlags: true });
  const flipped = flattenLayers(map.layers).filter((l) => l.type === "tilelayer" && l.visible)
    .reduce((s, l) => s + l.data.filter((g) => g >= ROT_120).length, 0);
  say("видимых непустых клеток " + all.stats.cells + ", с флагами в старших битах " + flipped);
  say("флаги сняты: нарисовано " + all.stats.drawn + " (с объектами), потеряно " + all.stats.lost);
  say("флаги не сняты: нарисовано " + keep.stats.drawn + ", потеряно " + keep.stats.lost);
  say("сняты только H, V, D без бита 29: потеряно " + three.stats.lost);
  const raw = layer("ground").data.find((g) => g > FLIP_H);
  const bad = findTileset(map.tilesets, raw >>> 0);
  say("пример: " + raw + " без снятия флагов → тайлсет " + bad.ts.name + ", №" + bad.local + " при " + bad.ts.tilecount + " тайлах");
}

say("");
say("# 3. Ловушка: тайлсет выбран неверно");
{
  const ok = buildDrawList(map);
  const first = buildDrawList(map, { firstOnly: true });
  const count = (cmds, name) => cmds.filter((c) => c.image === name).length;
  say("наибольший firstgid ≤ GID: terrain " + count(ok.cmds, "terrain.png") + ", deco " + count(ok.cmds, "deco.png") +
    ", tall " + count(ok.cmds, "tall.png") + ", потеряно " + ok.stats.lost);
  say("всегда первый тайлсет: terrain " + count(first.cmds, "terrain.png") + ", deco " + count(first.cmds, "deco.png") +
    ", tall " + count(first.cmds, "tall.png") + ", потеряно " + first.stats.lost);
  const hit = findTileset([map.tilesets[0]], 70);
  const r = tileRect(hit.ts, hit.local);
  say("GID 70 в terrain: №" + hit.local + ", строка " + Math.floor(hit.local / 8) + " из 8, y " + r.sy + " при высоте картинки 144");
}

say("");
say("# 4. Ловушка: забыты margin и spacing (terrain: margin 1, spacing 2)");
{
  const ts = map.tilesets[0];
  const cols = [];
  for (let c = 0; c < ts.columns; c++) cols.push(tileRect(ts, c).sx - tileRect(ts, c, { noGaps: true }).sx);
  say("сдвиг по x в столбцах 0–7, px: " + cols.join(", "));
  say("тайл №63 (правый нижний): верно x " + tileRect(ts, 63).sx + ", y " + tileRect(ts, 63).sy + "; без зазоров x " +
    tileRect(ts, 63, { noGaps: true }).sx + ", y " + tileRect(ts, 63, { noGaps: true }).sy);
  const ok = buildDrawList(map).cmds;
  const ng = buildDrawList(map, { noGaps: true }).cmds;
  let shifted = 0;
  let half = 0;
  let maxErr = 0;
  let decoShift = 0;
  ok.forEach((c, i) => {
    const e = Math.max(Math.abs(c.src.sx - ng[i].src.sx), Math.abs(c.src.sy - ng[i].src.sy));
    if (c.image === "terrain.png") { if (e > 0) shifted += 1; if (e >= 8) half += 1; maxErr = Math.max(maxErr, e); }
    else if (e > 0) decoShift += 1;
  });
  const terr = ok.filter((c) => c.image === "terrain.png").length;
  say("тайлов terrain на карте " + terr + ": со сдвигом " + shifted + ", сдвиг от половины тайла (8 px) " + half +
    ", наибольший " + maxErr + " px");
  say("deco и tall (margin 0, spacing 0): со сдвигом " + decoShift);
}

say("");
say("# 5. Отражения на canvas: 8 сочетаний H, V, D");
{
  // Поддельный контекст: хранит матрицу и записывает, куда попали углы тайла
  function fakeCtx() {
    let m = [1, 0, 0, 1, 0, 0];
    const stack = [];
    const mul = (a, b) => [a[0] * b[0] + a[2] * b[1], a[1] * b[0] + a[3] * b[1], a[0] * b[2] + a[2] * b[3],
      a[1] * b[2] + a[3] * b[3], a[0] * b[4] + a[2] * b[5] + a[4], a[1] * b[4] + a[3] * b[5] + a[5]];
    const ctx = { draws: [] };
    ctx.save = () => stack.push(m);
    ctx.restore = () => { m = stack.pop(); };
    ctx.translate = (x, y) => { m = mul(m, [1, 0, 0, 1, x, y]); };
    ctx.scale = (x, y) => { m = mul(m, [x, 0, 0, y, 0, 0]); };
    ctx.transform = (a, b, c, d, e, f) => { m = mul(m, [a, b, c, d, e, f]); };
    ctx.drawImage = (img, sx, sy, sw, sh, dx, dy, dw, dh) => {
      const p = (x, y) => [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
      ctx.draws.push({ tl: p(dx, dy), tr: p(dx + dw, dy), bl: p(dx, dy + dh) });
    };
    return ctx;
  }
  // Ожидание по документации: сначала диагональ (обмен x и y), потом H и V
  const expect = (h, v, d, u, w) => { let [a, b] = u; if (d) [a, b] = [b, a]; if (h) a = w - a; if (v) b = w - b; return [a, b]; };
  const same = (p, q) => Math.abs(p[0] - q[0]) < 1e-9 && Math.abs(p[1] - q[1]) < 1e-9;
  let good = 0;
  let late = 0;
  const lines = [];
  for (let k = 0; k < 8; k++) {
    const c = { src: { sx: 0, sy: 0, w: 16, h: 16 }, dx: 0, dy: 0, image: "t", h: (k & 1) !== 0, v: (k & 2) !== 0, d: (k & 4) !== 0 };
    const a = fakeCtx();
    drawToCanvas(a, { t: null }, [c]);
    const b = fakeCtx();
    drawToCanvas(b, { t: null }, [c], { diagonalLast: true });
    const want = [expect(c.h, c.v, c.d, [0, 0], 16), expect(c.h, c.v, c.d, [16, 0], 16), expect(c.h, c.v, c.d, [0, 16], 16)];
    const okA = same(a.draws[0].tl, want[0]) && same(a.draws[0].tr, want[1]) && same(a.draws[0].bl, want[2]);
    const okB = same(b.draws[0].tl, want[0]) && same(b.draws[0].tr, want[1]) && same(b.draws[0].bl, want[2]);
    if (okA) good += 1;
    if (okB) late += 1;
    lines.push(flagsOf(c) + " " + (okA ? "да" : "нет") + "/" + (okB ? "да" : "нет"));
  }
  say("совпало с документацией (сначала D / D последней): " + lines.join("; "));
  say("итого: сначала диагональ — " + good + " из 8, диагональ последней — " + late + " из 8");
  const ctx = fakeCtx();
  const { cmds } = buildDrawList(map);
  drawToCanvas(ctx, { "terrain.png": null, "deco.png": null, "tall.png": null }, cmds);
  say("вся карта: вызовов drawImage " + ctx.draws.length);
}

say("");
say("# 6. Ловушка: тайловый объект по верхнему левому углу");
{
  const solid = solidFromLayer(map, "collision");
  const W = map.width;
  const hitsSolid = (b) => {
    for (let y = Math.floor(b.y / 16); y <= Math.floor((b.y + b.h - 1) / 16); y++) {
      for (let x = Math.floor(b.x / 16); x <= Math.floor((b.x + b.w - 1) / 16); x++) {
        if (y < 0 || y >= map.height || x < 0 || x >= W || solid[y * W + x]) return true;
      }
    }
    return false;
  };
  const objs = layer("objects").objects;
  for (const o of objs) {
    const p = props(o.properties);
    const kind = o.gid ? "тайловый" : o.point ? "точка" : "прямоугольник";
    const b = objectBox(o);
    const keys = Object.keys(p).map((k) => k + "=" + p[k]).join(", ") || "нет";
    say(o.name + " (" + kind + "): x " + o.x + ", y " + o.y + " → рамка x " + b.x + "–" + (b.x + b.w) + ", y " + b.y + "–" +
      (b.y + b.h) + "; свойства: " + keys);
  }
  const tileObjs = objs.filter((o) => o.gid);
  const okHits = tileObjs.filter((o) => hitsSolid(objectBox(o))).length;
  const badHits = tileObjs.filter((o) => hitsSolid(objectBox(o, { tileTopLeft: true }))).length;
  const pl = objs[0];
  say("player по верхнему левому: y " + objectBox(pl, { tileTopLeft: true }).y + "–" + (objectBox(pl, { tileTopLeft: true }).y + pl.height) +
    ", сдвиг вниз " + (objectBox(pl, { tileTopLeft: true }).y - objectBox(pl).y) + " px");
  say("тайловых объектов в стене или за краем карты: верно " + okHits + " из " + tileObjs.length + ", по верхнему левому " + badHits + " из " + tileObjs.length);
  const ex = objs.find((o) => o.name === "exit");
  say("exit (прямоугольник) по нижнему левому, как тайловый: y " + (ex.y - ex.height) + " вместо " + ex.y + ", сдвиг вверх " + ex.height + " px");
}

say("");
say("# 7. Коллизии: слой collision против свойства solid у тайлов");
{
  const a = solidFromLayer(map, "collision");
  const b = solidFromTiles(map, "ground");
  const c = solidFromTiles(map, "ground", { byIndex: true });
  const n = (arr) => arr.filter(Boolean).length;
  const diff = (x, y) => x.filter((v, i) => v !== y[i]).length;
  say("твёрдых клеток: по слою " + n(a) + ", по свойству solid " + n(b) + ", расходятся " + diff(a, b));
  say("tiles[номер] вместо поиска по id: твёрдых " + n(c) + ", расходятся с верным " + diff(b, c));
  const t = map.tilesets[0];
  say("в terrain.tiles записей " + t.tiles.length + " на " + t.tilecount + " тайлов; tiles[1].id = " + t.tiles[1].id +
    ", свойства тайла №3: " + JSON.stringify(tileProps(t, 3)));
}

say("");
say("# 8. Порядок слоёв и renderorder");
{
  const W = map.width * map.tilewidth;
  const H = map.height * map.tileheight;
  const paint = (cmds) => {
    const frame = new Int32Array(W * H).fill(-1);
    for (const c of cmds) {
      const id = c.layer === "objects" ? 100000 + c.dx * 1000 + c.dy : (c.layer === "ground" ? 0 : 50000) + c.cell;
      for (let y = Math.max(0, c.dy); y < Math.min(H, c.dy + c.src.h); y++) {
        for (let x = Math.max(0, c.dx); x < Math.min(W, c.dx + c.src.w); x++) frame[y * W + x] = id;
      }
    }
    return frame;
  };
  const diffPx = (f, g) => { let n = 0; for (let i = 0; i < f.length; i++) if (f[i] !== g[i]) n += 1; return n; };
  const ownedBy = (f, lo, hi) => { let n = 0; for (const v of f) if (v >= lo && v < hi) n += 1; return n; };
  const { cmds } = buildDrawList(map);
  say("порядок отрисовки: " + flattenLayers(map.layers).filter((l) => l.visible !== false).map((l) => l.name).join(" → ") + " (collision скрыт)");
  const normal = paint(cmds);
  const order = ["deco", "ground", "objects"];
  const swapped = paint(order.flatMap((n) => cmds.filter((c) => c.layer === n)));
  say("видимых пикселей deco: ground → deco " + ownedBy(normal, 50000, 100000) + ", deco → ground " + ownedBy(swapped, 50000, 100000));
  const leftUp = (list) => {
    const res = [];
    for (const n of ["ground", "deco", "objects"]) {
      const part = list.filter((c) => c.layer === n);
      if (n !== "objects") part.sort((p, q) => q.cell - p.cell);
      res.push(...part);
    }
    return res;
  };
  say("right-down против left-up: различаются пикселей " + diffPx(normal, paint(leftUp(cmds))));
  const flat = cmds.filter((c) => c.src.h === 16 || c.layer === "objects");
  say("то же без трёх высоких тайлов 16×32: различаются пикселей " + diffPx(paint(flat), paint(leftUp(flat))));
}

say("");
say("# 9. Проверка при загрузке");
{
  say("исходная карта: ошибок " + validateMap(map).length);
  const broken = JSON.parse(JSON.stringify(map));
  broken.layers[1].data.pop();
  broken.layers[0].data[40] = 200;
  broken.layers[0].data[41] = (90 | FLIP_H) >>> 0;
  for (const e of validateMap(broken)) say("ошибка: " + e);
  const g = layer("ground").data;
  const bytes = Buffer.alloc(g.length * 4);
  g.forEach((v, i) => bytes.writeUInt32LE(v, i * 4));
  const b64 = bytes.toString("base64");
  const z64 = deflateSync(bytes).toString("base64");
  const packed = JSON.parse(JSON.stringify(map));
  Object.assign(packed.layers[0], { data: b64, encoding: "base64" });
  Object.assign(packed.layers[1], { data: z64, encoding: "base64", compression: "zlib" });
  for (const e of validateMap(packed)) say("ошибка: " + e);
  let same = 0;
  for (let i = 0; i < g.length; i++) if (Buffer.from(b64, "base64").readUInt32LE(i * 4) === g[i]) same += 1;
  say("длина data слоя ground: CSV-массив " + JSON.stringify(g).length + " символов, base64 " + b64.length + ", base64 + zlib " + z64.length);
  say("base64 без сжатия раскодирован (little-endian): совпало чисел " + same + " из " + g.length);
}

process.stdout.write(out.join("\n") + "\n");

Обвязка для браузера — несколько строк; в Node.js её не запускали, она только передаёт загруженные картинки в drawToCanvas. Путь ts.image в файле карты указан относительно самого файла карты, поэтому храните картинки рядом с ним или поправьте пути при загрузке.

// main.mjs — в браузере, рядом с level1.tmj и картинками тайлсетов
import { validateMap, buildDrawList, drawToCanvas } from "./tiledmap.mjs";

const map = await (await fetch("level1.tmj")).json();
const errors = validateMap(map);
if (errors.length > 0) throw new Error(errors.join("\n"));
const images = {};
for (const ts of map.tilesets) {
  const img = new Image();
  img.src = ts.image;
  await img.decode();
  images[ts.image] = img;
}
const ctx = document.querySelector("canvas").getContext("2d");
drawToCanvas(ctx, images, buildDrawList(map).cmds);

Как показать экран загрузки, пока картинки тайлсетов и карта ещё грузятся, мы разбирали в статье про загрузку ресурсов.

Проверка в Node.js

Ниже — полный вывод node test.mjs на Node.js 24.22.1; мы запускали его 25 раз подряд, вывод совпадал байт в байт. Координаты клеток — (столбец, строка) с нуля, координаты в пикселях — от верхнего левого угла карты.

Вывод прогона:

# 0. Карта
карта 32×18 клеток по 16×16 px = 512×288 px, orthogonal, right-down, зерно 77
тайлсет terrain: firstgid 1, тайлов 64 (GID 1–64), тайл 16×16, columns 8, margin 1, spacing 2, картинка 144×144
тайлсет deco: firstgid 65, тайлов 16 (GID 65–80), тайл 16×16, columns 4, margin 0, spacing 0, картинка 64×64
тайлсет tall: firstgid 81, тайлов 8 (GID 81–88), тайл 16×32, columns 4, margin 0, spacing 0, картинка 64×64
слой ground (tilelayer): data 576 чисел, непустых 576
слой deco (tilelayer): data 576 чисел, непустых 68
слой collision (tilelayer, скрыт): data 576 чисел, непустых 115
слой objects (objectgroup): объектов 6, из них с gid 4
строка 1 слоя ground, первые 8 чисел: 13, 1, 5, 5, 2684354565, 2, 3, 1

# 1. GID → тайлсет, номер тайла и место в картинке
1 (0x00000001) → GID 1, флаги -, terrain №0, в картинке x 1, y 1
13 (0x0000000D) → GID 13, флаги -, terrain №12, в картинке x 73, y 19
2684354565 (0xA0000005) → GID 5, флаги HD, terrain №4, в картинке x 73, y 1
70 (0x00000046) → GID 70, флаги -, deco №5, в картинке x 16, y 16
1073741889 (0x40000041) → GID 65, флаги V, deco №0, в картинке x 0, y 0
85 (0x00000055) → GID 85, флаги -, tall №4, в картинке x 0, y 32
0 → пустая клетка

# 2. Ловушка: флаги не сняты
видимых непустых клеток 644, с флагами в старших битах 63
флаги сняты: нарисовано 648 (с объектами), потеряно 0
флаги не сняты: нарисовано 585, потеряно 63
сняты только H, V, D без бита 29: потеряно 3
пример: 2684354565 без снятия флагов → тайлсет tall, №2684354484 при 8 тайлах

# 3. Ловушка: тайлсет выбран неверно
наибольший firstgid ≤ GID: terrain 576, deco 65, tall 7, потеряно 0
всегда первый тайлсет: terrain 576, deco 0, tall 4, потеряно 68
GID 70 в terrain: №69, строка 8 из 8, y 145 при высоте картинки 144

# 4. Ловушка: забыты margin и spacing (terrain: margin 1, spacing 2)
сдвиг по x в столбцах 0–7, px: 1, 3, 5, 7, 9, 11, 13, 15
тайл №63 (правый нижний): верно x 127, y 127; без зазоров x 112, y 112
тайлов terrain на карте 576: со сдвигом 576, сдвиг от половины тайла (8 px) 307, наибольший 15 px
deco и tall (margin 0, spacing 0): со сдвигом 0

# 5. Отражения на canvas: 8 сочетаний H, V, D
совпало с документацией (сначала D / D последней): - да/да; H да/да; V да/да; HV да/да; D да/да; HD да/нет; VD да/нет; HVD да/да
итого: сначала диагональ — 8 из 8, диагональ последней — 6 из 8
вся карта: вызовов drawImage 648

# 6. Ловушка: тайловый объект по верхнему левому углу
player (тайловый): x 48, y 272 → рамка x 48–64, y 240–272; свойства: hp=5
slime (тайловый): x 128, y 192 → рамка x 128–144, y 160–192; свойства: patrol=48
bat (тайловый): x 352, y 128 → рамка x 352–368, y 96–128; свойства: нет
slime (тайловый): x 208, y 272 → рамка x 208–224, y 240–272; свойства: нет
exit (прямоугольник): x 464, y 224 → рамка x 464–496, y 224–272; свойства: target=level2, once=true
spawn (точка): x 56, y 270 → рамка x 56–56, y 270–270; свойства: нет
player по верхнему левому: y 272–304, сдвиг вниз 32 px
тайловых объектов в стене или за краем карты: верно 0 из 4, по верхнему левому 4 из 4
exit (прямоугольник) по нижнему левому, как тайловый: y 176 вместо 224, сдвиг вверх 48 px

# 7. Коллизии: слой collision против свойства solid у тайлов
твёрдых клеток: по слою 115, по свойству solid 112, расходятся 3
tiles[номер] вместо поиска по id: твёрдых 410, расходятся с верным 492
в terrain.tiles записей 9 на 64 тайлов; tiles[1].id = 8, свойства тайла №3: {"sound":"grass"}

# 8. Порядок слоёв и renderorder
порядок отрисовки: ground → deco → objects (collision скрыт)
видимых пикселей deco: ground → deco 17408, deco → ground 0
right-down против left-up: различаются пикселей 768
то же без трёх высоких тайлов 16×32: различаются пикселей 0

# 9. Проверка при загрузке
исходная карта: ошибок 0
ошибка: слой «ground»: неизвестный GID 200 в клетке (8,1)
ошибка: слой «ground»: неизвестный GID 90 в клетке (9,1)
ошибка: слой «deco»: в data 575 чисел, ждали 32×18 = 576
ошибка: слой «ground»: data — строка (base64), нужен CSV-массив
ошибка: слой «deco»: data — строка (base64, zlib), нужен CSV-массив
длина data слоя ground: CSV-массив 1693 символов, base64 3072, base64 + zlib 744
base64 без сжатия раскодирован (little-endian): совпало чисел 576 из 576

Что показал прогон: пять ловушек

Все пять ловушек воспроизвелись и изменили картинку или данные: ловушка 1 — раздел 2 вывода, ловушка 2 — раздел 3, ловушка 3 — раздел 4, ловушка 4 — раздел 6, ловушка 5 — раздел 7. Чего прогон не подтвердил — в следующем разделе.

Ловушка 1: флаги отражения не сняты

Если не снять флаги, каждый отражённый тайл ищется по числу больше двух миллиардов и пропадает. В разделе 2 вывода из 644 видимых непустых клеток у 63 были флаги в старших битах, и все 63 не нарисовались. Число 2684354565 без снятия флагов «нашлось» в последнем тайлсете tall под номером 2684354484 при 8 тайлах: если бы загрузчик не проверял tilecount, он взял бы координаты далеко за краем картинки.

Снять только три флага H, V, D — тоже ошибка: 3 клетки с оставшимся битом 29 потерялись. На карте, которую когда-то делали гексагональной, такие клетки могут оказаться где угодно, и в ручной проверке их не заметить.

Ловушка 2: тайлсет выбран неверно

Если всегда брать первый тайлсет, все тайлы из второго и третьего наборов ищутся в первой картинке и пропадают. В разделе 3 вывода при верном выборе нарисовано 576 тайлов terrain, 65 — deco и 7 — tall; при выборе первого набора все 65 тайлов deco и 3 высоких тайла из слоя deco потерялись — 68 штук. GID 70 при этом становится тайлом №69 в terrain, в 8-й строке при восьми строках (0–7), с y 145 при высоте картинки 144 px. Тайлы terrain ошибка не задела: для первого набора правило «наибольший firstgid ≤ GID» и «первый набор» совпадают, поэтому на карте с одним тайлсетом её не видно.

Ловушка 3: забыты margin и spacing

Если забыть про отступ и зазоры, тайл вырезается из картинки со сдвигом, который растёт к правому и нижнему краю: на terrain (margin 1, spacing 2) по столбцам 0–7 сдвиг по x — 1, 3, 5, 7, 9, 11, 13, 15 px, по строкам по y — так же. В разделе 4 вывода со сдвигом нарисовались все 576 тайлов terrain, у 307 сдвиг был от половины тайла (8 px) и больше — то есть на экране в основном соседний тайл, — а наибольший сдвиг — 15 px. Тайлсеты deco и tall с margin 0 и spacing 0 ошибка не задела: 0 тайлов со сдвигом.

Ловушка 4: тайловый объект по верхнему левому углу

Если рисовать тайловый объект от его y вниз, как прямоугольник, он сдвигается вниз ровно на свою высоту. В разделе 6 вывода player 16×32 по верхнему левому углу занял y 272–304 вместо 240–272 — сдвиг 32 px, ниже верхней грани стены. Из 4 тайловых объектов в стене или за краем карты при верном чтении — 0, при неверном — все 4. Обратная ошибка тоже есть: прямоугольник exit, прочитанный как тайловый объект, уезжает вверх на свою высоту — на 48 px.

Ловушка 5: свойства тайла по позиции в tiles

Если брать свойства тайла как tiles[номер], а не искать запись с нужным id, свойства достаются чужим тайлам. В разделе 7 вывода по свойству solid верно найдено 112 твёрдых клеток; с tiles[номер] их стало 410, и с верной сеткой разошлись 492 клетки из 576: почти весь фон стал стенами, а большинство стен — проходимыми.

Что не подтвердилось и где мы поправили себя по документации

Пять ожиданий прогон не подтвердил или подтвердил слабее, чем мы думали:

  • «Если перепутать порядок отражений, сломается половина вариантов». Нет: в разделе 5 вывода диагональ, применённая после H и V, расходится с документацией только в 2 сочетаниях из 8 — HD и VD. Отражение без диагонали, одна диагональ и HVD совпадают при любом порядке. Ошибка всё равно настоящая: диагональ вместе с одним отражением — это поворот на 90°, а повороты, по документации, Tiled и записывает через диагональный флаг.
  • «renderorder меняет картинку». На тайлах 16×16 — нет: right-down и left-up дали 0 различающихся пикселей. Разница появилась только из-за трёх высоких тайлов 16×32 — 768 px, ровно три клетки 16×16, на которые они налезают.
  • «base64 компактнее массива». Без сжатия — наоборот: 3072 символа против 1693 у массива, потому что 4 байта на клетку, а наши GID в основном одно- и двузначные. Короче массива только base64 со сжатием zlib — 744 символа.
  • «Слой коллизий и свойство solid дают одно и то же». Почти: разошлись 3 клетки из 576 — это невидимые барьеры, которые есть только в слое collision. Какой способ главный, решите заранее, иначе такие клетки будут то стеной, то нет.
  • «Забытые margin и spacing портят все тайлсеты». Только те, где они не равны 0: у deco и tall — 0 тайлов со сдвигом.

В двух местах документация уточнила нашу исходную картину. Бит 30 на гексагональной карте — не диагональ, а поворот на 60°, а бит 29 — поворот на 120°; с какой версии Tiled пишет бит 29, на странице Global Tile IDs не сказано, поэтому версию мы не называем. И нижний левый угол для тайловых объектов — правило для ортогональной карты при objectalignment по умолчанию: на изометрической карте точка привязки — середина нижнего края, а в тайлсете привязку можно поменять. Само слово TMJ на странице JSON Map Format не встречается: расширение .tmj описано в заметке к выпуску Tiled 1.8.

Практический сценарий: подключить карту левел-дизайнера

Задача: левел-дизайнер прислал level1.tmj с тремя тайлсетами, отражёнными тайлами и персонажами-объектами, а вы хотите, чтобы игра показала уровень так же, как редактор. Входные данные — наш tiledmap.mjs и контрольные числа из вывода.

  1. Формат. В Tiled формат слоя тайлов — CSV, тайлсеты встроены в карту (у каждого есть image и columns, а не только source). Проверка: validateMap вернула 0 ошибок.
  2. Флаги. Найдите в data любое число больше 268435455 (0x0FFFFFFF): после снятия флагов оно должно попасть в тайлсет. Проверка: stats.lost равно 0, как в разделе 2 вывода.
  3. Тайлсеты. Тайлы из второго набора — не из первой картинки. Проверка: число тайлов по картинкам совпадает с числом тайлов каждого набора на карте.
  4. Зазоры. Нарисуйте тайл с наибольшим номером в наборе с margin или spacing: он должен совпасть с последним тайлом в редакторе, без полосок соседей.
  5. Объекты. Персонаж стоит на полу, а не в нём: низ рамки тайлового объекта — его y. Проверка: 0 тайловых объектов в стене, как в разделе 6.
  6. Коллизии. Выберите один источник (слой или свойство) и сравните со вторым: расхождения должны быть только там, где дизайнер ставил невидимые барьеры.

Проверяемый итог: карта на canvas совпадает с редактором клетка в клетку, отражённые тайлы на месте, персонаж стоит на полу, а проверка при загрузке ловит испорченный файл до первой отрисовки.

Когда вам это не подойдёт

Наш загрузчик рассчитан на конечную ортогональную карту со встроенными тайлсетами из одной картинки; вот где этого мало:

  • Внешние тайлсеты. Если в tilesets у набора есть только firstgid и source, сам набор лежит в отдельном файле (.tsj или .tsx), и его нужно загрузить и подставить; firstgid при этом берут из карты.
  • Тайлсет из отдельных картинок. У такого набора у каждого тайла своя картинка в tiles[].image, и формула с columns, margin и spacing не работает.
  • Бесконечные карты. У них infinite: true, а данные слоя лежат кусками в chunks со своими x и y, а не одним data на width × height.
  • Изометрия, гексы и прочие ориентации. Позиция клетки на экране считается иначе, а у гексов биты 30 и 29 — повороты, а не диагональ.
  • Анимации, смещения и эффекты слоя. Анимированные тайлы (animation), смещение и параллакс слоя (offsetx, parallaxx), прозрачность, оттенок, режим наложения, поворот объектов (rotation) и сортировку объектов по y (draworder: topdown) наш код не читает.
  • base64 и сжатие. Если менять формат слоя нельзя, данные нужно раскодировать, а zlib, gzip или zstd — ещё и распаковать.

Мы разрабатываем J2DRU — браузерный 2D игровой движок, где логика собирается из событий, условий и действий, а проект можно углублять на TypeScript. Движок в разработке и публично пока не открыт, заявку можно оставить на странице раннего доступа (подача заявки не гарантирует приглашение).

Источники (проверено: 12.11.2026, все страницы открываются с HTTP 200; документация — версия Tiled 1.12.2): Tiled — JSON Map Format (поля карты, слоя, объекта, тайлсета и свойства; data — массив GID или base64; encoding csv или base64; compression zlib, gzip, zstd с 1.3; objectalignment с 1.4; первый firstgid всегда 1; журнал изменений формата до Tiled 1.12); Tiled — Global Tile IDs (биты 32–29, снимать бит 29 всегда, порядок «сначала диагональ», наибольший firstgid ≤ GID, пример 1/65/115 и GID 72, GID 0 — пустая клетка, проверка размера данных); Tiled — TMX Map Format (тайловый объект привязан к нижнему левому углу на ортогональной карте и к середине нижнего края на изометрической; objectalignment unspecified; крупные тайлы растут вверх и вправо; порядок слоёв — порядок отрисовки; little-endian в base64); Tiled — Working with Objects (у прямоугольника точка привязки — верхний левый угол); Tiled — Working with Layers (порядок слоёв определяет порядок отрисовки; коллизии через специальный тайлсет); Tiled — Editing Tilesets (Tile Collision Editor); Tiled — Introduction (формат слоя тайлов в диалоге New Map; margin и spacing обычно 0); Tiled — Generic File Formats (JSON проще загружать в браузере; экспорт CSV — только слои тайлов, пустая клетка -1); Tiled 1.8 Released (07.02.2022: расширения tmj, tsj и tj). Карта, тайлсеты, зерно и все числа прогона — наш пример и наш прогон в Node.js 24.22.1.

Читайте также:

Частые вопросы

Как прочитать карту из Tiled в JavaScript?

Сохраните карту в формате JSON (расширение .tmj) с форматом слоя тайлов CSV и загрузите её как обычный JSON. В корне — width и height в клетках, tilewidth и tileheight в пикселях, массив layers и массив tilesets. У слоя тайлов массив data длиной width × height, у слоя объектов — массив objects. Для каждой клетки снимите флаги с GID, найдите тайлсет по firstgid и вырежьте тайл из картинки по columns, margin и spacing.

Что такое GID и firstgid в Tiled?

GID — номер тайла, общий для всех тайлсетов одной карты. У каждого тайлсета есть firstgid — GID его тайла с номером 0; у первого тайлсета он всегда 1, а GID 0 значит пустую клетку. Тайлсет клетки — тот, у которого наибольший firstgid, не больший GID, а номер тайла в нём — GID минус firstgid. Перед этим из GID нужно снять флаги отражения в четырёх старших битах.

Почему отражённые тайлы из Tiled пропадают?

Потому что отражение хранится в старших битах того же числа: бит 32 — по горизонтали, 31 — по вертикали, 30 — диагональ, а бит 29 документация велит снимать всегда, даже на не гексагональной карте. Если не снять флаги, GID получается больше двух миллиардов и не попадает ни в один тайлсет. В нашем прогоне так потерялись 63 тайла из 644, а снятие только трёх флагов без бита 29 потеряло ещё 3.

Почему объект из Tiled стоит ниже, чем в редакторе?

У объекта-тайла (с полем gid) на ортогональной карте x и y — нижний левый угол картинки, а у прямоугольника — верхний левый. Если рисовать тайловый объект от y вниз, он сдвинется ровно на свою высоту: в нашем прогоне персонаж 16×32 ушёл на 32 px вниз, и все 4 тайловых объекта оказались в стене или за краем карты. Привязку меняет свойство тайлсета objectalignment (с Tiled 1.4).