Torque 2D – Tile-Editor (Temp Doco)

Like all the demos/editors, go into “prefs.cs” and change the resolution to what you desire. We'll be adding a screen to do this shortly but 800x600 is not that good to work with although everything should work fine at that resolution so checking that would be cool.

Before I waffle about the tile-editor, you may want to ignore my post and go straight into it. In that case, I'd definately recommend going to "Help > Shortcut Keys..." to see what controls/shortcuts are available.

Upon launching the tile-editor, you will be presented with a default tile-map. These defaults can be changed in "prefs.cs" for tile-counts, tile-sizes and tile-layers amongst others. There are two windows you'll see; each one with a GG logo in the background.

The Image-Library window is where you can select from any of the currently active imageMaps/animations. Note that the definitions here are from the base T2D mod. If you replace the base with your own mod then you'll see your stuff here. Click on the drop-down box and select the imagery you're interested in. You can resize/move the window to where you need. Before I describe how to use this further, it's important to know how the brushes work.

On the "Brush" menu, you’ll see a list of 20 brushes, all of which you can customise. A brush can be a single tile or a large area of tiles, each tile with its own specific settings such as collision-poly, static/animated images, flipping, custom-data etc. By default there are 20 brushes but you can easily change this preference. Brushes 1-9 can be selected by hitting the keys 1-9.

The Image-Library allows you to select a single-tile brush which you can paint onto the tile-layer. To select a tile image and replace the current brush, simply click on a tile in the image-library. Note that the tile-editor is not bothered whether the tile is animated or not. If the brush is undefined then the editor will define a single-tile brush. If the brush is defined then it will confirm that you want to replace it. Note that you can turn-off this confirmation on the "brush" menu.

To draw with the current brush onto the tile-layer simply click the left-mouse on the layer. Note that there is an info-bar at the bottom of the screen that shows current brush plus (width/height), tile-position the mouse is over as well as tile-layer size and current tile-layer and total layer count.

There are other ways to draw with the current brush as well. Just drag with the left mouse and you will literally paint the tiles. If you hold the shift-key down and drag with the left-mouse, you will be shown a drag area and when you release, it will paint the current brush into the tiles under the area you specified. Note that this also works for area brushes.

To clear a tile, you can also simply click but with the right-mouse button. You can also use the shift-key and right-drag the mouse to clear an area. Note that erasing uses the brush definition to clear so if you've got a complex area brush, it will erase only the tiles defined in the brush. Essentially, area brushes can contain empty tiles so your tile-brushes can have transparency!

Right, you've made a mistake and you want to correct it. No problem, goto the "Edit" menu and hit "Undo". This will only undo the very last change but does correct full brush drag draw/erase operations. It also covers layer erases but doesn't undo tile-layer additions, removals or resizes. If you undo something you didn’t want to then you can hit “Redo”. You can use this to switch between prior to the editor and after the edit.

Okay, so you're bored with painting single tiles so you now need to define cool brushes. Paint some tiles onto the current tile layer, something really nice and leave some clear tiles as well. Don't worry about selecting a brush at this point, just go ahead and hold the alt-key down and left-drag the mouse over an area and release the mouse-key. When you do this, the editor will ask you which brush you want to assign the area to and it will also allow you to rename the brush to whatever you want. When you click save, you'll find that new brush selected in the "brush" menu. Go ahead and paint with it at a specific-tile or an area with the shift-key. Also, you'll notice that the empty tiles, when you defined the brush, are nice holes in the brush and don't touch the layer when painting. Also, you can use the right-mouse button (and shift for an area) to erase using the brush definition. Neat.

Other stuff on the brush menu is the ability to load and save your brushes. When you save the brushes, they contain all the information you need to paint with them at a later date. It does assume only one thing, that your imagemaps/animations are available. If not, then that specific part of the brush will not paint, that’s all. Using this, you can setup brush palettes for stuff like buildings, complex animations etc. Note that you can also simply reset the brushes and there's also an option to stop the brushes from overwriting the existing collision information in the tile-layer. Note that when you draw with a brush, and subsequently change a brush, it doesn’t subsequently affect the contents of the tile-layer.

Right, before we do anything else, I'll just explain a little about how to get around your tile-layer. Because the tile-editor is written using T2D, it inherits all the nice camera facilities it's got. Use the cursor keys to pan around the layer. Use the "[" and "]" keys to zoom in/out. If you get lost then hit the "Home" key and it will move to the top-left of your map quickly. The "View" menu allows you to get to some presets such as x2 zoom, home etc. You can also select "Adjust..." which allows you to specify the window width/height as well as the zoom. Note that the changes here are persistant between sessions. Hit "reset" on this screen to return to the defaults. Another nice feature is the ability to center the view on a specific tile. Use "ctrl" + right-mouse button to do this.

The "View" menu also has other important options. I'm about to explain how to add extra layers but before I do, these options will be invaluable. "All Layers", suprisingly tells the editor to show all the layers. Note that you can continue to edit the current layer (indicated on the bottom info-bar). The second option "Up to Current Layer" is perhaps more useful. As you've probably guess, it shows all the layers prior plus the current layer. It's extemely important to note that the tile-editor is assuming that your first layer will be at the back, progressively moving forward but T2D doesn't inhibit you to do something different, you can change this when you load-up your map in T2D. Remember that T2D tile-layers are standard objects that can be placed on different layers. Typically, if you use a tile-map saved from the editor, they'll load in the correct order (assuming you've not changed the default in the t2dSceneGraph). The final option here is "Tile-Info". This draws a boundary to the tile-layer as well as showing the collision-polygons per-tile. Note that the tile-layer size is permanently the tile-count * tile-size and you must change this in T2D if you wish to have it smaller and pan the tile-layer contents.

The "Layers" menu allows you to Add, Remove and Clear a Layer. Nothing much more to add to that really apart from the fact that there's current no method to reorder your layers so if you want to change a layer then simply clear it and resize/redraw it rather than deleting it. Two nice options on the "Layers" menu are "Resize Layer..." and "Resize Tiles...", these allow you to change the tile-count and tile-sizes as you wish. As is standard with T2D, it makes no assumptions that the tile-layers all need to be the same size. If you want one layer to be twice the number of tiles but half the size or even ten-times the size, you can, no problem.

Okay, let's assume you've just added a layer or two. if you look at the right of the info-bar, you'll see the current layer. The current layers’ tile-count/size is indicated by the blue-grid. This grid is aligned with the current layers tiles. To switch between layers, use the Page-Up/Down keys. If your layers have different sizes, you'll notice that the blue tile-guide changes as well.

By default, as you flick between layers, only the layers’ tiles show. As mentioned previous, use the "A" key to select to show ALL tiles or "C" to show up to current layer.

Okay, so you now want to start putting in tiles you can collide with so here's how you do it. Goto the "Image Library" window and select the little red cross in the top-left of the window, it should change to a green-cross. Now select a nice tile, a pretty tile, a sexy tile. When you click the tile, as explained earlier, you've defined a boring single-tile brush but this time, you've told it that it is a collision tile. Assuming you've got "Tile-Info" on (see above), when you now draw a tile, you'll see a green square around the tile. Green squares indicate the collision-polygon (this can be specified in T2D scripts using "setDebugOn(BIT(5))". The default completely covers the tile but this can easily be changed! As a note, here's an example of the "Suppress Collision Draw" in the "Brush" menu. If you turn this off, you'll draw the current brush but it'll ignore the collision-flag options in your brush (it doesn’t remove them).

Okay, this is all great but you want some find-grained control over the individual options of the tiles! No problem. Move to a tile which you've drawn to and use "ctrl" left-mouse. When you do this, you’ll be presented with the “edit-tile” dialog. Here, you can specify lots of information about the tile. For clarification of some of these options, see the T2D reference guide. Starting from the top; "Script" is the info that will be passed to the layer-callback when the tile is shown on screen e.g. Tile-Script. "Custom Data" is identical to the "Script" option but would typically be used to provide type information regarding the tile, probably due to a collision. Below this is a drop-down box that’s linked to the “Custom Data” option. This box is filled with all custom-data entries for all tiles in the current layer (unique entries). This can be extremely handy if you're using custom-data as a tile-type like "water", "beach", "mountain", "building", "lava" etc. So as to be consistent, you can select from existing entries from the current tile-layer only. Maybe this should be from all tile-layers in the map?

Below this are the "FlipX" and "FlipY" options. These will flip the tile-image only. It does not flip the collision polygon although this may change if it is necessary?

Below this is "Collision Active". This simply turns the collision-active flag on or off. Note that if you turn the collision off for a tile, its other collision details stay intact so it's possible to, on-the-fly, enable/disable tile collisions without the need to redefine the collision-polygon details. Useful for doorways or other dynamic tile entries.

Below this is the rest of the tile-collision details. "Collision Polygon Scale" does exactly what it says on the tin. "Collision Polygon Count" specifies how many edges there are to the polygon defined in the box below which is "Collision Polygon Definition". This is a list of the vertices for the polygon. The polygon must match the edge-count specified above (x2 edge count entries) and must be convex. This is a pretty brute method of defining polygons and we're working on an editor to make this process much easier but in the meantime, I added a simple method to make it as easy as it can be for the moment. Below the polygon definition, you'll see a drop-down box. In here are some predefined polygons for you to select. Note that I'll be adding some others in here but you can easily add your own as the editor-script is supplied. I'll provide details if necessary to those who want to do so. Any suggestions on prefab collision-shapes here would be most welcome.

Okay, hit save and the tile will be updated.

Finally, the "File" menu allows you to load/save whole maps as well as load/save individual tile-layers. You can also append a tile-layer.


Future work
So, the idea here is that you compose your buildings/complex polygon tiles and then define area brushes to paste onto the tile-layer. I was thinking that some immediate improvements would be to allow the editing of brushes or perhaps a preferable method would be to provide a scratch-pad window that you can compose/edit your brushes which would save you from doing this process in the corner of the map somewhere. As is usual, any suggestions will be most welcomed.

As a final note, don't forget that both the current editors will be available from a key-press rather than the command-line so please ignore that fact for now.

Hopefully, I've convered most stuff in the editor and you'll find it very useful.

All the best,

- Melv.
15th February 2005