Using LDtk with FlxTilemap

Having the right tools at your disposal can make game development a whole lot easier. Since I make a lot of platformers, one of the most important tools for me is a level editor. Recently, I finally took the plunge and tried out LDtk, a 2D level editor from the creator of Dead Cells (which you should totally play, by the way). And I have to say, this is the best level editor I’ve used so far. However, it can be a bit tricky to set it up for use in HaxeFlixel. The website has instructions on how to do it, but there is oen caveat: HaxeFlixel has the FlxTilemap class, which makes dealing with tilemaps very simple. LDtk, however, does not support this out of the box.

But I wouldn’t be writing this tutorial if there wasn’t a way to get it all to work anyway. So let’s take a look at how to do it!

A lot of this tutorial will cover things better explained on the LDtk website, but I’ll quickly gloss over them anyway to give you an idea of the full picture.

First of all, an important hint: Make sure that you install the LDtk Haxe API _including its dependencies as outlined here.

Step 1: Make a Level

The first step is to fire up LDtk and to make a level. I won’t go into detail here, because the website has a good set of instructions already. Just throw together a map using an IntGrid layer and a Tile layer (which you can auto-generate from the IntGrid layer). Then save the project in the assets folder of your HaxeFlixel project. Yep, just plop the whole .ldtk project file in there. It’ll be fine.

Step 2: Import the level

The next step might seem a bit weird, but bear with me. In your HaxeFlixel project, create a new .hx file with just the following content:

private typedef _Tmp = haxe.macro.MacroType<[ldtk.Project.build("path/to/project.ldtk")]>;

Don’t add anything else, no class definition or nothing. Do, however, put in the correct path to your LDtk file. The name of this .hx file does not matter, but it will be used as a class name, so it’s best to use something descriptive like LdtkProject.hx or something along those lines. I usually put the file in my source folder.

This line will call a build macro that parses the LDtk project file and constructs types and classes that we can then easily use in the game. So let’s use them right now!

Go to your PlayState and add the following line in create():

var project = new LdtkProject();

This will use the data from the macro to create a new LDtk project file in the game, containing information and data on all the levels you’ve created! Note that we’re creating an instance of the LdtkProject class. This class name is based on the name you gave your .hx file. So, if you named the file MyLdtkLevel.hx, you’d call var project = new MyLdtkLevel() instead.

Alright, with that you’ve imported the LDtk project with everything you’ll need. Thanks to the magic of macros, you’ll now be able to access the various levels, layers etc. as outlined on the LDtk website. One of the samples also shows you how to render your layers, which looks something like this:

var container = new flixel.group.FlxSpriteGroup();
add(container);
level.l_Main.render( container );

So it’s actually easy to get your level on screen once you know how!

But, as I’ve mentioned at the beginning, there is a caveat. We can easily render our levels, access entities and so on. But if we want to use FlxTilemap to handle collisions and so on, we’ll have to find another way.

Let me show you another way.

Step 3: Make a FlxTilemap

Okay, so: The classic way to create a FlxTilemap is by using the loadMapFromCSV function. This function parses a string containing all your tile-data in csv-format to create collision data, draw tiles to the screen, and so on.

But all we have is a LDtk project file. How do we get our hands on the csv data we need?

It’s very simple actually!

First of all, we need to grab the level from our project file that we want the data for. This might look something like this:

var project = new LdtkProject();
var level = project.getLevel("Level_0");

The name of your level of course depends on what you entered in LDtk itself.

This new level object is chock-full of data and information, and among them is the csv-data we need. You can access it like this:

var csv = level.l_IntGrid.json.intGridCsv;

Note that l_IntGrid is the name of your IntGrid-layer in LDtk, so if you called it something else, you’ll have to of course use that name.

And that’s the whole secret, really! Now you can simply pass csv into loadMapFromCSV to create a FlxTilemap object, which you can then use for easy collision checking using FlxG.overlap and whatnot.

Note that when calling loadMapFromCSV you will have to pass in a graphic with tiles. I just pass in an image with basic one-colored tiles, since I hide my FlxTilemap anyway (I render my levels using the render method outlined above). However, with a bit of finagling, you can probably also just pass in the actual tileset and just render your level that way.

If you have any questions, comments or criticism, post them in the comments below or reach out to me on Twitter @ohsat_games!