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.