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.

Single or separate files ?

When saving your project, you are given 2 options:

1. Saving to a single JSON file named myProject.ldtk, which will contain everything.
2. Saving project data to a JSON file named myProject.ldtk and saving each level to a separate *.ldtkl file in a sub-folder named myProject.

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.

Optional level JSON (*.ldtkl)

This file contains exactly the same type of data as if it was in the main file. The format is identical:

• level data,
• all layers content.

A typical LDtk JSON file

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).

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.).

Information stored in root

Most of these are only used by the editor itself.

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.

Unique identifiers

Each definition has a uid field which stands for Uniquer Identifier.

Each instance of whatever also has a defUid field which simply refers to the corresponding definition with the same uid.

Making your gamedev life easier

If all you want in your game is to access the JSON data (layers content, entities etc.), going back & forth between Definitions & Instances could be a little bit cumbersome to say the least.

To make the JSON parsing much easier, all instances have some redundant fields prefixed with a double underscores (like __value). For example, here is the JSON of an Enemy entity in a level:

"entityInstances" : [
	{
		"__identifier" : "Mob",
		"__cx" : 3,
		"__cy" : 5,
		"defUid" : 2,
		"x" : 56,
		"y" : 96,
		"fieldInstances" : []
	},
	{
		...
	},
]

Here, if you want to get the actual entity name of this Instance (ie. “Mob“), you need to use the defUid value to retrieve the Entity Definition containing the info.

Luckily, you have a __identifier value which is a redundant copy of this exact info, making it easier for you to read it.

Same goes for the grid based coordinates (__cx and __cy) which normally depend on the Layer definition which contains the grid size making an overly complicated task for a simple info.

Long story short, fields prefixed with double underscores are there to make your parsing life easier.