TileMaster 2D Map Editor 0.2 documentation

TileMaster 2D Map Editor 0.3

by Andy Partington (a.partington@yaroze41.freeserve.co.uk)

Introduction

Like the title says, TileMaster is a utility to help design level maps for 2D games. For those of us who have tried knocking their own games together, you know how tedious typing out your map data by hand is. This map editor lets you see what the level map will look like before you use it in your game, and lets you design levels far easier than the old graph paper and patience method!
Because TileMaster is written in Java, it will run on any machine which can handle the Java environment. It'll come in handy when deciding to move over to more stable operating systems ;)
Major changes since the last version (prototype):

Removed tile size restrictions - now your tiles can have almost any width and height (except zero).

Removed GsSPRITE and GsMAP format options - This kind of thing is probably best left to your game engine.

Added filename filtering when loading graphics - now you can only see the supported graphics formats.

Added double buffering to the canvas in the main window - you can now hide the window and it'll repaint correctly when redisplayed.

Fixed hideously slow map data loading.

Resizing the map is no longer destructive.

Major changes since 0.2

Got rid of double buffering (technically speaking) in favour of a much faster way of redrawing the screen after it has been hidden - now usable on low spec machines again (Cheers Pal!)

Implemented user-definable map data format - you're no longer restricted to C :) You can also save the formats you create for use later on.

You can now specify an offset to add to each data item - just in case you don't want your data starting from 0.

The right mouse button can now be used to delete blocks! The wonders of modern technology ;)

Current version: 0.3

What you will need

The Java Development Kit (JDK) or Java Runtime Environment (JRE). If you do not have this already you can download it from http://www.java.sun.com. Java 1.1.6 or Java 2 (1.2.2/1.3) recommended.
A pretty fast Java-capable host (faster the better).
(Probably) some kind of graphics converter - the Java 1.1 AWT only supports .GIF and .JPEG images...

To run the program, type java MapEditor (or jre MapEditor if you're using the runtime environment) and press return. Assuming you've installed Java correctly, with the correct classpath, then the program will start running. Java is case-sensitive, so type it just like it is above.

Using the Map Editor

1: The Main Window

This is the main editing area for the map. It is also the window which allows you to control the various functions of the map editor.
Menu funtions

File -> Load -> Tile Graphics
This option lets you load in your graphics that make up the building blocks of your map. They should be arranged in a similar way to the file default.gif.
NOTE! The tiles can be any size you like, not just 16*16 as in the above example. However, avoid pictures that contain other stuff than what you want to use as your map blocks (unless your game code supports it!), because the map editor will work out things wrongly, and your map will look proper bent when you come to use it in your game. Just crop an area which holds the exact area of your blocks, and save it out as a .GIF or .JPEG file.

File -> Load -> Level Map
Lets you load a level map that you have been working on. Make sure that the tiles that you used for drawing the map are loaded beforehand, or else your map will be displayed rather strangely indeed! On the other hand, this is good for when you want to try out different tile sets using the same map data!
This option won't work with exported C data, so don't even try it!!

File -> Export map data
This option saves the data out as a text file that you can include in your source code.
TileMaster works by outputting a list of numbers corresponding to an entire row of blocks (from left to right) on the map screen. Each new row is output on a seperate line (so, pretty much how it looks on screen) It is up to you to provide the correct structure to surround this data for your chosen language! Please see the section about Map->Define map format for more information.
NOTE!! If you do not define your own output data format, then TileMaster will revert to its default setting, which is to generate a 2D array using C syntax. 0xffff represents a blank block, while numbers 0-0xfffe represents each map block. This format should be general enough to be used with other routines besides what the Net Yaroze BG handler expects, with a bit of persuasion.

File -> Save map
Lets you get some shut-eye on those late-night games designing seshes!!
Well, you might be able to use this data in your programs too! The first 32 bytes of the file are taken up by two short values (16-bit Java format). These are the number of blocks across and the number of blocks down. The rest of the data is also in short format. Again, you could probably batter this map data format into something your routines can use.
NOTE: The file sizes of the map format are a bit sinister - they don't seem to correspond to what they should do. e.g. if you have a map size of 20*16, the data should be 640 bytes, plus 4 bytes for the header = 644 bytes. Instead, it ends up slightly larger than it should be (653 bytes). Other sizes are similarly too large. So whether or not there is some crap being written in there or not, I dunno, so if you want to play it safe, just export the map as a C file.

File -> Exit
Shuts down the program and quits the scene!

Map -> Resize map
To resize the map, choose this option. Enter the number of blocks horizontally and vertically, click OK and the Main Window will be resized accordingly.
WARNING!! If you want to make the map smaller than the current size, you may lose part of the map data. In this instance, as much data as possible is preserved, starting from the top left hand corner of the map.

Map -> Set tile size
To use bigger or smaller tiles to build up the map, select this option. A dialogue box will appear asking you for the width and height of a tile. This only affects the area that gets chosen inside the tile window; the actual tiles themselves are not affected.
NOTE (GsBG users only): Yaroze GsBG format map data only allows 16*16 tiles (the default setting). This is something to keep in mind when building your maps. Say if you use 8*8 tiles to build a GsBG map, it may look fine in TileMaster, but will be displayed very differently when you come to use it!
WARNING!! Don't mix tiles of different sizes on the same map! It isn't supported (and may never be!)

Map -> Create new map
Hmm, that's a tricky one... ;)

Map -> Define map format
This option will let you specify your own map format structure (as far as possible), as well as load existing formats. It is up to you to define a format which is usable by your chosen language!
Please make sure that you also enter spaces, tabs and CR/LF where appropriate - TileMaster will not compensate if you forget to add these!
The user-definable options are:

New line prefix: Some text you want to start each new line with, e.g. '{' for C or 'dw ' for asm [without quotes of course - but including spaces :)] - or even nothing at all!

New line postfix: Text to end the new line with, e.g. '}'

New line indent: How many spaces to indent each line with.

Data seperator: I suspect that most people will want to use ',' but if you're feeling in the mood for adventure, you can use what you like ;)

Offset to add to data: By default, TileMaster numbers its tiles from 0 to however many tiles there are (going from top left to bottom right). This option lets you add an offset to each data item, so you can (for example) prevent numbering conflicts when using multiple sets of graphics, or to use the value 0 to define an empty block (see below).

Empty block definition: TileMaster uses this value to define regions of empty space. A typical graphics engine will look out for this value and not try to draw anything if it is encountered.

Insert seperator at end of every new line except last: For C-style 2D array definitions, or a 1D array formatted over multiple lines, check this box. For asm-style output, uncheck this box.

Data header: Semi-free text input (see section below on reserved words) - its up to you to make sure its legal for your target language though!

Data trailer: See data header.

There are also buttons that allow you to load a previously defined format definition, or save the current definition.
Reserved words
There are 5 reserved words (at the moment) that you can use in the Data header/Data trailer window that may come in useful. Upon encountering one of these reserved words, an appropriate piece of data is substituted in its place. Note that this process only takes place when the file is being exported. The reserved words are:

<width> The number of blocks going across the screen.

<height> The number of blocks going down the screen.

<tilewidth> The number of pixels going across per tile.

<tileheight> The number of pixels going down per tile.

<filename> The name of the file being exported, minus the extension.

Help -> About
No help here, but a bit of info telling you where you can find some!

2: The Tile Window

The tile window is the area which contains the graphics for the map blocks. To select a map block, just click on the block. You can then click or drag the mouse in the main window to place the block.

3: The Main Window

Placing a block

Firstly, you must select a block, as described in the description of the tile window. To place a block, click the mouse button in the main window. You can drag the mouse in order to draw the blocks in freehand.
Removing a block
To remove a block from the Main Window, hold down the right mouse button while clicking/dragging.
NOTE (Mac users): Hold down CTRL while clicking/dragging the mouse in the main window. I don't have access to a Mac so I can't test out the long click function. If Java interprets a long click as a right mouse button event then so much the better, maybe someone can email me and i'll update the manual!

4: Final thoughts

0.3 is here, and with this release, it is just about ready to break out of the Yaroze-only util category and go more general purpose :) There are still a few untidy bits here and there, and a couple of other features missing that I want to implement, but those of you who downloaded the prototype and threw it in the bin should hopefully see a bit of a general improvement!
Many thanks go to Pal for his suggestions for improvements/encouragement, without which I would probably have left TileMaster gathering dust! He also pointed out a faster way of redrawing the screen without resorting to double buffering, nice one mate!
I'm still open to any feedback! Email me at a.partington@yaroze41.freeserve.co.uk