Introduction
Project data is stored in JSON files (see Wikipedia to learn more about JSON format).
An up-to-date detailed JSON file format description, directly generated from latest source code, is available on this website.
Project JSON (*.ldtk)
This JSON file contains:
- project settings,
- all definitions,
- depending on the “Separate level files” option:
- if Separation is disabled: all level data, including layer content.
- if Separation is enabled: all level data, except layer content.
Example
Below is an example of a completely new & empty LDtk project file:
{
"__header__" : { // Some information header
"fileType": "LDtk Project JSON",
"app": "LDtk",
"appAuthor": "Sebastien Benard",
"appVersion": "0.6.3",
"url": "..."
},
// Global project settings
"name" : "My empty project",
"jsonVersion" : 1,
"defaultPivotX" : 0.0,
"defaultPivotY" : 0.0,
"defaultGridSize" : 16,
"bgColor" : "#7F8093",
"nextUid" : 1,
"defs" : { // These are elements definitions
"layers" : [],
"entities" : [],
"tilesets" : [],
"enums" : [],
"externalEnums" : []
},
"levels" : [ // Actual level data
{
"identifier" : "Level",
"uid" : 0,
"pxWid" : 256,
"pxHei" : 256,
"layerInstances" : [] // "null" if levels are separated
}
]
}
Format overview
The file is mainly divided between 4 major blocks, but 2 are really important: definitions (defs
) and level data (levels
).

JSON root
Information stored in root
Most of these are only used by the editor itself.
File identification: __header
You probably don’t need this part as it only contains some information to identify the file itself (app, origin, human readable description etc.).
Definitions: defs
“Definitions” contain all the details and settings of each component in the project:
- layers,
- entities and their fields,
- tilesets,
- enums.
All level instances: levels
Level data contain the actual instances of each levels and their layers content, entities instances etc.