JSON_DOC.md

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	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	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) : IID information of this instance widPx (Int) worldX (Int) worldY (Int) instances (Array of Reference to an Entity instance) : 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	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: #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	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 (north, south, west, east). 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	An array containing this level custom field values.
identifier	String	User defined unique identifier
iid	String	Unique instance identifier
layerInstances	Array of Layer instance (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	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
gridTiles Only Tile layers	Array of Tile instance
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 (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	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 (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 object. - For Tile, the value is a TilesetRect object. - For EntityRef, the value is an 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	All entities definitions, including their custom fields
enums	Array of Enum definition	All internal enums
externalEnums	Array of Enum definition	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	All layer definitions
levelFields	Array of Field definition	All custom fields available to all levels.
tilesets	Array of Tileset definition	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 (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 (can be null)) isOptional (Bool) name (String) requiredBiomeValues (Array of String) rules (Array of Auto-layer rule definition) 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 (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 (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	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<Int>, Array<Point> 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	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 (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