Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
gdevelop5:objects:tilemap [2020/12/04 20:15]
blurymind [Known limitations]
gdevelop5:objects:tilemap [2021/11/22 23:06] (current)
Line 1: Line 1:
-The Tilemap extension+# Tilemap object
  
-<note tip>**See it in action!** 🎮\\ +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...
-[[#Examples|I would rather see the tiled Tilemap example! Please take me there now.]] +
-</note>+
  
-The Tilemap extension can be used to load tilemaps in Gdevelop games.+For now, this object is meant for advanced users as it requires Tilemaps to be authored in an **external editor called [[https://www.mapeditor.org/|Tiled]]** 
  
-For not it can only load **[[https://www.mapeditor.org/|tiled]]** tilemap/set json files, but this may change in the future, with plans to add support for **[[https://ldtk.io/|LdTk]]** tilemaps. +<note>You can also create tilemaps using [[https://ldtk.io/|LDtk (Level Designer Toolkit)]], but it requires an extra stepExport your LDtk world into TMX format and import that TMX file into Tiled This will allow you to follow the instructions below.</note>
- {{:gdevelop5:objects:tilemaptiledgdevelop.png?nolink}}+
  
---- +{{:gdevelop5:objects:tilemap:pasted:20210104-105043.png}}
-# Known limitations+
  
-This extension uses **[[ https://github.com/pixijs/pixi-tilemap|pixi-tilemap]]**  to function and as a result inherits some of its limitations+## 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).
  
-  * If you have **animated tiles**, they will need to be arranged in the right order in 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 tile - this extension only supports uniform duration for all tiles. You can configure how fast the animation is played, but you can't go granular on a per frame basis. +## Creating new tilemap step by step
  
-{{:gdevelop5:objects:tilemapanimationlimitation.png?nolink}}+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 [[https://adamatomic.itch.io/cavernas|downloaded here]]. Save the file in your project folder.
  
-* Unfortunately **Isometric tilemaps** are not supported +Download Tiled on [[https://www.mapeditor.org/|mapeditor.org]] and launch itChoose to create **New map...**: 
-* Unfortunately **Tilemaps that use more than one tilesets** are not supportedOne tileset per tilemap only for nowThis is due to the way Gdevelop manages resourcesWe may overcome this limitation and use the relative paths that are stored in the tiled files instead in the future. +{{:gdevelop5:objects:tilemap:pasted:20210104-112522.png}}
-* 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.+
  
 +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:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-112656.png}}
 +
 +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:
 +{{:gdevelop5:objects:tilemap:pasted:20210104-112850.png}}
 +
 +Enter a name, and choose the image file (also called the "Atlas") that you saved in your project folder:
 +{{:gdevelop5:objects:tilemap:pasted:20210104-113221.png}}
 +
 +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:
 +{{:gdevelop5:objects:tilemap:pasted:20210104-114523.png}}
 +
 +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**:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-114702.png}}
 +
 +You can then click **Apply** and drag'n'drop the object on the scene if it's not there already:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-114824.png}}
 +
 +### 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:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-122010.png}}
 +
 +Create objects with placeholder images (probably just a colored rectangle), then add to them the Platform behavior: 
 +{{:gdevelop5:objects:tilemap:pasted:20210104-115630.png}}
 +
 +Hide the invisible obstacles/platforms at the start of the scene using events:
 +{{:gdevelop5:objects:tilemap:pasted:20210104-120406.png}}
 +
 +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:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-105614.png}}
 +
 +Finally, choose the tileset file in GDevelop, in addition to choosing the atlas image and the tilemap JSON file:
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-110127.png}}
 +
 +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. 
 +
 +<note warning>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. </note>
 +
 +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. 
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-112051.png}}
 +
 +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):
 +
 +{{:gdevelop5:objects:tilemap:pasted:20210104-112229.png}}
 +
 +## 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 [[https://github.com/pixijs/pixi-tilemap|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).