Solarus solarus-0.9.1
Tileset syntax specification

A tileset is the skin of a map. It is composed of a set of tile patterns that a map can use. The tilesets directory contains the tilesets and their images. For a tileset whose id is XXXX (an integer number on four digits, like the maps), the file tilesetXXXX.dat describes all its tile patterns. We give here the detailed specification of the format of this file.

The images of the tile patterns are picked in the file tilesetXXXX_tiles.png. A tile pattern is a rectangle image inside this PNG file, with any size multiple of 8*8 pixels, and some obstacle and animation properties.

The obstacle property of a tile pattern can have the following values (these values are from the enumration Obstacle):

  • 0 (no obstacle): the tile is normal ground without obstacle
  • 1 (obstacle): the tile cannot be traversed
  • 2 (top-right): the upper-right half of the tile is an obstacle
  • 3 (top-left): the upper-left half of the tile is an obstacle
  • 4 (bottom-left): the lower-left half of the tile is an obstacle
  • 5 (bottom-right): the lower-right half of the tile is an obstacle
  • 6 (empty): there is no ground here: you should look at a lower layer
  • 7 (top-right in water): the upper-right half of the tile is an obstacle, the rest is deep water
  • 8 (top-left in water): the upper-left half of the tile is an obstacle, the rest is deep water
  • 9 (bottom-left in water): the lower-left half of the tile is an obstacle, the rest is deep water
  • 10 (bottom-right in water): the lower-right half of the tile is an obstacle, the rest is deep water
  • -1 (deep water): the tile is some deep water (the hero drowns or swims)
  • -2 (shallow water): the tile is shallow water (the hero may walk on it)
  • -1 (deep water): the tile is some deep water (the hero drowns or swims)
  • -2 (shallow water): the tile is shallow water (the hero may walk on it)
  • -3 (hole): the tile is a hole (the hero falls into it)
  • -4 (ladder): the tile is a ladder (the hero walks slowly on it)

A tile pattern also has an animation property:

  • 0 (fixed pattern): the pattern has no animation (like most tiles).
  • 1 (3-frame pattern): the pattern repeats an animation of three frames, with the sequence 0-1-2-0 or 0-1-2-1-0. Examples of use: water, lava, flowers.
  • 2 (self scrolling pattern): when the camera moves, the pattern scrolls on itself (twice slower than the camera). This achieves the same effect as parallax scrolling, but the tile remains displayed at its position. However, this is limited to simple, repeatable patterns: you cannot make big scrolling backgrounds composed of different tiles (use parallax patterns for this) because no tile actually moves with the camera, they just scroll on themselves. Example of use: holes in dungeons.
  • 3 (time scrolling pattern): the pattern scrolls on itself with time in a direction (not implemented yet, will probably be removed in the future).
  • 4 (parallax scrolling pattern): when the camera moves, the place where the pattern is displayed also moves (twice slower) to give illusion of depth. Placing such tiles on your map can be tricky because at runtime, they are displayed elsewhere (except in the particular case where the camera is in (0,0), the top-left corner of the map). Note that collisions properties remain applied to the real position of the tile and not to where they are displayed. Usually, parallax scrolling is used for decoration only. Example of use: a complex background panorama.
  • 5 (3-frame + parallax): combines the properties of 3-frame animated patterns and parallax scrolling patterns.

Finally, a tile pattern has a default layer. This is the layer suggested by the map editor when placing the tile onto a map:

  • 0 (low layer): the tile is always displayed below the hero (e.g. lower rooms in dungeons)
  • 1 (intermediate layer): the hero may be above or below the tile (e.g. most of the rooms in dungeons)
  • 2 (high layer): the tile is above everything (e.g. a tree)

When you add a tile to a map with the map editor, it is placed on its default layer, but then you may then change the layer. Thus, the default layer property is only used by the map editor, not by the game.

A tileset description file is a clear text file. Here is an example of such a file:

255	255	255
1	0	0	0	16	0	16	16
2	0	0	0	32	0	16	16
163	0	0	2	152	240	8	32
164	0	0	2	160	240	8	32
165	0	0	2	168	240	8	32
166	0	1	0	200	240	32	24
167	0	1	0	232	240	24	32
168	0	1	0	200	264	24	32

The first line is the background color of the maps using this tileset (with the RGB notation). Each one of the remaining lines describes a tile pattern. The first element of the line is always the id of the tile pattern (an integer number), the second one is the animation type, and the remaining part of the line depends on the number of frames of the pattern.

Single-frame patterns

Syntax of patterns having only one frame (i.e. fixed patterns, self scrolling patterns, time scrolling patterns and parallax scrolling patterns):

id   animation_type   obstacle   default_layer   x   y   width   height

id identifies the pattern. animation_type indicates the type of animation (can be 0, 2, 3 or 4). obstacle and default_layer are the properties explained above. x, y, width and height define the rectangle of the tile pattern in the PNG image.

Multi-frame patterns

Syntax of animations patterns with three frames (i.e. 3-frame patterns and 3-frame + parallax patterns):

id   animation_type   obstacle   default_layer   animation_sequence   width   height   x1   y1   x2   y2   x3   y3

animation_type indicates the type of animation (can be 1 or 5). animation_sequence determines how the three frames of the animation are played: 1 means 0-1-2-0, and 2 means 0-1-2-1-0. width, height, x1, y1, x2, y2, x3 and y3 define the location of the three rectangles in the PNG image (the size is the same for all rectangles).