# LDtk Json structure (version 1.5.3)
## 1. LDtk Json root
This is the root of any Project JSON file. It contains:
- the project settings,
- an array of levels,
- a group of definitions (that can probably be safely ignored for most users).
Value | Type | Description
-- | -- | --
`bgColor` | String
*Hex color "#rrggbb"* | Project background color
`defs` | [Definitions](#ldtk-DefinitionsJson) | A structure containing all the definitions of this project
`externalLevels`
 | Bool | If TRUE, one file will be saved for the project (incl. all its definitions) and one file in a sub-folder for each level.
`iid`
 | String | Unique project identifier
`jsonVersion` | String | File format version
`levels` | Array of [Level](#ldtk-LevelJson) | All levels. The order of this array is only relevant in `LinearHorizontal` and `linearVertical` world layouts (see `worldLayout` value).
Otherwise, you should refer to the `worldX`,`worldY` coordinates of each Level.
`toc`
 | Array of Object | All instances of entities that have their `exportToToc` flag enabled are listed in this array.
This array contains objects with the following fields:
- **`identifier`** **(String**)
- **`instancesData`** **(Array of Object**) 
- **`fields`** **(Untyped**) : *An object containing the values of all entity fields with the `exportToToc` option enabled. This object typing depends on actual field value types.*
- **`heiPx`** **(Int**)
- **`iids`** **([Reference to an Entity instance](#ldtk-EntityReferenceInfos)**) : *IID information of this instance*
- **`widPx`** **(Int**)
- **`worldX`** **(Int**)
- **`worldY`** **(Int**)
- **`instances`** **(Array of [Reference to an Entity instance](#ldtk-EntityReferenceInfos)**) : ***WARNING**: this deprecated value will be *removed* completely on version 1.7.0+* ** *Replaced by: `instancesData`*
`worldGridHeight`
Only *'GridVania' layouts*
 | Int *(can be `null`)* | **WARNING**: this field will move to the `worlds` array after the "multi-worlds" update. It will then be `null`. You can enable the Multi-worlds advanced project option to enable the change immediately.
Height of the world grid in pixels.
`worldGridWidth`
Only *'GridVania' layouts*
 | Int *(can be `null`)* | **WARNING**: this field will move to the `worlds` array after the "multi-worlds" update. It will then be `null`. You can enable the Multi-worlds advanced project option to enable the change immediately.
Width of the world grid in pixels.
`worldLayout`
 | Enum *(can be `null`)* | **WARNING**: this field will move to the `worlds` array after the "multi-worlds" update. It will then be `null`. You can enable the Multi-worlds advanced project option to enable the change immediately.
An enum that describes how levels are organized in this project (ie. linearly or in a 2D space).
Possible values: <`null`>, `Free`, `GridVania`, `LinearHorizontal`, `LinearVertical`
`worlds`
 | Array of [World](#ldtk-WorldJson) | This array will be empty, unless you enable the Multi-Worlds in the project advanced settings.
- in current version, a LDtk project file can only contain a single world with multiple levels in it. In this case, levels and world layout related settings are stored in the root of the JSON.
- with "Multi-worlds" enabled, there will be a `worlds` array in root, each world containing levels and layout settings. Basically, it's pretty much only about moving the `levels` array to the `worlds` array, along with world layout related values (eg. `worldGridWidth` etc).
If you want to start supporting this future update easily, please refer to this documentation: https://github.com/deepnight/ldtk/issues/231
`appBuildId`
*Only used by editor*
 | Float | LDtk application build identifier.
This is only used to identify the LDtk version that generated this particular project file, which can be useful for specific bug fixing. Note that the build identifier is just the date of the release, so it's not unique to each user (one single global ID per LDtk public release), and as a result, completely anonymous.
`backupLimit`
*Only used by editor*
 | Int | Number of backup files to keep, if the `backupOnSave` is TRUE
`backupOnSave`
*Only used by editor*
 | Bool | If TRUE, an extra copy of the project will be created in a sub folder, when saving.
`backupRelPath`
*Only used by editor*
 | String *(can be `null`)* | Target relative path to store backup files
`customCommands`
*Only used by editor*
 | Array of Object | An array of command lines that can be ran manually by the user
This array contains objects with the following fields:
- **`command`** **(String**)
- **`when`** **(Enum**) : *Possible values: `Manual`, `AfterLoad`, `BeforeSave`, `AfterSave`*
`defaultEntityHeight`
*Only used by editor*
 | Int | Default height for new entities
`defaultEntityWidth`
*Only used by editor*
 | Int | Default width for new entities
`defaultGridSize`
*Only used by editor* | Int | Default grid size for new layers
`defaultLevelBgColor`
*Only used by editor*
 | String
*Hex color "#rrggbb"* | Default background color of levels
`defaultLevelHeight`
*Only used by editor*
 | Int *(can be `null`)* | **WARNING**: this field will move to the `worlds` array after the "multi-worlds" update. It will then be `null`. You can enable the Multi-worlds advanced project option to enable the change immediately.
Default new level height
`defaultLevelWidth`
*Only used by editor*
 | Int *(can be `null`)* | **WARNING**: this field will move to the `worlds` array after the "multi-worlds" update. It will then be `null`. You can enable the Multi-worlds advanced project option to enable the change immediately.
Default new level width
`defaultPivotX`
*Only used by editor* | Float | Default X pivot (0 to 1) for new entities
`defaultPivotY`
*Only used by editor* | Float | Default Y pivot (0 to 1) for new entities
`dummyWorldIid`
*Only used by editor*
 | String | If the project isn't in MultiWorlds mode, this is the IID of the internal "dummy" World.
`exportLevelBg`
*Only used by editor*
 | Bool | If TRUE, the exported PNGs will include the level background (color or image).
`exportTiled`
*Only used by editor* | Bool | If TRUE, a Tiled compatible file will also be generated along with the LDtk JSON file (default is FALSE)
`flags`
*Only used by editor*
 | Array of Enum | An array containing various advanced flags (ie. options or other states).
Possible values: `DiscardPreCsvIntGrid`, `ExportOldTableOfContentData`, `ExportPreCsvIntGridFormat`, `IgnoreBackupSuggest`, `PrependIndexToLevelFileNames`, `MultiWorlds`, `UseMultilinesType`
`identifierStyle`
*Only used by editor*
 | Enum | Naming convention for Identifiers (first-letter uppercase, full uppercase etc.)
Possible values: `Capitalize`, `Uppercase`, `Lowercase`, `Free`
`imageExportMode`
*Only used by editor*
 | Enum | "Image export" option when saving project.
Possible values: `None`, `OneImagePerLayer`, `OneImagePerLevel`, `LayersAndLevels`
`levelNamePattern`
*Only used by editor*
 | String | The default naming convention for level identifiers.
`minifyJson`
*Only used by editor* | Bool | If TRUE, the Json is partially minified (no indentation, nor line breaks, default is FALSE)
`nextUid`
*Only used by editor* | Int | Next Unique integer ID available
`pngFilePattern`
*Only used by editor*
 | String *(can be `null`)* | File naming pattern for exported PNGs
`simplifiedExport`
*Only used by editor*
 | Bool | If TRUE, a very simplified will be generated on saving, for quicker & easier engine integration.
`tutorialDesc`
*Only used by editor*
 | String *(can be `null`)* | This optional description is used by LDtk Samples to show up some informations and instructions.
~~`exportPng`~~
*Only used by editor*
*DEPRECATED!*
 | Bool *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 0.9.3
Replaced by: `imageExportMode`
## 1.1. World 
**IMPORTANT**: this type is available as a preview. You can rely on it to update your importers, for when it will be officially available.
A World contains multiple levels, and it has its own layout settings.
Value | Type | Description
-- | -- | --
`identifier`
 | String | User defined unique identifier
`iid`
 | String | Unique instance identifer
`levels`
 | Array of [Level](#ldtk-LevelJson) | All levels from this world. The order of this array is only relevant in `LinearHorizontal` and `linearVertical` world layouts (see `worldLayout` value). Otherwise, you should refer to the `worldX`,`worldY` coordinates of each Level.
`worldGridHeight`
Only *'GridVania' layouts*
 | Int | Height of the world grid in pixels.
`worldGridWidth`
Only *'GridVania' layouts*
 | Int | Width of the world grid in pixels.
`worldLayout`
 | Enum | An enum that describes how levels are organized in this project (ie. linearly or in a 2D space).
Possible values: `Free`, `GridVania`, `LinearHorizontal`, `LinearVertical`
`defaultLevelHeight`
*Only used by editor*
 | Int | Default new level height
`defaultLevelWidth`
*Only used by editor*
 | Int | Default new level width
## 2. Level
This section contains all the level data. It can be found in 2 distinct forms, depending on Project current settings:
- If "*Separate level files*" is **disabled** (default): full level data is *embedded* inside the main Project JSON file,
- If "*Separate level files*" is **enabled**: level data is stored in *separate* standalone `.ldtkl` files (one per level). In this case, the main Project JSON file will still contain most level data, except heavy sections, like the `layerInstances` array (which will be null). The `externalRelPath` string points to the `ldtkl` file.
A `ldtkl` file is just a JSON file containing exactly what is described below.
Value | Type | Description
-- | -- | --
`__bgColor`
 | String
*Hex color "#rrggbb"* | Background color of the level (same as `bgColor`, except the default value is automatically used here if its value is `null`)
`__bgPos`
Only *If background image exists*
 | Object *(can be `null`)* | Position informations of the background image, if there is one.
This object contains the following fields:
- **`cropRect`** **(Array of Float**) : *An array of 4 float values describing the cropped sub-rectangle of the displayed background image. This cropping happens when original is larger than the level bounds. Array format: `[ cropX, cropY, cropWidth, cropHeight ]`*
- **`scale`** **(Array of Float**) : *An array containing the `[scaleX,scaleY]` values of the **cropped** background image, depending on `bgPos` option.*
- **`topLeftPx`** **(Array of Int**) : *An array containing the `[x,y]` pixel coordinates of the top-left corner of the **cropped** background image, depending on `bgPos` option.*
`__neighbours`
  | Array of Object | An array listing all other levels touching this one on the world map. Since 1.4.0, this includes levels that overlap in the same world layer, or in nearby world layers.
Only relevant for world layouts where level spatial positioning is manual (ie. GridVania, Free). For Horizontal and Vertical layouts, this array is always empty.
This array contains objects with the following fields:
- **`dir`** **(String**)  : *A lowercase string tipping on the level location (`n`orth, `s`outh, `w`est, `e`ast).
Since 1.4.0, this value can also be `<` (neighbour depth is lower), `>` (neighbour depth is greater) or `o` (levels overlap and share the same world depth).
Since 1.5.3, this value can also be `nw`,`ne`,`sw` or `se` for levels only touching corners.* - **`levelIid`** **(String**)  : *Neighbour Instance Identifier*
- **`levelUid`** **(Int *(can be `null`)***)  : ***WARNING**: this deprecated value is no longer exported since version 1.2.0* ** *Replaced by: `levelIid`*
`bgRelPath`
 | String *(can be `null`)* | The *optional* relative path to the level background image.
`externalRelPath`
 | String *(can be `null`)* | This value is not null if the project option "*Save levels separately*" is enabled. In this case, this **relative** path points to the level Json file.
`fieldInstances`
 | Array of [Field instance](#ldtk-FieldInstanceJson) | An array containing this level custom field values.
`identifier` | String | User defined unique identifier
`iid`
 | String | Unique instance identifier
`layerInstances`
 | Array of [Layer instance](#ldtk-LayerInstanceJson) *(can be `null`)* | An array containing all Layer instances. **IMPORTANT**: if the project option "*Save levels separately*" is enabled, this field will be `null`.
This array is **sorted in display order**: the 1st layer is the top-most and the last is behind.
`pxHei` | Int | Height of the level in pixels
`pxWid` | Int | Width of the level in pixels
`uid` | Int | Unique Int identifier
`worldDepth`
 | Int | Index that represents the "depth" of the level in the world. Default is 0, greater means "above", lower means "below".
This value is mostly used for display only and is intended to make stacking of levels easier to manage.
`worldX`
  | Int | World X coordinate in pixels.
Only relevant for world layouts where level spatial positioning is manual (ie. GridVania, Free). For Horizontal and Vertical layouts, the value is always -1 here.
`worldY`
  | Int | World Y coordinate in pixels.
Only relevant for world layouts where level spatial positioning is manual (ie. GridVania, Free). For Horizontal and Vertical layouts, the value is always -1 here.
`__smartColor`
*Only used by editor*
 | String
*Hex color "#rrggbb"* | The "guessed" color for this level in the editor, decided using either the background color or an existing custom field.
`bgColor`
*Only used by editor*
 | String *(can be `null`)*
*Hex color "#rrggbb"* | Background color of the level. If `null`, the project `defaultLevelBgColor` should be used.
`bgPivotX`
*Only used by editor*
 | Float | Background image X pivot (0-1)
`bgPivotY`
*Only used by editor*
 | Float | Background image Y pivot (0-1)
`bgPos`
*Only used by editor*
 | Enum *(can be `null`)* | An enum defining the way the background image (if any) is positioned on the level. See `__bgPos` for resulting position info.
Possible values: <`null`>, `Unscaled`, `Contain`, `Cover`, `CoverDirty`, `Repeat`
`useAutoIdentifier`
*Only used by editor*
 | Bool | If TRUE, the level identifier will always automatically use the naming pattern as defined in `Project.levelNamePattern`. Becomes FALSE if the identifier is manually modified by user.
## 2.1. Layer instance
Value | Type | Description
-- | -- | --
`__cHei` | Int | Grid-based height
`__cWid` | Int | Grid-based width
`__gridSize` | Int | Grid size
`__identifier` | String | Layer definition identifier
`__opacity`
 | Float | Layer opacity as Float [0-1]
`__pxTotalOffsetX`
 | Int | Total layer X pixel offset, including both instance and definition offsets.
`__pxTotalOffsetY`
 | Int | Total layer Y pixel offset, including both instance and definition offsets.
`__tilesetDefUid`
Only *Tile layers, Auto-layers*
 | Int *(can be `null`)* | The definition UID of corresponding Tileset, if any.
`__tilesetRelPath`
Only *Tile layers, Auto-layers*
 | String *(can be `null`)* | The relative path to corresponding Tileset, if any.
`__type` | String | Layer type (possible values: IntGrid, Entities, Tiles or AutoLayer)
`autoLayerTiles`
Only *Auto-layers*
 | Array of [Tile instance](#ldtk-Tile) | An array containing all tiles generated by Auto-layer rules. The array is already sorted in display order (ie. 1st tile is beneath 2nd, which is beneath 3rd etc.).
Note: if multiple tiles are stacked in the same cell as the result of different rules, all tiles behind opaque ones will be discarded.
`entityInstances`
Only *Entity layers* | Array of [Entity instance](#ldtk-EntityInstanceJson) |
`gridTiles`
Only *Tile layers* | Array of [Tile instance](#ldtk-Tile) |
`iid` | String | Unique layer instance identifier
`intGridCsv`
Only *IntGrid layers*
 | Array of Int | A list of all values in the IntGrid layer, stored in CSV format (Comma Separated Values).
Order is from left to right, and top to bottom (ie. first row from left to right, followed by second row, etc).
`0` means "empty cell" and IntGrid values start at 1.
The array size is `__cWid` x `__cHei` cells.
`layerDefUid` | Int | Reference the Layer definition UID
`levelId` | Int | Reference to the UID of the level containing this layer instance
`overrideTilesetUid`
Only *Tile layers* | Int *(can be `null`)* | This layer can use another tileset by overriding the tileset UID here.
`pxOffsetX`
 | Int | X offset in pixels to render this layer, usually 0 (IMPORTANT: this should be added to the `LayerDef` optional offset, so you should probably prefer using `__pxTotalOffsetX` which contains the total offset value)
`pxOffsetY`
 | Int | Y offset in pixels to render this layer, usually 0 (IMPORTANT: this should be added to the `LayerDef` optional offset, so you should probably prefer using `__pxTotalOffsetX` which contains the total offset value)
`visible`
 | Bool | Layer instance visibility
`optionalRules`
*Only used by editor*
 | Array of Int | An Array containing the UIDs of optional rules that were enabled in this specific layer instance.
`seed`
Only *Auto-layers*
*Only used by editor* | Int | Random seed used for Auto-Layers rendering
~~`intGrid`~~
Only *IntGrid layers*
*DEPRECATED!*
 | Array of Object *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.0.0
Replaced by: `intGridCsv`
## 2.1.1. Tile instance 
This structure represents a single tile from a given Tileset.
Value | Type | Description
-- | -- | --
`a`
 | Float | Alpha/opacity of the tile (0-1, defaults to 1)
`f` | Int | "Flip bits", a 2-bits integer to represent the mirror transformations of the tile.
- Bit 0 = X flip
- Bit 1 = Y flip
Examples: f=0 (no flip), f=1 (X flip only), f=2 (Y flip only), f=3 (both flips)
`px`
 | Array of Int | Pixel coordinates of the tile in the **layer** (`[x,y]` format). Don't forget optional layer offsets, if they exist!
`src` | Array of Int | Pixel coordinates of the tile in the **tileset** (`[x,y]` format)
`t`
 | Int | The *Tile ID* in the corresponding tileset.
`d`
*Only used by editor*
 | Array of Int | Internal data used by the editor.
For auto-layer tiles: `[ruleId, coordId]`.
For tile-layer tiles: `[coordId]`.
## 2.2. Entity instance
Value | Type | Description
-- | -- | --
`__grid`
 | Array of Int | Grid-based coordinates (`[x,y]` format)
`__identifier` | String | Entity definition identifier
`__pivot`
 | Array of Float | Pivot coordinates (`[x,y]` format, values are from 0 to 1) of the Entity
`__smartColor`
 | String | The entity "smart" color, guessed from either Entity definition, or one its field instances.
`__tags`
 | Array of String | Array of tags defined in this Entity definition
`__tile`
  | [Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)* | Optional TilesetRect used to display this entity (it could either be the default Entity tile, or some tile provided by a field value, like an Enum).
`__worldX`
  | Int *(can be `null`)* | X world coordinate in pixels. Only available in GridVania or Free world layouts.
`__worldY`
  | Int *(can be `null`)* | Y world coordinate in pixels Only available in GridVania or Free world layouts.
`defUid` | Int | Reference of the **Entity definition** UID
`fieldInstances` | Array of [Field instance](#ldtk-FieldInstanceJson) | An array of all custom fields and their values.
`height`
 | Int | Entity height in pixels. For non-resizable entities, it will be the same as Entity definition.
`iid`
 | String | Unique instance identifier
`px`
 | Array of Int | Pixel coordinates (`[x,y]` format) in current level coordinate space. Don't forget optional layer offsets, if they exist!
`width`
 | Int | Entity width in pixels. For non-resizable entities, it will be the same as Entity definition.
## 2.3. Field instance
Value | Type | Description
-- | -- | --
`__identifier` | String | Field definition identifier
`__tile`
 | [Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)* | Optional TilesetRect used to display this field (this can be the field own Tile, or some other Tile guessed from the value, like an Enum).
`__type` | String | Type of the field, such as `Int`, `Float`, `String`, `Enum(my_enum_name)`, `Bool`, etc.
NOTE: if you enable the advanced option **Use Multilines type**, you will have "*Multilines*" instead of "*String*" when relevant.
`__value` | Various possible types | Actual value of the field instance. The value type varies, depending on `__type`:
- For **classic types** (ie. Integer, Float, Boolean, String, Text and FilePath), you just get the actual value with the expected type.
- For **Color**, the value is an hexadecimal string using "#rrggbb" format.
- For **Enum**, the value is a String representing the selected enum value.
- For **Point**, the value is a [GridPoint](#ldtk-GridPoint) object.
- For **Tile**, the value is a [TilesetRect](#ldtk-TilesetRect) object.
- For **EntityRef**, the value is an [EntityReferenceInfos](#ldtk-EntityReferenceInfos) object.
If the field is an array, then this `__value` will also be a JSON array.
`defUid` | Int | Reference of the **Field definition** UID
`realEditorValues`
*Only used by editor* | Array of Enum *(can be `null`)* | Editor internal raw values
## 2.3.1. Reference to an Entity instance 
This object describes the "location" of an Entity instance in the project worlds.
Value | Type | Description
-- | -- | --
`entityIid`
 | String | IID of the refered EntityInstance
`layerIid`
 | String | IID of the LayerInstance containing the refered EntityInstance
`levelIid`
 | String | IID of the Level containing the refered EntityInstance
`worldIid`
 | String | IID of the World containing the refered EntityInstance
## 2.3.2. Grid point 
This object is just a grid-based coordinate used in Field values.
Value | Type | Description
-- | -- | --
`cx`
 | Int | X grid-based coordinate
`cy`
 | Int | Y grid-based coordinate
## 3. Definitions
If you're writing your own LDtk importer, you should probably just ignore *most* stuff in the `defs` section, as it contains data that are mostly important to the editor. To keep you away from the `defs` section and avoid some unnecessary JSON parsing, important data from definitions is often duplicated in fields prefixed with a double underscore (eg. `__identifier` or `__type`).
The 2 only definition types you might need here are **Tilesets** and **Enums**.
Value | Type | Description
-- | -- | --
`entities` | Array of [Entity definition](#ldtk-EntityDefJson) | All entities definitions, including their custom fields
`enums` | Array of [Enum definition](#ldtk-EnumDefJson) | All internal enums
`externalEnums` | Array of [Enum definition](#ldtk-EnumDefJson) | Note: external enums are exactly the same as `enums`, except they have a `relPath` to point to an external source file.
`layers` | Array of [Layer definition](#ldtk-LayerDefJson) | All layer definitions
`levelFields`
 | Array of [Field definition](#ldtk-FieldDefJson) | All custom fields available to all levels.
`tilesets` | Array of [Tileset definition](#ldtk-TilesetDefJson) | All tilesets
## 3.1. Layer definition
Value | Type | Description
-- | -- | --
`__type` | String | Type of the layer (*IntGrid, Entities, Tiles or AutoLayer*)
`autoSourceLayerDefUid`
Only *Auto-layers* | Int *(can be `null`)* |
`displayOpacity` | Float | Opacity of the layer (0 to 1.0)
`gridSize` | Int | Width and height of the grid in pixels
`identifier` | String | User defined unique identifier
`intGridValues`
Only *IntGrid layer*
 | Array of Object | An array that defines extra optional info for each IntGrid value.
WARNING: the array order is not related to actual IntGrid values! As user can re-order IntGrid values freely, you may value "2" before value "1" in this array.
This array contains objects with the following fields:
- **`color`** **(String**) *Hex color "#rrggbb"*
- **`groupUid`** **(Int**)  : *Parent group identifier (0 if none)*
- **`identifier`** **(String *(can be `null`)***) : *User defined unique identifier*
- **`tile`** **([Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)***) 
- **`value`** **(Int**)  : *The IntGrid value itself*
`intGridValuesGroups`
Only *IntGrid layer*
 | Array of Object | Group informations for IntGrid values
This array contains objects with the following fields:
- **`color`** **(String *(can be `null`)***) : *User defined color*
- **`identifier`** **(String *(can be `null`)***) : *User defined string identifier*
- **`uid`** **(Int**) : *Group unique ID*
`parallaxFactorX`
 | Float | Parallax horizontal factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.
`parallaxFactorY`
 | Float | Parallax vertical factor (from -1 to 1, defaults to 0) which affects the scrolling speed of this layer, creating a fake 3D (parallax) effect.
`parallaxScaling`
 | Bool | If true (default), a layer with a parallax factor will also be scaled up/down accordingly.
`pxOffsetX`
 | Int | X offset of the layer, in pixels (IMPORTANT: this should be added to the `LayerInstance` optional offset)
`pxOffsetY`
 | Int | Y offset of the layer, in pixels (IMPORTANT: this should be added to the `LayerInstance` optional offset)
`tilesetDefUid`
Only *Tile layers, Auto-layers*
 | Int *(can be `null`)* | Reference to the default Tileset UID being used by this layer definition.
**WARNING**: some layer *instances* might use a different tileset. So most of the time, you should probably use the `__tilesetDefUid` value found in layer instances.
Note: since version 1.0.0, the old `autoTilesetDefUid` was removed and merged into this value.
`uid` | Int | Unique Int identifier
`autoRuleGroups`
Only *Auto-layers*
*Only used by editor* | Array of Object | Contains all the auto-layer rule definitions.
This array contains objects with the following fields:
- **`active`** **(Bool**)
- **`biomeRequirementMode`** **(Int**) 
- ~~collapsed~~ **(Bool**) *This field was removed in 1.0.0 and should no longer be used.*
- **`color`** **(String *(can be `null`)***) 
- **`icon`** **([Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)***) 
- **`isOptional`** **(Bool**) 
- **`name`** **(String**)
- **`requiredBiomeValues`** **(Array of String**) 
- **`rules`** **(Array of [Auto-layer rule definition](#ldtk-AutoRuleDef)**)
- **`uid`** **(Int**)
- **`usesWizard`** **(Bool**) 
`autoTilesKilledByOtherLayerUid`
Only *Auto layers*
*Only used by editor*
 | Int *(can be `null`)* |
`biomeFieldUid`
*Only used by editor*
 | Int *(can be `null`)* |
`canSelectWhenInactive`
*Only used by editor*
 | Bool | Allow editor selections when the layer is not currently active.
`doc`
*Only used by editor*
 | String *(can be `null`)* | User defined documentation for this element to provide help/tips to level designers.
`excludedTags`
Only *Entity layer*
*Only used by editor*
 | Array of String | An array of tags to forbid some Entities in this layer
`guideGridHei`
*Only used by editor*
 | Int | Height of the optional "guide" grid in pixels
`guideGridWid`
*Only used by editor*
 | Int | Width of the optional "guide" grid in pixels
`hideFieldsWhenInactive`
*Only used by editor*
 | Bool |
`hideInList`
*Only used by editor*
 | Bool | Hide the layer from the list on the side of the editor view.
`inactiveOpacity`
*Only used by editor*
 | Float | Alpha of this layer when it is not the active one.
`renderInWorldView`
*Only used by editor*
 | Bool | If TRUE, the content of this layer will be used when rendering levels in a simplified way for the world view
`requiredTags`
Only *Entity layer*
*Only used by editor*
 | Array of String | An array of tags to filter Entities that can be added to this layer
`tilePivotX`
Only *Tile layers*
*Only used by editor* | Float | If the tiles are smaller or larger than the layer grid, the pivot value will be used to position the tile relatively its grid cell.
`tilePivotY`
Only *Tile layers*
*Only used by editor* | Float | If the tiles are smaller or larger than the layer grid, the pivot value will be used to position the tile relatively its grid cell.
`type`
*Only used by editor* | Enum | Type of the layer as Haxe Enum
Possible values: `IntGrid`, `Entities`, `Tiles`, `AutoLayer`
`uiColor`
*Only used by editor*
 | String *(can be `null`)* | User defined color for the UI
`uiFilterTags`
*Only used by editor*
 | Array of String | Display tags
`useAsyncRender`
Only *Tile layers, Auto-layers*
*Only used by editor*
 | Bool | Asynchronous rendering option for large/complex layers
~~`autoTilesetDefUid`~~
Only *Auto-layers*
*DEPRECATED!*
 | Int *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.2.0
Replaced by: `tilesetDefUid`
## 3.1.1. Auto-layer rule definition
This complex section isn't meant to be used by game devs at all, as these rules are completely resolved internally by the editor before any saving. You should just ignore this part.
Value | Type | Description
-- | -- | --
`active`
*Only used by editor* | Bool | If FALSE, the rule effect isn't applied, and no tiles are generated.
`alpha`
*Only used by editor* | Float |
`breakOnMatch`
*Only used by editor* | Bool | When TRUE, the rule will prevent other rules to be applied in the same cell if it matches (TRUE by default).
`chance`
*Only used by editor* | Float | Chances for this rule to be applied (0 to 1)
`checker`
*Only used by editor* | Enum | Checker mode
Possible values: `None`, `Horizontal`, `Vertical`
`flipX`
*Only used by editor* | Bool | If TRUE, allow rule to be matched by flipping its pattern horizontally
`flipY`
*Only used by editor* | Bool | If TRUE, allow rule to be matched by flipping its pattern vertically
`invalidated`
*Only used by editor*
 | Bool | If TRUE, then the rule should be re-evaluated by the editor at one point
`outOfBoundsValue`
*Only used by editor*
 | Int *(can be `null`)* | Default IntGrid value when checking cells outside of level bounds
`pattern`
*Only used by editor* | Array of Int | Rule pattern (size x size)
`perlinActive`
*Only used by editor* | Bool | If TRUE, enable Perlin filtering to only apply rule on specific random area
`perlinOctaves`
*Only used by editor* | Float |
`perlinScale`
*Only used by editor* | Float |
`perlinSeed`
*Only used by editor* | Float |
`pivotX`
Only *'Stamp' tile mode*
*Only used by editor* | Float | X pivot of a tile stamp (0-1)
`pivotY`
Only *'Stamp' tile mode*
*Only used by editor* | Float | Y pivot of a tile stamp (0-1)
`size`
*Only used by editor* | Int | Pattern width & height. Should only be 1,3,5 or 7.
`tileMode`
*Only used by editor* | Enum | Defines how tileIds array is used
Possible values: `Single`, `Stamp`
`tileRandomXMax`
*Only used by editor*
 | Int | Max random offset for X tile pos
`tileRandomXMin`
*Only used by editor*
 | Int | Min random offset for X tile pos
`tileRandomYMax`
*Only used by editor*
 | Int | Max random offset for Y tile pos
`tileRandomYMin`
*Only used by editor*
 | Int | Min random offset for Y tile pos
`tileRectsIds`
*Only used by editor* | Array of Array of Int | Array containing all the possible tile IDs rectangles (picked randomly).
`tileXOffset`
*Only used by editor*
 | Int | Tile X offset
`tileYOffset`
*Only used by editor*
 | Int | Tile Y offset
`uid`
*Only used by editor* | Int | Unique Int identifier
`xModulo`
*Only used by editor* | Int | X cell coord modulo
`xOffset`
*Only used by editor* | Int | X cell start offset
`yModulo`
*Only used by editor* | Int | Y cell coord modulo
`yOffset`
*Only used by editor* | Int | Y cell start offset
~~`tileIds`~~
*Only used by editor*
*DEPRECATED!*
 | Array of Int *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.5.0
Replaced by: `tileRectsIds`
## 3.2. Entity definition
Value | Type | Description
-- | -- | --
`color` | String
*Hex color "#rrggbb"* | Base entity color
`height` | Int | Pixel height
`identifier` | String | User defined unique identifier
`nineSliceBorders`
 | Array of Int | An array of 4 dimensions for the up/right/down/left borders (in this order) when using 9-slice mode for `tileRenderMode`.
If the tileRenderMode is not NineSlice, then this array is empty.
See: https://en.wikipedia.org/wiki/9-slice_scaling
`pivotX` | Float | Pivot X coordinate (from 0 to 1.0)
`pivotY` | Float | Pivot Y coordinate (from 0 to 1.0)
`tileRect`
 | [Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)* | An object representing a rectangle from an existing Tileset
`tileRenderMode`
 | Enum | An enum describing how the the Entity tile is rendered inside the Entity bounds.
Possible values: `Cover`, `FitInside`, `Repeat`, `Stretch`, `FullSizeCropped`, `FullSizeUncropped`, `NineSlice`
`tilesetId` | Int *(can be `null`)* | Tileset ID used for optional tile display
`uiTileRect`
 | [Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)* | This tile overrides the one defined in `tileRect` in the UI
`uid` | Int | Unique Int identifier
`width` | Int | Pixel width
`allowOutOfBounds`
*Only used by editor*
 | Bool | If enabled, this entity is allowed to stay outside of the current level bounds
`doc`
*Only used by editor*
 | String *(can be `null`)* | User defined documentation for this element to provide help/tips to level designers.
`exportToToc`
*Only used by editor*
 | Bool | If enabled, all instances of this entity will be listed in the project "Table of content" object.
`fieldDefs`
*Only used by editor* | Array of [Field definition](#ldtk-FieldDefJson) | Array of field definitions
`fillOpacity`
*Only used by editor*
 | Float |
`hollow`
*Only used by editor*
 | Bool |
`keepAspectRatio`
*Only used by editor*
 | Bool | Only applies to entities resizable on both X/Y. If TRUE, the entity instance width/height will keep the same aspect ratio as the definition.
`limitBehavior`
*Only used by editor* | Enum | Possible values: `DiscardOldOnes`, `PreventAdding`, `MoveLastOne`
`limitScope`
*Only used by editor*
 | Enum | If TRUE, the maxCount is a "per world" limit, if FALSE, it's a "per level".
Possible values: `PerLayer`, `PerLevel`, `PerWorld`
`lineOpacity`
*Only used by editor*
 | Float |
`maxCount`
*Only used by editor*
 | Int | Max instances count
`maxHeight`
*Only used by editor*
 | Int *(can be `null`)* | Max pixel height (only applies if the entity is resizable on Y)
`maxWidth`
*Only used by editor*
 | Int *(can be `null`)* | Max pixel width (only applies if the entity is resizable on X)
`minHeight`
*Only used by editor*
 | Int *(can be `null`)* | Min pixel height (only applies if the entity is resizable on Y)
`minWidth`
*Only used by editor*
 | Int *(can be `null`)* | Min pixel width (only applies if the entity is resizable on X)
`renderMode`
*Only used by editor* | Enum | Possible values: `Rectangle`, `Ellipse`, `Tile`, `Cross`
`resizableX`
*Only used by editor*
 | Bool | If TRUE, the entity instances will be resizable horizontally
`resizableY`
*Only used by editor*
 | Bool | If TRUE, the entity instances will be resizable vertically
`showName`
*Only used by editor*
 | Bool | Display entity name in editor
`tags`
*Only used by editor*
 | Array of String | An array of strings that classifies this entity
`tileOpacity`
*Only used by editor*
 | Float |
~~`tileId`~~
*DEPRECATED!*
 | Int *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.2.0
Replaced by: `tileRect`
## 3.2.1. Field definition 
This section is mostly only intended for the LDtk editor app itself. You can safely ignore it.
Value | Type | Description
-- | -- | --
`__type`
*Only used by editor* | String | Human readable value type. Possible values: `Int, Float, String, Bool, Color, ExternEnum.XXX, LocalEnum.XXX, Point, FilePath`.
If the field is an array, this field will look like `Array<...>` (eg. `Array`, `Array` etc.)
NOTE: if you enable the advanced option **Use Multilines type**, you will have "*Multilines*" instead of "*String*" when relevant.
`acceptFileTypes`
Only *FilePath*
*Only used by editor* | Array of String *(can be `null`)* | Optional list of accepted file extensions for FilePath value type. Includes the dot: `.ext`
`arrayMaxLength`
Only *Array*
*Only used by editor* | Int *(can be `null`)* | Array max length
`arrayMinLength`
Only *Array*
*Only used by editor* | Int *(can be `null`)* | Array min length
`canBeNull`
*Only used by editor* | Bool | TRUE if the value can be null. For arrays, TRUE means it can contain null values (exception: array of Points can't have null values).
`defaultOverride`
*Only used by editor* | Enum *(can be `null`)* | Default value if selected value is null or invalid.
`doc`
*Only used by editor*
 | String *(can be `null`)* | User defined documentation for this field to provide help/tips to level designers about accepted values.
`identifier`
*Only used by editor* | String | User defined unique identifier
`isArray`
*Only used by editor* | Bool | TRUE if the value is an array of multiple values
`max`
Only *Int, Float*
*Only used by editor* | Float *(can be `null`)* | Max limit for value, if applicable
`min`
Only *Int, Float*
*Only used by editor* | Float *(can be `null`)* | Min limit for value, if applicable
`regex`
Only *String*
*Only used by editor*
 | String *(can be `null`)* | Optional regular expression that needs to be matched to accept values. Expected format: `/some_reg_ex/g`, with optional "i" flag.
`type`
*Only used by editor* | String | Internal enum representing the possible field types. Possible values: F_Int, F_Float, F_String, F_Text, F_Bool, F_Color, F_Enum(...), F_Point, F_Path, F_EntityRef, F_Tile
`uid`
*Only used by editor* | Int | Unique Int identifier
`allowOutOfLevelRef`
*Only used by editor*
 | Bool |
`allowedRefTags`
*Only used by editor*
 | Array of String |
`allowedRefs`
*Only used by editor*
 | Enum | Possible values: `Any`, `OnlySame`, `OnlyTags`, `OnlySpecificEntity`
`allowedRefsEntityUid`
*Only used by editor*
 | Int *(can be `null`)* |
`autoChainRef`
*Only used by editor*
 | Bool |
`editorAlwaysShow`
*Only used by editor* | Bool |
`editorCutLongValues`
*Only used by editor*
 | Bool |
`editorDisplayColor`
*Only used by editor*
 | String *(can be `null`)* |
`editorDisplayMode`
*Only used by editor*
 | Enum | Possible values: `Hidden`, `ValueOnly`, `NameAndValue`, `EntityTile`, `LevelTile`, `Points`, `PointStar`, `PointPath`, `PointPathLoop`, `RadiusPx`, `RadiusGrid`, `ArrayCountWithLabel`, `ArrayCountNoLabel`, `RefLinkBetweenPivots`, `RefLinkBetweenCenters`
`editorDisplayPos`
*Only used by editor* | Enum | Possible values: `Above`, `Center`, `Beneath`
`editorDisplayScale`
*Only used by editor*
 | Float |
`editorLinkStyle`
*Only used by editor*
 | Enum | Possible values: `ZigZag`, `StraightArrow`, `CurvedArrow`, `ArrowsLine`, `DashedLine`
`editorShowInWorld`
*Only used by editor*
 | Bool |
`editorTextPrefix`
*Only used by editor*
 | String *(can be `null`)* |
`editorTextSuffix`
*Only used by editor*
 | String *(can be `null`)* |
`exportToToc`
*Only used by editor*
 | Bool | If TRUE, the field value will be exported to the `toc` project JSON field. Only applies to Entity fields.
`searchable`
*Only used by editor*
 | Bool | If enabled, this field will be searchable through LDtk command palette
`symmetricalRef`
*Only used by editor*
 | Bool |
`textLanguageMode`
*Only used by editor*
 | Enum *(can be `null`)* | Possible values: <`null`>, `LangPython`, `LangRuby`, `LangJS`, `LangLua`, `LangC`, `LangHaxe`, `LangMarkdown`, `LangJson`, `LangXml`, `LangLog`
`tilesetUid`
Only *Tile*
*Only used by editor*
 | Int *(can be `null`)* | UID of the tileset used for a Tile
`useForSmartColor`
*Only used by editor*
 | Bool | If TRUE, the color associated with this field will override the Entity or Level default color in the editor UI. For Enum fields, this would be the color associated to their values.
## 3.3. Tileset definition
The `Tileset` definition is the most important part among project definitions. It contains some extra informations about each integrated tileset. If you only had to parse one definition section, that would be the one.
Value | Type | Description
-- | -- | --
`__cHei`
 | Int | Grid-based height
`__cWid`
 | Int | Grid-based width
`customData`
 | Array of Object | An array of custom tile metadata
This array contains objects with the following fields:
- **`data`** **(String**)
- **`tileId`** **(Int**)
`embedAtlas`
 | Enum *(can be `null`)* | If this value is set, then it means that this atlas uses an internal LDtk atlas image instead of a loaded one.
Possible values: <`null`>, `LdtkIcons`
`enumTags`
 | Array of Object | Tileset tags using Enum values specified by `tagsSourceEnumId`. This array contains 1 element per Enum value, which contains an array of all Tile IDs that are tagged with it.
This array contains objects with the following fields:
- **`enumValueId`** **(String**)
- **`tileIds`** **(Array of Int**)
`identifier` | String | User defined unique identifier
`padding` | Int | Distance in pixels from image borders
`pxHei` | Int | Image height in pixels
`pxWid` | Int | Image width in pixels
`relPath` | String *(can be `null`)* | Path to the source file, relative to the current project JSON file
It can be null if no image was provided, or when using an embed atlas.
`spacing` | Int | Space in pixels between all tiles
`tags`
 | Array of String | An array of user-defined tags to organize the Tilesets
`tagsSourceEnumUid`
 | Int *(can be `null`)* | Optional Enum definition UID used for this tileset meta-data
`tileGridSize` | Int |
`uid` | Int | Unique Intidentifier
`cachedPixelData`
*Only used by editor*
 | Object *(can be `null`)* | The following data is used internally for various optimizations. It's always synced with source image changes.
This object contains the following fields:
- **`averageColors`** **(String *(can be `null`)***)  : *Average color codes for each tileset tile (ARGB format)*
- **`opaqueTiles`** **(String**)  : *An array of 0/1 bytes, encoded in Base64, that tells if a specific TileID is fully opaque (1) or not (0)*
`savedSelections`
*Only used by editor* | Array of Object | Array of group of tiles selections, only meant to be used in the editor
This array contains objects with the following fields:
- **`ids`** **(Array of Int**)
- **`mode`** **(Enum**)
## 3.3.1. Tileset rectangle 
This object represents a custom sub rectangle in a Tileset image.
Value | Type | Description
-- | -- | --
`h`
 | Int | Height in pixels
`tilesetUid`
 | Int | UID of the tileset
`w`
 | Int | Width in pixels
`x`
 | Int | X pixels coordinate of the top-left corner in the Tileset image
`y`
 | Int | Y pixels coordinate of the top-left corner in the Tileset image
## 3.4. Enum definition
Value | Type | Description
-- | -- | --
`externalRelPath` | String *(can be `null`)* | Relative path to the external file providing this Enum
`iconTilesetUid` | Int *(can be `null`)* | Tileset UID if provided
`identifier` | String | User defined unique identifier
`tags`
 | Array of String | An array of user-defined tags to organize the Enums
`uid` | Int | Unique Int identifier
`values` | Array of [Enum value definition](#ldtk-EnumDefValues) | All possible enum values, with their optional Tile infos.
`externalFileChecksum`
*Only used by editor* | String *(can be `null`)* |
## 3.4.1. Enum value definition
Value | Type | Description
-- | -- | --
`color`
 | Int | Optional color
`id` | String | Enum value
`tileRect`
 | [Tileset rectangle](#ldtk-TilesetRect) *(can be `null`)* | Optional tileset rectangle to represents this value
~~`tileId`~~
*DEPRECATED!*
 | Int *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.4.0
Replaced by: `tileRect`
~~`__tileSrcRect`~~
*DEPRECATED!*
  | Array of Int *(can be `null`)* | **WARNING**: this deprecated value is no longer exported since version 1.4.0
Replaced by: `tileRect`