LDtk: a 2D level editor you build from source, and what that costs you

Who LDtk is for, and the problem it removes

Most 2D projects start with levels stored in whatever format the engine already parses: a tilemap array, a scene file, a hand-written JSON blob. That works until a designer needs to move a room, retag a spawn point, or add an entity type, at which point every change turns into a code edit. LDtk is a level editor aimed at that gap. The README describes it as a "modern, efficient and open-source 2D level editor with a strong focus on user-friendliness", and the repository topics list 2d, game-development and level-editor alongside the implementation stack.

The audience is narrower than "anyone making a 2D game". LDtk is written in Haxe and its companion API is a Haxe library, so the natural user is a developer who is either working in Haxe already or willing to parse the editor's exported project data from another language. A designer who only wants to paint tiles and never touches a command line is a second-class user here: the README's own instructions start with installing a compiler.

Electron main, renderer, and a Haxe API on the side

LDtk is not a single binary with an internal scripting layer. The build is split into two Haxe targets. The Electron main process is compiled separately from the renderer, and each produces a distinct artifact the README names explicitly: main.debug.hxml writes app/assets/main.js, and renderer.debug.hxml writes app/assets/js/renderer.js. The UI itself is built on Heaps.io and runs in the renderer, with jQuery and MarkedJS listed among the related tools.

That split explains the alternative runtimes. The renderer can also run standalone in NW.js without the Electron main process, which is why the repository carries an app/nwjs directory and a hide-plugin.hxml build target. The Hide plugin compiles to app/nwjs/hide-plugin.js from sources in src/hide/plugin/, and once registered in a Hide project's res/props.json it opens LDtk in its own tab. The README notes one consequence of that embedding: the CastleDB enum sync reads Hide's live database, including unsaved changes.

The other half of the architecture is the data contract. Level data lives in .ldtk project files, and the ldtk-haxe-api repository is the library that reads them. The README is clear that these two move together: when you check out a dev branch, you must switch the Haxe API to the same branch.

Installing LDtk: download, or build master yourself

The README does not give an install procedure for the released application. It says to visit LDtk.io to get the latest version, and that is the only distribution channel it names. Everything below is the from-source path, which is what the repository actually documents.

Building requires two things, per the README: an up-to-date Haxe compiler and NPM, which is used for install and packaging scripts and ships with NodeJS. From the repository root, the first command installs the required Haxe libraries:

haxe setup.hxml

After that, the README is explicit that you must change into the app directory before installing the JavaScript dependencies, because the npm install is expected to run there:

cd app
npm i

Now build the two Electron halves. Run both from the repository root. The first produces app/assets/main.js:

haxe main.debug.hxml

The second produces app/assets/js/renderer.js:

haxe renderer.debug.hxml

With both artifacts in place, starting the editor is an npm script run from the app folder:

npm run start

If you would rather not involve Electron at all, the README offers a second entry point: nw app/nwjs runs the renderer in NW.js. For editor integration there is a third path, building the Hide plugin with haxe hide-plugin.hxml and registering the resulting hide-plugin.js in a Hide project's res/props.json, alongside a menu.extra entry that mounts the ldtk.LdtkView component. The ldtk.project key in that file is optional and resolves relative to res/.

Dev branches, unstable builds, and the missing upgrade path

The README's most useful warning is about version skew. To try a future version you check out a branch named dev-x.y.z, and the README states plainly that these branches "might be unstables, or even broken", recommending them only if you intend to add or fix something in LDtk itself. It adds two operational costs: haxelibs need frequent updating on those branches, and the Haxe API must be switched to the same branch, with a haxelib git command shown using a dev-0.6.0 example.

That is a real constraint, not boilerplate. A project file written by a dev build may not open in the released version, and the README documents no migration tool, no format versioning policy, and no rollback procedure. The released version numbers in the repository sit at 1.5.3, while the API branch example in the README is dev-0.6.0, which tells you the two version lines are not the same number and should not be assumed to correspond.

The second limitation is the toolchain itself. There is no packaged installer described in the repository, so anyone who wants to run a local build needs Haxe and Node installed and working. The README also does not document headless operation, a CLI for batch-editing levels, or a way to run the editor in CI. If your workflow depends on generating or validating levels without a GUI, nothing in the README suggests LDtk covers it.

Tiled and the generic tilemap pipeline

The obvious alternative is Tiled, the long-standing 2D map editor. The difference is not features so much as where the format lives. Tiled's map format is an open specification that many engines and community loaders parse directly, so a project can adopt it without writing a loader. LDtk's equivalent is the ldtk-haxe-api library maintained in a separate repository by the same author, which means the integration work sits with you unless a loader already exists for your engine.

The second difference is the runtime. LDtk is an Electron application built from Haxe and Heaps.io sources; the README also documents running the renderer under NW.js and embedding it as a Hide plugin. That gives it a scripting and plugin story tied to the Haxe ecosystem, and it is the reason the CastleDB enum sync can read a Hide project's live database. If your team is not in Haxe, that extensibility is mostly inaccessible, and a plain tilemap editor with a documented format will be less friction.

Maintenance, licensing, and what the repository does not say

The repository is not archived, and the last push was on 2026-07-12. The most recent tagged releases listed are v1.5.3 on 2024-01-15, v1.5.2 on 2024-01-12 and v1.5.1 on 2024-01-11, so tagged releases and branch activity are not moving at the same rate. Treat the release tags as the stable surface and master as a moving target.

LDtk is MIT licensed, which is permissive and imposes no copyleft obligation on your game. That covers the editor source. The README separates out the assets: tileset images are covered by a README in app/extraFiles/samples, and the default palettes are credited to third parties, "Endesga32" by Endesga and "Colorblind 16" by FilipWorks. Other bundled dependencies carry their own terms: Haxe, Heaps.io, Electron, jQuery, MarkedJS, and SVG icons from material.io. If you ship anything derived from the sample tilesets or the palettes, check those files rather than assuming the MIT header covers them. This is not legal advice; read the licences yourself.

Upgrade cost is the weak point. The README documents building master and building dev branches, and nothing about upgrading an installed copy, migrating a .ldtk file between versions, or reverting after a bad upgrade. The practical consequence is that version pinning has to happen on your side, and the ldtk-haxe-api branch you depend on has to be recorded alongside the editor version.

Editorial conclusion

Adopt LDtk if you are comfortable working from a Haxe toolchain and want a level editor whose project format and Haxe API you can read directly, and if you plan to pin a release rather than track master. Do not adopt it if you need a documented upgrade path, a rollback story, or a packaged installer you can hand to a non-programmer on the team, because the README covers building from source and nothing about migrating or reverting a project. Before committing, verify three things: that the release you download from ldtk.io is the version you intend to pin, that the ldtk-haxe-api branch you install matches your LDtk branch, and that your engine integration reads the .ldtk file format your build produces.

Frequently asked questions

Official sources

1. deepnight/ldtk on GitHub
2. License: MIT
3. Project website
4. README
5. Releases