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

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:

"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 (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 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 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.

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