Tilemap object

The Tilemap object can be used to display tile-based objects. It's a good way to create maps for RPG, strategy games or create objects by assembling tiles, useful for platformer, retro-looking games, etc…

For now, this object is meant for advanced users as it requires Tilemaps to be authored in an external editor called Tiled.

You can also create tilemaps using LDtk (Level Designer Toolkit), but it requires an extra step: Export your LDtk world into TMX format and import that TMX file into Tiled. This will allow you to follow the instructions below.

Known limitations

  • Only orthogonal tilemaps are supported - isometric tilemaps are not for now.
  • Tilemaps that use more than one tilesets are not supported. One tileset per tilemap is supported for now.
  • Unfortunately collisions from tiled files are not supported - you will need to manually create them as separate invisible objects in GDevelop for now.
  • Maps and tilesets must be saved as JSON files (.json) with Tiled.
  • Don't resize your atlas (image file) after you've started making a tilemap in Tiled: GDevelop won't render it, because its texture size and the one that is set in the Tiled file are different. If you need to resize your tileset, create a new map in Tiled (where you can copy your existing map).

Creating a new tilemap step by step

Start by finding or creating your tileset and save it in a PNG file. For this example, we'll use the Cavernas public domain tileset that can be downloaded here. Save the file in your project folder.

Download Tiled on mapeditor.org and launch it. Choose to create a New map…:

Choose CSV, Base 64 or Base 64 (zlib compressed) for the tile layer format (Zstandard compressed is not supported). Choose the size of the tilemap and the size of the tiles:

Choose a file where to save the map, as a JSON file. It's recommended that you save the JSON file in your project folder.

In Tiled, choose then to create a new tileset:

Enter a name, and choose the image file (also called the “Atlas”) that you saved in your project folder:

You can choose Embed in map so that the tileset data is stored inside the Tilemap JSON file. If you don't, you'll be asked where to save the Tileset JSON file, and you'll need to select this file in GDevelop too when setting up the tilemap. See the section “Choosing between a bundled or external tileset”.

Draw your map in Tiled:

Finally, to display the map in GDevelop, choose to create a new Tilemap object. Then configure it by choosing your Atlas image (the image containing the tiles) and the Tilemap JSON file:

You can then click Apply and drag'n'drop the object on the scene if it's not there already:

Handling collisions

Collision tiles set in Tiled are for now not supported by GDevelop. Instead, you can create objects that will act as invisible obstacle or platforms. Here is an example when using the platformer behavior:

Create objects with placeholder images (probably just a colored rectangle), then add to them the Platform behavior:

Hide the invisible obstacles/platforms at the start of the scene using events:

You can also put these objects on a separate layer in GDevelop and hide the layer.

Choosing between a bundled or external tileset

Tiled allows to embed the tileset data in the Tilemap JSON file. This is done by default when Embed in map is checked when creating a new tileset in Tiled, when editing a map. This is well supported by GDevelop, which will detect that there is a tileset in the Tilemap JSON file and load it.

If your intention is to have different maps share a tileset, it is recommended to instead save the tileset as a separate tileset JSON file. That will give you a small optimization, as the tileset is now being parsed only once by GDevelop. It is also more manageable for big projects.

To do so, uncheck “Embed in map” when creating a tileset in Tiled. Choose then Save As… and select the file where to store the tileset:

Finally, choose the tileset file in GDevelop, in addition to choosing the atlas image and the tilemap JSON file:

Internally, GDevelop will work as follow:

  • If you set a tileset JSON file in the object, this tileset will be used. Note that if at the same time, another tileset is bundled in your Tilemap JSON file, the external tileset JSON file will still be used by the object: the bundled tileset will be ignored.
  • If you do not provide a tileset JSON file, the object will look for a tileset inside the Tilemap JSON and load it if present.

Using animated tiles

If you have animated tiles, they will need to be arranged in the right order in a single row on the atlas to work.

Tiled will let you put tile frames from any places of the atlas and repeat some frames - but the GDevelop object will not be able to properly interpret the animation if you do that.

Tiled also lets you put a different duration for each frame - this extension only supports uniform duration for all frames. You can configure how fast the animation is played, but you can't go granular on a per frame basis.

In GDevelop, you can choose the speed of the animation(s) of the Tilemap, which is by default 4 FPS (4 images per second, which means 1000/4 = 250ms between each image):

Future development

This object is still experimental and will be improved in the future:

  • A basic editor might be developed inside GDevelop to allow creating and editing maps directly in the scene editor.
  • Support for collisions could be added.
  • Isometric tiles support could be added.

Technical note: this extension uses pixi-tilemap. Since this project is open-source, feel free to contribute back to it or to GDevelop to improve the object (or report a bug).