RPG Mapper: Creating Custom Tilesets

This tutorial was written as of RPG Mapper version 0.0.3, and as features improve and change, may become outdated.

Creating custom tilesets is accomplished by creating a ZIP file contain graphic files. Graphic files should be in a format readable by the Java virtual machine; currently supported formats are GIF, JPEG, and PNG. (PNG format is personally perferred by me since it allows full color images, and for most tilesets where the tiles are very small, it works about as well as JPEG images.)

Start by creating the tiles in your favorite graphics program, and saving the images into subdirectories of a directory on your harddrive where you are storing the tileset. The following directories can be within the tileset:

ground - place tiles that represent standard ground terrain (grass, dirt, sand) in this directory.
water - place tiles that represent water (such as lakes, streams, and waterfalls) in this directory.
path - place tiles that represent roads and paths in this directory.
landscape - place tiles that represent landscape (flowers, decorative bushes or trees) in this directory. (Non-decorative trees, such as forests and the like, belong in the ground directory.)
wall - place tiles that represent walls of buldings in this directory (but not walls that belong outdoors, that should be in the landscape directory like stone walls).
interior - place tiles that represent interior floors in this directory.
decorative - place tiles that represent decorative (such as statues, tables, and other interior decorations) imagery in this directory.

[Note 1]

When loading a tileset, all files will be attempted to be loaded as image files. [Note 2] However, there is one special file that is not treated as a graphics file, it is called "tiles.txt" and should not be placed in any subdirectories. [Note 3] This file gives various parameters about the tileset, and is required in order for maps to be saved or loaded using the new tileset. Below is an example of the file format to be stored in the text file.

Section Header
width = 32
height = 32
type = square
name = "Wilderness Outdoor Set"
author = "Daniel Potter"
id = "dmpotter.outdoors.wilderness"
default = "ground/grass.png"
EndSection

The directives listed above are for a square map type, and are the basic directives required. In fact, only the type, name, and id parameters really need to be specified, as the rest can be determined automatically. Failing to name the tile will cause the tileset to be named "Tile Set Containing x Tiles" in the New Map... dialog. The following is a list of parameters and what they mean:

width / height - the width and height of each individual tile
type - the type of tileset, either "square" or "hex" - for hex tilesets, see the section below on hex tilesets.
name - the name the tileset is given in the tileset selection pulldown.
author - the author of the tileset (as of 0.0.3, this field isn't used).
id - An important parameter! Ensure that this parameter is defined - it gives an id to your tileset that is stored in saved maps that use it. This ID (which should be unique) is the method that the Mapper application uses to know how to choose the tileset to render a loaded map with. The general naming scheme is "author name.type.tileset name" where author name is whatever you want to use as your nickname (I use my first two initials and my full last name), type is a generic type of set (and is fairly optional) and name is a representation of the tileset name (a keyword, perhaps). Spaces are allowed in the id name (but the keyword must be quoted if spaces are used).
default - an optional string that represents the file name (and later, ID string) of the tile that should be used to blank out new maps created with this tileset.

Once the tileset is ready, the directory that contains the tiles.txt file and the various subdirectories containing tiles should be zipped into a single file. Placing the tileset zip file into the tilesets directory will cause it to be loaded when the application starts up again (not the next time the New Map... dialog is displayed).

Hex Tilesets

There are two additional parameters needed when creating a hex tileset; evenOffsetX and offsetY. They specify the offsets that define where alternating rows of hex tiles are placed. The following diagram shows how the offsets effect the tiles:

Set the various parameters so that the hex tiles will align appropriately.

Note 1

As of 0.0.3, these directories do not actually do anything as far as the end-user is concerned. However, internally, the type codes are used and the tile the map is originally set to is choosen from the ground selection. Future versions will split the available tiles into the given sections, so when creating a tileset, use the directories, as removing (or renaming...) tileset files will cause maps created via the tileset to fail to load.

Note 2

It's unclear what happens if a non-graphics file is included; since images are loaded via the AWT toolkit which kindly enough gives no contract as to what happens when bogus data is given to the image loading function, I cannot give a definitive answer as to what will happen -- the files may be ignored and no empty tiles created, or an empty blank tile may be given instead. An exception might even be throw on some systems -- it depends on your Java environment. Mine seems to toggle between skipping the bad image and simply stalling when it attempts to load it, refusing to start the application because of it.

Note 3

If there are multiple "tiles.txt" files, or even files that end in "tiles.txt", then the last loaded will be used. There is really no way to tell which file will be loaded last unless you list the zip file with something that just lists entries in zipfile order.

RPG Mapper is hosted by