{
"openapi": "3.1.1",
"info": {
"title": "Tilemap Converter (TMX, Tiled JSON, PNG, collisions) API",
"version": "1.0.0",
"summary": "Convert Tiled TMX and JSON maps, render a PNG and merge collision rectangles.",
"description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
},
"servers": [
{
"url": "https://fliplinetilemapconverter.usefulweb.app"
}
],
"paths": {
"/api/v1/calculate": {
"post": {
"operationId": "calculate",
"summary": "Convert Tiled TMX and JSON maps, render a PNG and merge collision rectangles.",
"description": "Convert tile maps between Tiled TMX (CSV, base64, zlib or gzip layers), Tiled JSON, engine-neutral JSON and Flipline Tilemap Desk projects. Render a flattened PNG with flip flags and export solid tiles as merged collision rectangles for physics engines.\n\nMethodology:\n- Reads TMX and Tiled JSON (format 1.10) with embedded single-image tilesets, tile properties, collision objects, animations and Wang sets; tile layers in CSV or base64 (uncompressed, zlib or gzip; zstd is reported). Infinite maps are read from chunks and written as 16 × 16 chunks.\n- Global tile ids keep Tiled’s flip flags (bit 31 horizontal, 30 vertical, 29 anti-diagonal). Tilesets are renumbered consecutively from firstgid 1. The 120° hexagonal flag, layer groups (flattened), text objects and object templates are not supported and are reported.\n- The PNG render draws visible tile and image layers in order, bottom-left aligned like Tiled (isometric: centred on the diamond), applying flips in Tiled’s order (anti-diagonal, then horizontal, then vertical) and layer opacity. Missing images become placeholder colours; animated tiles show their first frame; objects are not drawn.\n- Collision export: solid cells (non-one-way rectangles covering the whole tile) are merged by greedy meshing — the widest run in a row extended downwards — so rectangles cover exactly the solid cells without overlap. Full-tile one-way tiles become horizontal runs; other shapes become polygons in map pixels with flips applied.\n- The same import, export, render and collision code runs in Flipline’s Tilemap Desk, so a map exported there converts to identical bytes here.",
"tags": [
"apps"
],
"x-mcp-tool": "flipline_tilemap_converter",
"x-owner-app": "flipline",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FliplineTilemapConverterInput"
},
"examples": {
"example1": {
"summary": "TMX with zlib layers and its tileset image → Tiled JSON",
"value": {
"map": "\n\n",
"images": {
"filename": "meadow.png",
"contentType": "image/png",
"contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAIAAAABgCAYAAADVenpJAAAFnklEQVR4AWPUjzf9z0AFoGcrhFNOU02c4fqtlyhilw6/o4a1WO3HZh86QLcfpJ8Yfeh2UMsf+MIP2T4YoJa9TFQxBQmAHIoOiA1UagFc9mFzG7n6aOknetrHAmMQSoEwQCjl4wtEfJ7AZT8hfbjcgU0fMh9mH7p+QvrQ1cL0hydrklR6rJx7Hac8OWFIagkMA3hLAHJTIj30UTM3k6sPWS21Sw96hSE8AQzlwMcFhoo+bIBeYQhPAEM1BVOqDxugtz5cgB5hiFIFDMUUTKk+XGCkVH8oCWAopmBy9Q22UmCgEjBGI3AkNuBwgZHQhsBIACMp8EfbEDi6gSOpFUypPlxgqCR8rAlgJLWCydU3XNoQOAeCRgOfPLcNFX0wtTgTwGjgk+a2oZqAqTYbONIBqXMZ2GYjidFHSD+xM5ow/VSfDRzJYKg1gkEAXgLQOwXC1OKbFSMFEDObiew2QjkQlz50QIv1AMSEIc3XAwyWupxcMBgao+QCetqHswSAWUhsSiQ1BWPTT2rpAVKLzX5i9OFzPzH6iAWE2gCUroMgteRGVzs6HTzE9I1OB+NQOzoRRJ4+sqeDB1tgjNShXErjjOzp4NGidOD0UTPhUzQdPBxGwvCBkZDwKZoOHupFMDUS8FBP+AM2HTxcitKhnvAHbDp4tCGGHYyo6eDhEohDuRQYNEPBo20I0vRhA+SE4ejOIAr0DfU2BEgtfC6A0r1tAz0bN9BzGUMVjA4FYwHk6huKAO9sIDYAyx2k5GBkfeiAVvvrCeViaudcepegMECpPwZVG4CagN65eLCUoKQCxtg57uASgJR6D1ktufpIAfhS/kC1HUi1D5/agQpDEKC4DTDadiBP32AJQ6pMB48O4pCnbzCMI1BlOnikDgFjA0NtHGHAp4OH+mzaQOmjVhgO+HTwaBuCPH3UCsNBMR082oYgTx81wpBppLeCydU3XEoBppHeCiZX33BJwOAqYCS3ginRNxwSMDgBjHbjyNM3HBIwxTuDRrtx5OkbLKXAoDkfgNz97TAw1NYzEKMfX1jg009sGILAoDsfYCSVAuTqo2ZYkL07mFopkF7n7cMAzG20vK8Am33ogNITQnCZQyoYVLuDqQ3IzY2DwT56hSF8PQAuQEpupqc+9Pl8UuxDbgOQ2nYYjGFBib7R6eARPo4wOh1Mor7hNo4wOh1Mor7hNo4wOh1Mhr7hNBcxOh1Mhr7h1IYYnQ4mU99wKQVGp4PJ1DdcEvDodDAF+oZDAh6dDqZA33BIwKPTwQOkb7CUAqM7g0Z4G4IJNKYOG1cnJzCQ9ZOiDxcYKoGPy9/EhiG6flLDHqZ/UAwF4wKjbQja6KPJUDA+B6JrRE6B+AA2fcSAwawPphY0C4ltDp9YO8jVR20/DekTQsjVN9qIRQCU9QAgjcRYgK6WXH2kAHR9A3XOP7X0UbqegVphP2Kng4dLKUC1NgCpGtHVjnbD6KuPWmE4oqeDRxPwCJ8OHk3Ao9PBZOsbLgl4dDqYTH3DJQGPTgdToG84JODR6WAK9A2HBDw6HTzE9FE7LEang0d4Ah7dGTTCEzDBvYEwjcSON5Oqb6iftw8DpM5JEHu+AK4wpHR3MUz/oLw3cKgDepce2ACxYU/27mBKb78m1T5C9pNiH0jtQO8OpvS0cxhYnLKTkWQHIQGy2wDk6httA1Cuj5olKNnTwcgrYoZiIIJyPnLpQaw+aiVE9BVF1A5DYsHodDAF+nCBoVQKjE4HD5A+bGAgSoHR6eAB0ocL0LsUGJ0OJlPfcCkFRqeDydQ3GBMwOWB0OpgCfYMtAZMDRqeDKdA3GBMwqWB0OniA9A2WUmB0OngYtiFIAaPTwUO8DUEpGN0ZRIE+bGColQIo5wOQaiFILaX71Acq8EGzgTB/kxP4+HZHjw4F00EfLjA6CEQaAADFzMkIoaNybQAAAABJRU5ErkJggg=="
},
"target": "tiled-json",
"encoding": "csv",
"render": true,
"scale": 2
}
},
"example2": {
"summary": "Tiled JSON with flipped slopes and one-way ledges → TMX",
"value": {
"map": "{\"type\":\"map\",\"version\":\"1.10\",\"orientation\":\"orthogonal\",\"renderorder\":\"right-down\",\"width\":12,\"height\":6,\"tilewidth\":16,\"tileheight\":16,\"infinite\":false,\"compressionlevel\":-1,\"nextlayerid\":2,\"nextobjectid\":1,\"tilesets\":[{\"firstgid\":1,\"name\":\"Platforms\",\"tilewidth\":16,\"tileheight\":16,\"spacing\":0,\"margin\":0,\"tilecount\":3,\"columns\":3,\"image\":\"platforms.png\",\"imagewidth\":48,\"imageheight\":16,\"tiles\":[{\"id\":0,\"type\":\"solid\",\"objectgroup\":{\"type\":\"objectgroup\",\"draworder\":\"index\",\"id\":2,\"name\":\"\",\"opacity\":1,\"visible\":true,\"x\":0,\"y\":0,\"objects\":[{\"id\":1,\"name\":\"\",\"type\":\"\",\"visible\":true,\"rotation\":0,\"x\":0,\"y\":0,\"width\":16,\"height\":16}]}},{\"id\":1,\"type\":\"ledge\",\"properties\":[{\"name\":\"material\",\"type\":\"string\",\"value\":\"wood\"}],\"objectgroup\":{\"type\":\"objectgroup\",\"draworder\":\"index\",\"id\":2,\"name\":\"\",\"opacity\":1,\"visible\":true,\"x\":0,\"y\":0,\"objects\":[{\"id\":1,\"name\":\"\",\"type\":\"\",\"visible\":true,\"rotation\":0,\"x\":0,\"y\":0,\"width\":16,\"height\":4,\"properties\":[{\"name\":\"oneWay\",\"type\":\"bool\",\"value\":true}]}]}},{\"id\":2,\"type\":\"slope\",\"objectgroup\":{\"type\":\"objectgroup\",\"draworder\":\"index\",\"id\":2,\"name\":\"\",\"opacity\":1,\"visible\":true,\"x\":0,\"y\":0,\"objects\":[{\"id\":1,\"name\":\"\",\"type\":\"\",\"visible\":true,\"rotation\":0,\"x\":0,\"y\":0,\"width\":0,\"height\":0,\"polygon\":[{\"x\":0,\"y\":16},{\"x\":16,\"y\":0},{\"x\":16,\"y\":16}]}]}}]}],\"layers\":[{\"id\":1,\"name\":\"Ground\",\"opacity\":1,\"visible\":true,\"x\":0,\"y\":0,\"type\":\"tilelayer\",\"width\":12,\"height\":6,\"data\":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,2,2,2,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,3,0,0,0,0,0,0,0,0,0,0,3,1,1,2147483651,0,0,0,0,2,2,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]}]}",
"target": "tmx",
"encoding": "base64-gzip",
"render": true,
"scale": 2
}
},
"example3": {
"summary": "Isometric autotiled map → engine-neutral JSON",
"value": {
"map": "\n\n",
"images": {
"filename": "meadow.png",
"contentType": "image/png",
"contentBase64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAAgCAYAAAD9qabkAAAEVklEQVR4AWMYBaNgFIyCUTAKRsEoGAWjYBSMglEwCkbBKBjqQD/e9D8ID7xLBgZQ6v+BDr+Bdv9I8D8juYYPZoDuaT1bITC9OGXnsPQvOqDU/7Fz3MH6Lx1+hyJ+ceFpuoQfpfaP+p94/w+rDIHL4+hguBYElPoflvBAQFNNnOH6rZdgNr0yArL9yIBY+9H9H56sCfcDMiDG/yAAC4Oh6n9Q/CPHIwwg+39YZAR8CR9bAMDAcCkICGV8XGEA8z+uhIeun1YZAVfBgw5w2U9MwYcvIxDyP0z/yrnXsdpPKcBV8KADSvyPzVyQ/5nIdfRQAcgeBgUANcFg6yOCIh5b5BMKA0LhgitD0gLQKr6oEQbo4Uur+MflVnT7QQUHcuEBavHgyvy4zB3tAlDBHhigVx+R3BYPDOBrAmPTP5SbwNgAoS4AMWFIiruIBcS2xIgBxLZ8RwcBqWAuvTIIsQkcBrA1+YixZ3QQkLguCQzQuyAg1l3oaof9ICA6gCUESiOE2IxHqwyDy35iEwG5BR+1wo9cQKn9lOontm8OAwNREBDjLnzxPyKmxSgFsISEa1QVHcASArULAHw1PqHR3lFAPsCWEYkZrKRW/LcdivtPTtOfmPgfTSAkAGJrBFplPGJrhNGMTxuAK/zJ7WqRYz8lYzzYwGhCIQPgqhGq7BbRJTxx1QijGZ8+AFdBQK/wxzVYORr/dAbo0zADYT+oMBgo+0c6GAzxT6n9FK0DGA4BMNQBPefo0cFIj39qrysZCEDR6OhANUEGSxMMBEgddKG2/chgoOzHN81ED/thYCDtH6pdQJI04Ctt6ZERiF2oMVCDcLTOCMTOTw/kICQtM8JIH4QldjaC6oOAxExDIQN6ToPRIyPA7Me1uQQd0HsakNYZgdyFMbRaK48N0HIalNz1APT0PzZ3UW0akNhdVvReCIMOaJURiN1lNdD+BwFqZgRSl6bSciEMJctgaeV/dLtovRCI3DCg2kIgXBmBVrukiLEfF6BFjTDSlgIPtzXxo0uBqbQUeDBvhsEGqD1YOdT8DwLEZARix3hggFYJn1qbXnCpJcf/2OwarC0eQmqRx2iokhEGeq04DFArI5Bq/0D7n9glyjCAnhGIXWEGA/Ss8fAVPOgtMGLHaGDmwjICuQUPrOU7VHYBogOKzwMAeXygEj82+0EJAT1xooOBnDenJSBlHz22MCBGP3r40iP+0WtcZPtBCRi5EAdlSJg8rcIAn35yASl2UVMtCAzr8wBIPRKKXHtgYDB2AUgZC8E1zUSvMR5c89uUngdAbBeQ2LX+pLqLWEBqS4waYyEj5jwAasxPD8ZBQFKbfMSoGwznAVBS8FDzPAB0MJTHQkbPA6DQHBgYKdOgo+cBDP9p0NHdQ0QAUhci0WohELmDXKOAMkDuegB6HxqKDkbPA6AyGOlLgUc6GLFLgUcBKhjpm3FGOhjo8xgGOv2NAigY3Q49ssFAn8dAjfgHABenDwpH5WukAAAAAElFTkSuQmCC"
},
"target": "neutral-json",
"encoding": "csv",
"render": true,
"scale": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "Calculation result envelope.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FliplineTilemapConverterResult"
}
}
}
},
"400": {
"description": "Malformed JSON body.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"422": {
"description": "Invalid input (see errors[]).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
},
"429": {
"description": "Rate limit exceeded (see Retry-After).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
}
}
}
}
},
"/api/v1/tool": {
"get": {
"operationId": "getToolDefinition",
"summary": "Inputs, output schema and examples for this tool",
"responses": {
"200": {
"description": "Tool definition.",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Problem": {
"type": "object",
"description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
"required": [
"type",
"title",
"status",
"detail"
],
"properties": {
"type": {
"type": "string"
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"detail": {
"type": "string"
},
"code": {
"type": "string"
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
},
"FliplineTilemapConverterInput": {
"type": "object",
"additionalProperties": false,
"properties": {
"map": {
"title": "Map text (TMX, Tiled JSON, engine-neutral JSON or Flipline tilemap project)",
"type": "string",
"maxLength": 4000000,
"default": ""
},
"file": {
"title": "Or: map file",
"type": "object",
"description": "Upload as {filename, contentType?, contentBase64}. Max 7813 KiB. Accepts .tmx,.tmj,.json,.xml.",
"additionalProperties": false,
"required": [
"filename",
"contentBase64"
],
"properties": {
"filename": {
"type": "string"
},
"contentType": {
"type": "string"
},
"contentBase64": {
"type": "string"
}
}
},
"images": {
"title": "Tileset and image-layer PNGs (one PNG or a ZIP of PNGs, matched by file name)",
"type": "object",
"description": "Upload as {filename, contentType?, contentBase64}. Max 23438 KiB. Accepts .png,.zip.",
"additionalProperties": false,
"required": [
"filename",
"contentBase64"
],
"properties": {
"filename": {
"type": "string"
},
"contentType": {
"type": "string"
},
"contentBase64": {
"type": "string"
}
}
},
"target": {
"title": "Convert to",
"type": "string",
"enum": [
"tmx",
"tiled-json",
"neutral-json",
"flipline",
"collision-json",
"png",
"zip"
],
"default": "tiled-json"
},
"encoding": {
"title": "Tile layer encoding (TMX and Tiled JSON)",
"type": "string",
"enum": [
"csv",
"base64",
"base64-zlib",
"base64-gzip"
],
"default": "csv"
},
"render": {
"title": "Also render a PNG preview",
"type": "boolean",
"default": true
},
"scale": {
"title": "PNG scale",
"type": "integer",
"minimum": 1,
"maximum": 8,
"default": 2
}
},
"required": []
},
"FliplineTilemapConverterResult": {
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"tool",
"computedAt",
"inputs",
"summary",
"result",
"units",
"assumptions",
"sources",
"warnings",
"presentation",
"links"
],
"properties": {
"schemaVersion": {
"type": "string",
"const": "1.0"
},
"tool": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"version"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"version": {
"type": "string"
}
}
},
"computedAt": {
"type": "string",
"format": "date-time"
},
"inputs": {
"type": "object",
"description": "Normalised inputs actually used, including applied defaults."
},
"summary": {
"type": "string"
},
"result": {
"type": "object",
"additionalProperties": false,
"required": [
"source",
"target",
"encoding",
"file",
"text",
"png",
"collision"
],
"properties": {
"source": {
"type": "object",
"additionalProperties": false,
"required": [
"format",
"orientation",
"width",
"height",
"infinite",
"tileWidth",
"tileHeight",
"tilesets",
"layers",
"placedTiles",
"objects",
"missingImages"
],
"properties": {
"format": {
"type": "string"
},
"orientation": {
"type": "string"
},
"width": {
"type": "integer"
},
"height": {
"type": "integer"
},
"infinite": {
"type": "boolean"
},
"tileWidth": {
"type": "integer"
},
"tileHeight": {
"type": "integer"
},
"tilesets": {
"type": "integer"
},
"layers": {
"type": "integer"
},
"placedTiles": {
"type": "integer"
},
"objects": {
"type": "integer"
},
"missingImages": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"target": {
"type": "string"
},
"encoding": {
"type": [
"string",
"null"
]
},
"file": {
"type": "object",
"additionalProperties": false,
"required": [
"artifactId",
"filename",
"mime",
"bytes",
"sha256",
"path"
],
"properties": {
"artifactId": {
"type": "string"
},
"filename": {
"type": "string"
},
"mime": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"sha256": {
"type": "string"
},
"path": {
"type": "string",
"description": "Download path on the same site (valid for about 2 hours)."
}
}
},
"text": {
"type": [
"string",
"null"
]
},
"png": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"artifactId",
"filename",
"mime",
"bytes",
"sha256",
"path"
],
"properties": {
"artifactId": {
"type": "string"
},
"filename": {
"type": "string"
},
"mime": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"sha256": {
"type": "string"
},
"path": {
"type": "string",
"description": "Download path on the same site (valid for about 2 hours)."
}
}
},
"collision": {
"type": "object",
"additionalProperties": false,
"required": [
"solidCells",
"mergedRects",
"oneWayRuns",
"shapes",
"skippedShapes",
"rects"
],
"properties": {
"solidCells": {
"type": "integer"
},
"mergedRects": {
"type": "integer"
},
"oneWayRuns": {
"type": "integer"
},
"shapes": {
"type": "integer"
},
"skippedShapes": {
"type": "integer"
},
"rects": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"x",
"y",
"width",
"height"
],
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
}
}
}
}
}
}
}
},
"units": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"assumptions": {
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"title"
],
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string"
},
"publisher": {
"type": "string"
},
"retrievedAt": {
"type": "string"
},
"note": {
"type": "string"
}
}
}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"presentation": {
"type": "array",
"items": {
"type": "object"
},
"description": "Display blocks used by the human page (same data)."
},
"links": {
"type": "object",
"additionalProperties": false,
"required": [
"human",
"api",
"openapi",
"methodology"
],
"properties": {
"human": {
"type": "string",
"format": "uri"
},
"api": {
"type": "string",
"format": "uri"
},
"openapi": {
"type": "string",
"format": "uri"
},
"methodology": {
"type": "string",
"format": "uri"
}
}
}
}
}
}
}
}