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`
parallaxoriginx	double	X coordinate of the parallax origin in pixels (since 1.8, default: 0)
parallaxoriginy	double	Y coordinate of the parallax origin in pixels (since 1.8, default: 0)
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
repeatx	bool	Whether the image drawn by this layer is repeated along the X axis. `imagelayer` only. (since Tiled 1.8)
repeaty	bool	Whether the image drawn by this layer is repeated along the Y axis. `imagelayer` only. (since Tiled 1.8)
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

The data of a tile layer can be stored as a native JSON array or as base64-encoded and optionally compressed binary data, the same as done in the TMX format. The tiles are referenced using Global Tile IDs.

{
  "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:

{
  "id":11,
  "properties":[
    {
      "name":"myProperty2",
      "type":"string",
      "value":"myProperty2_value"
    }],
  "terrain":[0, 1, 0, 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:

{
  "name":"ground",
  "tile":0
}

Wang Set

Field	Type	Description
colors	array	Array of Wang colors (since 1.5)
name	string	Name of the Wang set
properties	array	Array of Properties
tile	int	Local ID of tile representing the Wang set
type	string	`corner`, `edge` or `mixed` (since 1.5)
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 (since 1.5)
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`, `file`, `object` or `class` (since 0.16, with `color` and `file` added in 0.17, `object` added in 1.4 and `class` added in 1.8))
propertytype	string	Name of the custom property type, when applicable (since 1.8)
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.8

Added support for user-defined custom property types. A reference to the type is saved as the new propertytype property of Property.
The Property element can now have an arbitrary JSON object as its value, in case the property value is a class. In this case the type property is set to the new value class.
Added parallaxoriginx and parallaxoriginy properties to Map.
Added repeatx and repeaty properties to Layer (applies only to image layers at the moment).

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 and added a type field.
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.
Added object as possible type of Property.

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

Added a chunked data format, currently used for infinite maps.
Templates were added. Templates can be stored as JSON files with an Object Template object.
Tilesets can now contain Terrain Sets. They are saved in the new Wang Set object (since Tiled 1.1.5).