**This is an old revision of the document!**

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.

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

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

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.

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