1. Home
  2. Docs
  3. In-game implementation
  4. JSON overview

JSON overview


Project data is stored in JSON files.

An up-to-date detailed JSON file format description, directly generated from latest source code, is available on this website.

JSON evolution

The JSON format evolves as the app is updated and gains more functionalities. You can track these changes easily:

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.


Below is a simplified example of a typical empty LDtk project file:

	"__header__": { // Some header information
		"fileType": "LDtk Project JSON",
		"app": "LDtk",

	"iid": "9bba3440-7820-11ed-bc60-dd3cf5379687",
	"jsonVersion": "1.2.2",
	"worldLayout": "Gridvania",

	"defs": { // Definitions of this project elements
		"layers": [], 
		"entities": [], 
		"tilesets": [], 
		"enums": [], 
		"externalEnums": [], 
		"levelFields": [] 

	"levels": [ // Actual level data
			"identifier": "MyLevel0",
			"iid": "472e4691-66b0-11ec-aa49-8d5f985d2dae",
			"worldX": 0,
			"worldY": 0,
			"layerInstances": [],  // Layers content

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.