2.12 - Tileset definition file

Maps are composed of small bricks called tiles. Tiles are static entities: they cannot be moved or removed dynamically during the game. They are opposed to all dynamic entities such as enemies, doors, bushes, switches, etc. Each tile is a graphical element whose width and height are multiple of 8 pixels. When placed on a map, tiles can have different sizes and can overlap each other.

A tileset is a list of patterns that tiles on a map can use. You can call it the skin of the map. For example, there may exist a tileset for the outside world, another one for houses, another one for dungeons, etc.

The tilesets directory contains all tilesets and their images. For a tileset with id xx, there are three files:

Tile patterns defined in xx.tiles.png can be fixed or animated with several frames. Examples of uses of multi-frame patterns are water, flowers and lava.

Tile patterns can also have special scrolling effects like parallax scrolling.

Syntax of the tileset data file

Solarus Quest Editor fully supports the edition of tilesets. You should not have to edit tileset data files by hand unless you know what you are doing.

We now specify the syntax of a tileset data file.

The sequence of characters -- (two dashes) marks the beginning of a comment. After them, the rest of the line is ignored by the engine. Empty lines are also ignored.

Background color

The first element in the tileset file is the background color of the maps using this tileset. The definition of this background color starts with background_color{ and ends with }. Inside the braces, the background color is specified in RGB format: three integers between 0 and 255, separated by commas. It is allowed to have an extra comma after the last integer value.

Example of background color definition:

background_color{ 104, 184, 104 }

Tile patterns

After the background color definition, the tileset data file defines all tile patterns of the tileset. The definition of a tile pattern starts with tile_pattern{ and ends with }. Inside the braces, the properties of the tile pattern are specified. Properties are declared with the syntax key = value and separated with commas. It is allowed to have an extra comma after the last property. String values should be enclosed within double quotes. Each tile pattern must have the following properties:

Example of a tile pattern:

tile_pattern{
  id = "wall.1",
  ground = "wall",
  default_layer = 0,
  x = 64,
  y = 48,
  width = 24,
  height = 16,
  repeat_mode = "vertical",
}

Border sets

After the definition of all tile patterns, the tileset data file may contain the definition of border sets. Border sets are useful for auto-tiling. The quest editor uses them to allow the user to automatically generate borders around some selected entities in the map editor. Border sets currently have no effect in the engine itself: they are only used by the quest editor and they generate regular tiles.

A border set is a list of 12 tile pattern ids that correspond to 4 edges, 4 convex corners and 4 concave corners.

The definition of a border set starts with border_set{ and ends with }. Inside the braces, the properties of the border set are specified. Properties are declared with the syntax key = value and separated with commas. It is allowed to have an extra comma after the last property. String values should be enclosed within double quotes. Each border set has the following properties:

The properties pattern_0 to pattern_11, if defined, should all be ids of existing patterns in this tileset. These properties are all optional: if some of them are unset, it means that no border tile should be generated for the corresponding edges or corners. It is possible that several of these properties refer to the same pattern: it means that the same pattern can be used for several different edges or corners.

Example of a border set:

border_set{
  id = "wall",
  pattern_0 = "wall.4",
  pattern_1 = "wall.1",
  pattern_2 = "wall.3",
  pattern_3 = "wall.2",
  pattern_4 = "wall.corner.2",
  pattern_5 = "wall.corner.1",
  pattern_6 = "wall.corner.3",
  pattern_7 = "wall.corner.4",
  pattern_8 = "wall.corner_reverse.2",
  pattern_9 = "wall.corner_reverse.1",
  pattern_10 = "wall.corner_reverse.3",
  pattern_11 = "wall.corner_reverse.4",
}

Tileset data file example

Here is an example of a valid tileset file:

background_color{ 104, 184, 104 }

tile_pattern{
  id = "path_dirt",
  ground = "traversable",
  default_layer = 0,
  x = 32,
  y = 0,
  width = 16,
  height = 16,
}

tile_pattern{
  id = "ocean",
  ground = "deep_water",
  default_layer = 0,
  x = { 0, 8, 16 },
  y = { 32, 32, 32 },
  width = 8,
  height = 8,
}

tile_pattern{
  id = "parallax_tree",
  ground = "traversable",
  default_layer = 0,
  x = 320,
  y = 448,
  width = 16,
  height = 24,
  scrolling = "parallax",
}
Remarks
This syntax of the tileset data file is actually valid Lua. The engine and the editor internally use Lua to parse it.