Developing a static map using the Tiled plugin
A T-Engine map is composed of square grids and each of these grids has several content slots where the actual T-Engine entities are stored. You will be dealing with the TERRAIN, TRAP, OBJECT and ACTOR slots. Most maps in ToME are generated according to an algorithm (called a generator) which leads to a different map each time. T-Engine also supports static maps that you can prepare beforehand and to help designing this type of map a T-Engine plugin has been developed for the Tiled map editor. The T-Engine plugin will convert Tiled maps into the Lua format that T-Engine expects, or alternatively you can directly create the Lua maps. The Lua maps are constructed by first assigning an ASCII character char values for each of the content slots:
defineTile = function(char, grid, obj, actor, trap, status, spot)
Then you return an ASCII map that will be interpreted by the map generator according to the tiles defined with the defineTile function. Understanding this will help you determine if the Tiled map is being exported properly to the Lua file.
ToME Vault Tutorial
One use for static maps in ToME is to define the various vaults that can be encountered, and we will use this as a tutorial for learning how to use Tiled. You can grab the prepared files (**coming soon**). You can skip down to **Create a Terrain layer and paint** section if you are just developing vaults, but if you are developing a map for your own module you will need to look at these two sections.
Create a tilemap image
The first thing you need to get started is a tilemap. The tilemap is a single image that is a collection of the individual images for each terrain that you want to add to the map. Since T-Engine uses individual 32x32 pixel images you will need to create this, and the fastest way is to use the ImageMagick montage command. First copy all of the individual images you want to use into a single directory and the run this command:
montage -border 0 -geometry 32x32 *png tilemap.png
Create a Tiled terrain tileset
Launch the Tiled program and go to Map -> New Tileset. Name it whatever you want and select the tilemap image you just created. Make sure the tile width/height (32) and margin/spacing (0) are set up correctly. The tileset should now appear in the bottom right of the Tiled window. Now we need to assign an ASCII character and value to each tile. You need to right-click on each tile and select Tile Properties. Click on <new property> and enter display. Then click in the value space next to your new display property and enter any ASCII character you would like to be associated with this tile, eg. T for tree. Now add another property called value and a corresponding value, eg. "TREE". Note the inclusion of quotation marks since these properties will be exported directly to the Lua code and you want the Lua code to recognize this value as a string. Keep doing this until you have a complete terrain tileset. You can then right-click on the tileset and export it so you can re-use it in other maps.
Create a new Tiled map (and load the Tileset)
You can either create a new 10x10 map of 32x32 tiles. Now go to Map -> Add External Tileset and select vault.tsx In this tutorial we are going to be making a bandit-themed vault, and the final results can be seen in vault-tutorial.tmx.
Create a Terrain layer and paint
Tiled maps start with a default Tile Layer called Tile Layer 1. We will use this layer to "paint" the terrain content slot for the T-Engine map. In order for the T-Engine plugin to recognize we want to use this layer for the terrain content slot we need to have the layer name start with Terrain (case-insensitive). You can rename the layer by double-clicking on the current name. Now you can select a tile from the tileset and start painting on the map. Test what you have done so far by exporting the map with the T-Engine plugin (File -> Export as and select T-Engine4 map files in the format pull down). Open up the created Lua file and see if it makes sense. The tiles marked with a "V" are vault walls, so surround the exterior of the map with those.
Create an Actor object layer
Tiled has two different types of layers: Tiles and Objects. In the previous section we saw the Tile Layer, where we painted the terrain using the various tiles from our tileset. We could theoretically do the same thing for Actors, but creating a tileset for all of the actors (monsters) in ToME doesn't strike me as a lot of fun and thus we will use Object Layers for this work. Right-click in the layers window and select Add Object Layer. In order to link this layer to the Actor content slot we (you guessed it) rename the new layer to start with Actor. Instead of selecting a tile and painting it onto the map we now create free-sized rectangles on the map. Practice drawing, resizing and deleting the objects. Now we need to set the display and value properties of each object we put down, so place an object and open the property editor. Let us make this one our bandit lord. Put l in for display and {random_filter={name="bandit lord", add_levels=15}} in for value. Note that the value does not have quotation marks this time, and is actually a Lua table! When this table gets passed to the static map generator the generator will try to create a random actor that matches the name provided and then add an additional 15 levels (vaults are supposed to be difficult). The full syntax of what can be passed in this table is outside the scope of this article. Now each tile that the bandit lord object overlaps will attempt to place a matching actor there, so make sure your bandit lord object is fully contained within a single tile. You can add another object that tries to place assassins and make it larger than one tile, though.
Use Layer Properties as defaults
For a small vault creating and editing the properties for each individual actor is ok, but this can get really tedious when adding a lot of similar actors to the map. Well layers can have properties just like objects and tiles, and the T-Engine plugin will look at the layer's properties if it does not find display or value in the tile/object. To see this in action let us create a new Object Layer and call it Actor - Generic Bandit. Now right-click on the object layer and select Layer Properties. Add a display and value layer property and add some object to the new layer. Export the map and check that the actor content from your new layer is handled correctly.