JSON Map Format

Tiled can export maps as JSON files. To do so, simply select “File > Export As” and select the JSON file type. You can export json from the command line with the --export-map option.

The fields found in the JSON format differ slightly from those in the TMX Map Format, but the meanings should remain the same.

The following fields can be found in a Tiled JSON file:

Map

Field Type Description
backgroundcolor string Hex-formatted color (#RRGGBB or #AARRGGBB) (optional)
compressionlevel int The compression level to use for tile layer data (defaults to -1, which means to use the algorithm default)
height int Number of tile rows
hexsidelength int Length of the side of a hex tile in pixels (hexagonal maps only)
infinite bool Whether the map has infinite dimensions
layers array Array of Layers
nextlayerid int Auto-increments for each layer
nextobjectid int Auto-increments for each placed object
orientation string orthogonal, isometric, staggered or hexagonal
properties array Array of Properties
renderorder string right-down (the default), right-up, left-down or left-up (currently only supported for orthogonal maps)
staggeraxis string x or y (staggered / hexagonal maps only)
staggerindex string odd or even (staggered / hexagonal maps only)
tiledversion string The Tiled version used to save the file
tileheight int Map grid height
tilesets array Array of Tilesets
tilewidth int Map grid width
type string map (since 1.0)
version string The JSON format version (previously a number, saved as string since 1.6)
width int Number of tile columns

Map Example

{
  "backgroundcolor":"#656667",
  "height":4,
  "layers":[ ],
  "nextobjectid":1,
  "orientation":"orthogonal",
  "properties":[
    {
      "name":"mapProperty1",
      "type":"string",
      "value":"one"
    },
    {
      "name":"mapProperty2",
      "type":"string",
      "value":"two"
    }],
  "renderorder":"right-down",
  "tileheight":32,
  "tilesets":[ ],
  "tilewidth":32,
  "version":1,
  "tiledversion":"1.0.3",
  "width":4
}

Layer

Field Type Description
chunks array Array of chunks (optional). tilelayer only.
compression string zlib, gzip, zstd (since Tiled 1.3) or empty (default). tilelayer only.
data array or string Array of unsigned int (GIDs) or base64-encoded data. tilelayer only.
draworder string topdown (default) or index. objectgroup only.
encoding string csv (default) or base64. tilelayer only.
height int Row count. Same as map height for fixed-size maps.
id int Incremental ID - unique across all layers
image string Image used by this layer. imagelayer only.
layers array Array of layers. group only.
name string Name assigned to this layer
objects array Array of objects. objectgroup only.
offsetx double Horizontal layer offset in pixels (default: 0)
offsety double Vertical layer offset in pixels (default: 0)
opacity double Value between 0 and 1
parallaxx double Horizontal parallax factor for this layer (default: 1). (since Tiled 1.5)
parallaxy double Vertical parallax factor for this layer (default: 1). (since Tiled 1.5)
properties array Array of Properties
startx int X coordinate where layer content starts (for infinite maps)
starty int Y coordinate where layer content starts (for infinite maps)
tintcolor string Hex-formatted tint color (#RRGGBB or #AARRGGBB) that is multiplied with any graphics drawn by this layer or any child layers (optional).
transparentcolor string Hex-formatted color (#RRGGBB) (optional). imagelayer only.
type string tilelayer, objectgroup, imagelayer or group
visible bool Whether layer is shown or hidden in editor
width int Column count. Same as map width for fixed-size maps.
x int Horizontal layer offset in tiles. Always 0.
y int Vertical layer offset in tiles. Always 0.

Tile Layer Example

{
  "data":[1, 2, 1, 2, 3, 1, 3, 1, 2, 2, 3, 3, 4, 4, 4, 1],
  "height":4,
  "name":"ground",
  "opacity":1,
  "properties":[
    {
      "name":"tileLayerProp",
      "type":"int",
      "value":1
    }],
  "type":"tilelayer",
  "visible":true,
  "width":4,
  "x":0,
  "y":0
}

Object Layer Example

{
  "draworder":"topdown",
  "height":0,
  "name":"people",
  "objects":[ ],
  "opacity":1,
  "properties":[
    {
      "name":"layerProp1",
      "type":"string",
      "value":"someStringValue"
    }],
  "type":"objectgroup",
  "visible":true,
  "width":0,
  "x":0,
  "y":0
}

Chunk

Chunks are used to store the tile layer data for infinite maps.

Field Type Description
data array or string Array of unsigned int (GIDs) or base64-encoded data
height int Height in tiles
width int Width in tiles
x int X coordinate in tiles
y int Y coordinate in tiles

Chunk Example

{
  "data":[1, 2, 1, 2, 3, 1, 3, 1, 2, 2, 3, 3, 4, 4, 4, 1, ...],
  "height":16,
  "width":16,
  "x":0,
  "y":-16,
}

Object

Field Type Description
ellipse bool Used to mark an object as an ellipse
gid int Global tile ID, only if object represents a tile
height double Height in pixels.
id int Incremental ID, unique across all objects
name string String assigned to name field in editor
point bool Used to mark an object as a point
polygon array Array of Points, in case the object is a polygon
polyline array Array of Points, in case the object is a polyline
properties array Array of Properties
rotation double Angle in degrees clockwise
template string Reference to a template file, in case object is a template instance
text Text Only used for text objects
type string String assigned to type field in editor
visible bool Whether object is shown in editor.
width double Width in pixels.
x double X coordinate in pixels
y double Y coordinate in pixels

Object Example

{
  "gid":5,
  "height":0,
  "id":1,
  "name":"villager",
  "properties":[
    {
      "name":"hp",
      "type":"int",
      "value":12
    }],
  "rotation":0,
  "type":"npc",
  "visible":true,
  "width":0,
  "x":32,
  "y":32
}

Ellipse Example

{
  "ellipse":true,
  "height":152,
  "id":13,
  "name":"",
  "rotation":0,
  "type":"",
  "visible":true,
  "width":248,
  "x":560,
  "y":808
}

Rectangle Example

{
  "height":184,
  "id":14,
  "name":"",
  "rotation":0,
  "type":"",
  "visible":true,
  "width":368,
  "x":576,
  "y":584
}

Point Example

{
  "point":true,
  "height":0,
  "id":20,
  "name":"",
  "rotation":0,
  "type":"",
  "visible":true,
  "width":0,
  "x":220,
  "y":350
}

Polygon Example

{
  "height":0,
  "id":15,
  "name":"",
  "polygon":[
  {
    "x":0,
    "y":0
  },
  {
    "x":152,
    "y":88
  },
  {
    "x":136,
    "y":-128
  },
  {
    "x":80,
    "y":-280
  },
  {
    "x":16,
    "y":-288
  }],
  "rotation":0,
  "type":"",
  "visible":true,
  "width":0,
  "x":-176,
  "y":432
}

Polyline Example

{
  "height":0,
  "id":16,
  "name":"",
  "polyline":[
  {
    "x":0,
    "y":0
  },
  {
    "x":248,
    "y":-32
  },
  {
    "x":376,
    "y":72
  },
  {
    "x":544,
    "y":288
  },
  {
    "x":656,
    "y":120
  },
  {
    "x":512,
    "y":0
  }],
  "rotation":0,
  "type":"",
  "visible":true,
  "width":0,
  "x":240,
  "y":88
}

Text Example

{
  "height":19,
  "id":15,
  "name":"",
  "text":
  {
    "text":"Hello World",
    "wrap":true
  },
  "rotation":0,
  "type":"",
  "visible":true,
  "width":248,
  "x":48,
  "y":136
}

Text

Field Type Description
bold bool Whether to use a bold font (default: false)
color string Hex-formatted color (#RRGGBB or #AARRGGBB) (default: #000000)
fontfamily string Font family (default: sans-serif)
halign string Horizontal alignment (center, right, justify or left (default))
italic bool Whether to use an italic font (default: false)
kerning bool Whether to use kerning when placing characters (default: true)
pixelsize int Pixel size of font (default: 16)
strikeout bool Whether to strike out the text (default: false)
text string Text
underline bool Whether to underline the text (default: false)
valign string Vertical alignment (center, bottom or top (default))
wrap bool Whether the text is wrapped within the object bounds (default: false)

Tileset

Field Type Description
backgroundcolor string Hex-formatted color (#RRGGBB or #AARRGGBB) (optional)
columns int The number of tile columns in the tileset
firstgid int GID corresponding to the first tile in the set
grid Grid (optional)
image string Image used for tiles in this set
imageheight int Height of source image in pixels
imagewidth int Width of source image in pixels
margin int Buffer between image edge and first tile (pixels)
name string Name given to this tileset
objectalignment string Alignment to use for tile objects (unspecified (default), topleft, top, topright, left, center, right, bottomleft, bottom or bottomright) (since 1.4)
properties array Array of Properties
source string The external file that contains this tilesets data
spacing int Spacing between adjacent tiles in image (pixels)
terrains array Array of Terrains (optional)
tilecount int The number of tiles in this tileset
tiledversion string The Tiled version used to save the file
tileheight int Maximum height of tiles in this set
tileoffset Tile Offset (optional)
tiles array Array of Tiles (optional)
tilewidth int Maximum width of tiles in this set
transformations Transformations Allowed transformations (optional)
transparentcolor string Hex-formatted color (#RRGGBB) (optional)
type string tileset (for tileset files, since 1.0)
version string The JSON format version (previously a number, saved as string since 1.6)
wangsets array Array of Wang sets (since 1.1.5)

Each tileset has a firstgid (first global ID) property which tells you the global ID of its first tile (the one with local tile ID 0). This allows you to map the global IDs back to the right tileset, and then calculate the local tile ID by subtracting the firstgid from the global tile ID. The first tileset always has a firstgid value of 1.

Grid

Specifies common grid settings used for tiles in a tileset. See <grid> in the TMX Map Format.

Field Type Description
height int Cell height of tile grid
orientation string orthogonal (default) or isometric
width int Cell width of tile grid

Tile Offset

See <tileoffset> in the TMX Map Format.

Field Type Description
x int Horizontal offset in pixels
y int Vertical offset in pixels (positive is down)

Transformations

See <transformations> in the TMX Map Format.

Field Type Description
hflip bool Tiles can be flipped horizontally
vflip bool Tiles can be flipped vertically
rotate bool Tiles can be rotated in 90-degree increments
preferuntransformed bool Whether untransformed tiles remain preferred, otherwise transformed tiles are used to produce more variations

Tileset Example

{
 "columns":19,
 "firstgid":1,
 "image":"..\/image\/fishbaddie_parts.png",
 "imageheight":480,
 "imagewidth":640,
 "margin":3,
 "name":"",
 "properties":[
   {
     "name":"myProperty1",
     "type":"string",
     "value":"myProperty1_value"
   }],
 "spacing":1,
 "tilecount":266,
 "tileheight":32,
 "tilewidth":32
}

Tile (Definition)

Field Type Description
animation array Array of Frames
id int Local ID of the tile
image string Image representing this tile (optional)
imageheight int Height of the tile image in pixels
imagewidth int Width of the tile image in pixels
objectgroup Layer Layer with type objectgroup, when collision shapes are specified (optional)
probability double Percentage chance this tile is chosen when competing with others in the editor (optional)
properties array Array of Properties
terrain array Index of terrain for each corner of tile (optional)
type string The type of the tile (optional)

A tileset that associates information with each tile, like its image path or terrain type, may include a tiles array property. Each tile has an id property, which specifies the local ID within the tileset.

For the terrain information, each value is a length-4 array where each element is the index of a terrain on one corner of the tile. The order of indices is: top-left, top-right, bottom-left, bottom-right.

Example:

"tiles":[
  {
    "id":0,
    "properties":[
      {
        "name":"myProperty1",
        "type":"string",
        "value":"myProperty1_value"
      }],
    "terrain":[0, 0, 0, 0]
  },
  {
    "id":11,
    "properties":[
      {
        "name":"myProperty2",
        "type":"string",
        "value":"myProperty2_value"
      }],
    "terrain":[0, 1, 0, 1]
  },
  {
    "id":12,
    "properties":[
      {
        "name":"myProperty3",
        "type":"string",
        "value":"myProperty3_value"
      }],
    "terrain":[1, 1, 1, 1]
  }
]

Frame

Field Type Description
duration int Frame duration in milliseconds
tileid int Local tile ID representing this frame

Terrain

Field Type Description
name string Name of terrain
properties array Array of Properties
tile int Local ID of tile representing terrain

Example:

"terrains":[
{
  "name":"ground",
  "tile":0
},
{
  "name":"chasm",
  "tile":12
},
{
  "name":"cliff",
  "tile":36
}],

Wang Set

Field Type Description
colors array Array of Wang colors
name string Name of the Wang set
properties array Array of Properties
tile int Local ID of tile representing the Wang set
wangtiles array Array of Wang tiles

Wang Color

Field Type Description
color string Hex-formatted color (#RRGGBB or #AARRGGBB)
name string Name of the Wang color
probability double Probability used when randomizing
properties array Array of Properties
tile int Local ID of tile representing the Wang color

Example:

{
  "color": "#d31313",
  "name": "Rails",
  "probability": 1,
  "tile": 18
}

Wang Tile

Field Type Description
tileid int Local ID of tile
wangid array Array of Wang color indexes (uchar[8])

Example:

{
  "tileid": 0,
  "wangid": [2, 0, 1, 0, 1, 0, 2, 0]
}

Object Template

An object template is written to its own file and referenced by any instances of that template.

Field Type Description
type string template
tileset Tileset External tileset used by the template (optional)
object Object The object instantiated by this template

Property

Field Type Description
name string Name of the property
type string Type of the property (string (default), int, float, bool, color or file (since 0.16, with color and file added in 0.17))
value value Value of the property

Point

A point on a polygon or a polyline, relative to the position of the object.

Field Type Description
x double X coordinate in pixels
y double Y coordinate in pixels

Changelog

Tiled 1.7

  • The Tile (Definition) objects in a tileset are no longer always saved with increasing IDs. They are now saved in the display order, which can be changed in Tiled.

Tiled 1.6

  • The version property is now written as a string (“1.6”) instead of a number (1.5).

Tiled 1.5

  • Unified cornercolors and edgecolors properties of Wang Set as the new colors property.
  • Wang Color can now store properties.
  • Added transformations property to Tileset (see Transformations).
  • Removed dflip, hflip and vflip properties from Wang Tile (no longer supported).

Tiled 1.4

  • Added objectalignment to the Tileset object.
  • Added tintcolor to the Layer object.

Tiled 1.3

  • Added an editorsettings property to top-level Map and Tileset objects, which is used to store editor specific settings that are generally not relevant when loading a map or tileset.
  • Added support for Zstandard compression for tile layer data ("compression": "zstd" on tile layer objects).
  • Added the compressionlevel property to the Map object, which stores the compression level to use for compressed tile layer data.

Tiled 1.2

  • Added nextlayerid to the Map object.
  • Added id to the Layer object.
  • The tiles in a Tileset are now stored as an array instead of an object. Previously the tile IDs were stored as string keys of the “tiles” object, now they are stored as id property of each Tile object.
  • Custom tile properties are now stored within each Tile instead of being included as tileproperties in the Tileset object.
  • Custom properties are now stored in an array instead of an object where the property names were the keys. Each property is now an object that stores the name, type and value of the property. The separate propertytypes and tilepropertytypes properties have been removed.

Tiled 1.1