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

The Tilemap extension

The Tilemap extension can be used to load tilemaps in Gdevelop games.

For now it can only load Tiled tilemap/set json files, but this may change in the future, with plans to add support for LdTk tilemaps.


Known limitations

This extension uses pixi-tilemap to function and as a result inherits some of its limitations. For some features that you may desire, it might be worth considering if they need to be added to pixi-tilemap or to Gdevelop. Since both are open source projects, if that itch is strong - feel free to do a PR to both of them. Same applies for bug reports. Try to identify if the bug comes from Gdevelop or pixi-tilemap before you open a ticket.

  • 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 - this extension 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.

  • Unfortunately Isometric tilemaps are not supported
  • Unfortunately Tilemaps that use more than one tilesets are not supported. One tileset per tilemap only for now. This is due to the way Gdevelop manages resources. We may overcome this limitation and use the relative paths that are stored in the tiled files instead in the future.
  • Unfortunately collisions from tiled files are not supporter - you will need to manually create them as sepparate objects in Gdevelop for now
  • Unfortunately Gdevelop can not load XML files, so only the JSON format is supported. You will have to use that when you save your files in tiled
  • You can not change an atlas image during runtime - this is due to the way Gdevelop manages image resources. You can however swap out the tilemap json file during runtime - this allows for quick switching of tilemaps without leaving the scene.
  • If you for whatever reason decide to resize your atlas after you have set it in tiled, Gdevelop will refuse to render it, because its texture size and the one that is set in the tiled file are different.

Bundled tilesets vs external tilesets

Tiled allows the user to pack the tileset data in the tilemap.json file. This is OK and Gdevelop will detect that there is tileset data in the tilemap.json file and load it. if your intention is to have different maps share a tileset, it is recommended to save the tileset data as a separate and external 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.

in summary:

  • If you provide a tileset.json resource to the extension and at the same time another tileset is bundled in your tilemap.json file, the external tileset.json file will be favoured by the extension and the bundled tileset will be ignored.
  • If you do not provide a tileset.json resource, the extension will look for a tileset inside tilemap.json and load it if present.