T4 Modules Howto Guide/Developing a static map using the Tiled plugin
A T-Engine map is composed of square grids/tiles. Each grid has multiple content slots where the T-Engine entities are stored. Those slots include TERRAIN, TRAP, OBJECT, and ACTOR entities and the files they map to are defined in T4_Modules_Howto_Guide/Zones. T-Engine supports static and dynamic maps. Most maps in ToME are dynamic as they are created by algorithms (also called generators) which produce different maps each time they run. T-Engine also supports static maps, which are created by hand instead of algorithms. One use for static maps in ToME is to define the various vaults that can be encountered.
Contents
Static maps as code
Maps can be created by hand in Lua code. Even if you choose to use a tool like Tiled, understanding how this works will help you determine if the output of your tool is correct.
Maps defined as Lua code are start by assigning each grid an ASCII character char via the defineTile function. Content slots can be defined if applicable.
defineTile = function(char, grid, obj, actor, trap, status, spot)
After all grids have been given a value, the map is returned as a multi-line string containing the characters for each tile. Each line is a row, each character is a column. The return string is processed by the map generator to render to the screen. Here is a simple example ripped from the game file shadow-crypt-last.lua
-- License omitted for brevity
defineTile('<', "UP")
defineTile("#", "OLD_WALL")
defineTile(".", "FLOOR")
defineTile("@", "FLOOR", nil, "CULTIST_RAK_SHOR")
startx = 7
starty = 13
-- ASCII map section
return [[
###############
##...........##
#.............#
#..##.....##..#
#..##.....##..#
#.............#
#......@......#
#.............#
#.............#
#.............#
#..##.....##..#
#..##.....##..#
#.............#
##...........##
###############]]
(Fact check required) Note that starty and startx define where the player spawns within the map. Also note that dynamic maps are created in a similar fashion, except the algorithm chooses where to place the tiles for us.
Create a tilemap
The first thing you need to start making maps is a tilemap (also called an atlas). A tilemap is an image made up of a collection of smaller images. In this case, your tilemap will contain 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 images you want to use into a single directory and the run this command:
montage -border 0 -geometry 32x32 *png tilemap.png
Montage does the following:
- Specify size of each image as 32x32
- Stitches together all images ending with PNG extensions
- Does not add a border to separate them
- Creates a file named "tilemap.png"
Tiled editor
To help design static maps 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.
Tutorial
The following tutorial will show how to create a simple map used Tiled.
Create a terrain tileset
Launch the Tiled program and go to Map -> New Tileset. Name it whatever you want and select a tilemap image (see "Creating a tilemap"). 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 map
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.
Go back to T4 Modules Howto Guide
