Using GMTiled2 to load Tiled projects into GameMaker
GMTiled2 is a runtime parser for Tiled, an open-source map editor. It allows you to dynamically load your Tiled projects into your GameMaker game without having to export and import rooms or re-build the game.
Unfortunately the differences between features of Tiled, GameMaker, and the effort needed on my part to match them up is great, and as a result GMTiled2 only supports a subset of features, and requires some specific setup to work. This guide documents how to optimally set up your Tiled project and GameMaker game to make the most of GMTiled2
Step 1: In Tiled, Create a new project
Launch Tiled and create a new project.
Use the following settings:
- Orientation: orthogonal
- Tile layer format: Base64 (zlib compressed) or Base64 (uncompressed)
- Tile render order: Right Down
- Map size: Fixed (any size)
- Tile size: (any size)
Save the project somewhere on your computer, and then close Tiled; we’ll re-open it later after adding to the project.
Step 2 (optional): In GameMaker, add the TMX project
Your GameMaker game just needs to be able to access the .tmx file somehow. The easiest way to do it is to include the project in GameMaker’s project structure, but other methods are valid too (for example using an Open File dialog; or downloading it from the internet and saving it to the save directory).
This will cause the project you just saved in Step 1 to be copied into your GameMaker’s folder structure, inside the datafiles folder. This is particularly useful since now the .tmx project is part of your GameMaker project, and you can continue editing the .tmx project from this location.
Step 3: In GameMaker, add some Tile Sets
Add your sprites and create Tile Sets in your GameMaker project. Make a note of the name of the tilesets (in the below example, the name is tl_dungeon_sheet).
Step 4: In Tiled, add the same Tile Sets
Now reopen the .tmx project in the datafiles folder, add the same Tile Sets. Do this by hitting the New Tileset button, or the new icon in the sidebar
One benefit of having the tmx project inside the GameMaker project is you can have it load in the actual sprites from your GameMaker project, making it easier to maintain the same sprites across both Tiled and GameMaker. For example, in the below image, I’ve navigated to sprite/spr_dungeon_sheet/<uuid>.png to load in the same sprite into Tiled as I used to create tl_dungeon_sheet.
Use the following settings:
- Name: use the same name as the tileset resource in GM made in Step 3
- Type: Based on Tileset Image
- Embed in map: yes (always do this)
- Source: select the same image as the tileset resource in GM
- Tile width/height/margin/spacing: use the same settings as the tileset resource in GM
Step 5: In Tiled, draw your tiles!
You can add extra tilesets, and new layers, as long as you make sure it has the same name and settings as the ones you make in GM.
Step 6: In GameMaker, create the object/code that will load the tiles
In GameMaker, some code needs to be run to parse and load tiles. There are two methods to use depending on requirements:
Method 1: One-shot load
The easiest method is to just call tiled_oneshot(“your_tiled_project.tmx”). Whenever this function runs, it will load the tmx project, and create the necessary tile layers, and clean up any interim data created in the meantime.
You can put this inside a room create event; a room loader object’s create or room_start event.
The limitation of Oneshot load is there is no automatic way to unload the layers, meaning if you need to unload the room, you will need to either switch rooms, or manually cycle through the layers to remove them.
Method 2: Read/Create/Destroy
To address this limitation, the second method is to call tiles = tiled_read(“your_tiled_project.tmx”), which will parse the Tiled project and prepare a ds_map containing all the layer data. When you’re ready to show the room, simply run a tiled_create(tiles).
When you’re ready to remove all of the layers create by tiled_create, run tiled_destroy(tiles). This will attempt to remove all the layers and instances that were created, and destroy the ds_map, to free up memory.
Optionally, if you don’t need to use tiled_destroy, you can just free up the ds_map by using tiled_cleanup(tiles), which is internally just a ds_map_destroy(tiles).
Using Object Layers
It is possible to use Tiled and GMTiled2 to spawn objects into the room.
Step 1: In GameMaker, create the objects you want to be able to spawn
As with previously, make sure the assets you want to work with exist. In the below example, an obj_character has been made.
Step 2: In Tiled, create an object layer, and add objects
In Tiled, create an Object Layer, and use the draw tools to draw objects into the map.
Make sure the name field of any object you draw matches the name of an object in GameMaker, for example in the above example, I have used the “Insert Tile” tool to add three tile-objects (objects that use a tile as the graphic) to a layer called Instances, and have named them all obj_character.
This will cause three obj_character to be spawned on that layer. Note: the appearance of an object in Tiled has no bearing on the appearance when loaded in GameMaker, in the above example, I happen to use the same sprite in GameMaker as the tile I selected to use for the object. I could have used a square, or point object instead for the same effect.
Step 3 (optional): Set any custom properties of the object
Custom instance variables can be set for each object, in the bottom left corner, click the “+” button, and create a new instance variable. These will be set after the create event is run in GameMaker. Built-in variables can also be set, such as image_alpha in the above example.
The special “color” field will be translated into a GameMaker color (no alpha supported).
Technical Notes
Data storage format
The contents of the tmx file is first parsed into a ds_map by tiled_read(), you can export or save this to file using json_encode should you wish to not re-parse the file. This may be useful for including with other save data. Should you need programmatic access to data in tmx files, it is also possible to grab data out of this ds_map. The structure of the ds_map should be relatively self-explanatory for experienced programmers.
Layer depth
Each layer is created 100 depth apart, starting at 100 above (more negative) the depth of the object calling tiled_oneshot() or tiled_create().
For example, in the example project, the obj_gmtiled2 object is placed on the Instances layer in the room editor which is at depth 0 by default. The following sequence of events occurs when loading the example.tmx
- Layer Floor from the tmx is create at depth -100
- Layer Floor_clutter from the tmx is created at depth -200
- Layer Walls_lower from the tmx is created at depth -300
- Layer Instances already exists in the room, so it is moved to depth -400
- Layer Walls_upper from the tmx is created at depth -500
When running tiled_destroy(), the Instances layer, since it already existed in the room before loading, will be moved back to its original depth of 0 after all the other layers have been deleted.
