Коротко
Карта из Tiled в формате JSON (TMJ) — это размеры сетки, массив слоёв и массив тайлсетов: в слое тайлов на каждую клетку приходится одно число GID, в слое объектов — список объектов с координатами в пикселях и свойствами. Чтобы нарисовать клетку, из GID сначала снимают четыре старших бита флагов отражения, потом выбирают тайлсет с наибольшим firstgid, не большим GID, и вычисляют место тайла в картинке по columns, margin и spacing. У тайлового объекта точка привязки — нижний левый угол, у прямоугольника — верхний левый, а слои рисуют в том порядке, в каком они лежат в массиве. При загрузке проверяют, что в data ровно width × height чисел и что каждый GID попадает в свой тайлсет.
Содержание
- Что такое TMJ и как его получить
- Из чего состоит файл карты
- GID: какой тайл стоит в клетке
- Где тайл лежит в картинке: columns, margin, spacing
- Слой объектов: координаты и свойства
- Коллизии: отдельный слой или свойство тайла
- Порядок отрисовки слоёв
- Проверка данных при загрузке
- Если data — строка: base64 и сжатие
- Код на JavaScript
- Проверка в Node.js
- Что показал прогон: пять ловушек
- Что не подтвердилось и где мы поправили себя по документации
- Практический сценарий: подключить карту левел-дизайнера
- Когда вам это не подойдёт
Что такое 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 | размер клетки сетки в пикселях |
| карта | orientation | orthogonal, isometric, oblique, staggered или hexagonal |
| карта | renderorder | порядок клеток внутри слоя: right-down (по умолчанию), right-up, left-down, left-up; только для ортогональных карт |
| слой | type | tilelayer, objectgroup, imagelayer или group |
| tilelayer | data | массив GID или строка base64 |
| tilelayer | encoding, compression | csv (по умолчанию) или base64; zlib, gzip, zstd или пусто |
| objectgroup | objects, draworder | список объектов; topdown (по умолчанию) или index |
| тайлсет | firstgid | GID первого тайла этого набора |
| тайлсет | 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°.
| Бит | Маска | Ортогональная и изометрическая карта | Гексагональная карта |
|---|---|---|---|
| 32 | 0x80000000 | отражение по горизонтали (H) | то же |
| 31 | 0x40000000 | отражение по вертикали (V) | то же |
| 30 | 0x20000000 | отражение по диагонали (D) | поворот на 60° |
| 29 | 0x10000000 | не используется, но снимать обязательно | поворот на 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. Пример кода в документации прямо советует проверять размер данных, и это дешевле, чем потом искать, почему уровень съехал на одну клетку.
data— массив, а не строка; если строка, слой сохранён в base64 (о нём — ниже).data.length === width × heightдля слоёв конечной карты.- Каждый ненулевой 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 и контрольные числа из вывода.
- Формат. В Tiled формат слоя тайлов — CSV, тайлсеты встроены в карту (у каждого есть
imageиcolumns, а не толькоsource). Проверка:validateMapвернула 0 ошибок. - Флаги. Найдите в
dataлюбое число больше 268435455 (0x0FFFFFFF): после снятия флагов оно должно попасть в тайлсет. Проверка:stats.lostравно 0, как в разделе 2 вывода. - Тайлсеты. Тайлы из второго набора — не из первой картинки. Проверка: число тайлов по картинкам совпадает с числом тайлов каждого набора на карте.
- Зазоры. Нарисуйте тайл с наибольшим номером в наборе с margin или spacing: он должен совпасть с последним тайлом в редакторе, без полосок соседей.
- Объекты. Персонаж стоит на полу, а не в нём: низ рамки тайлового объекта — его
y. Проверка: 0 тайловых объектов в стене, как в разделе 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.
Читайте также:
- Тайловые сетки и устройство 2D-миров: от классики до современных редакторов уровней
- Головоломка с рычагами и дверями: связи объектов в данных уровня
- Память текстур в браузерной игре: размер атласа, форматы и выгрузка
- Загрузка ресурсов браузерной игры: экран загрузки, честный прогресс и подгрузка уровней по требованию
- Поиск пути A* на тайловой сетке: от поиска в ширину до рабочего кода на JavaScript