Solarus  1.0.0
Solarus 1.0 - Quest data files specification

We explain here how a quest is built.

A quest is a data package that may be run by the Solarus C++ engine (the Solarus executable file).

When you run the solarus executable file, it needs the path of the quest to launch. This can be done at runtime by specifying the path as a command-line argument: solarus path/to/your/quest. If the quest path is not specified, the current directory is considered by default, unless you compiled Solarus with another default quest path.

The quest in this path may have one of the following two forms:

  • A zip archive called data.solarus and containing all data of your quest. This archive form is useful when your quest is finished and you distribute it to people.
  • A directory called data and containing all data of your quest. This form is handy when you are developing your quest. It is also the only possible form to edit your quest with Solarus Quest Editor. In fact, when you modify a map in the editor, you don't even need to restart the game.

The data files represent all resources used by both the engine and the quest, such as sounds, musics, images, sprites, dialogs, maps and Lua scripts. We specify here the details for all those files.

Here is the full structure of the data directory / data.solarus archive of a quest and the syntax of each file.

  • quest.dat: global properties of your quest.
  • project_db.dat: list of all resources (maps, sprites, enemies...) with their id and human-readable name.
  • main.lua: main Lua script of your quest.
  • *.lua: other Lua scripts, possibly organized in subdirectories.
  • sounds/: contains all sound effects.
    • sounds/*.ogg: your sound files.
  • musics/: contains all musics.
    • musics/*.{ogg, it, spc}: your music files.
  • text/: contains the fonts used to draw text in your quest.
    • text/fonts.dat: the list of fonts and their properties.
    • text/*.{ttf, fon, png, ...}: your font files.
  • languages/: contains the language-specific files.
  • sprites/: contains all animated sprites, possibly organized in subdirectories.
    • sprites/xx.dat: definition of sprite "xx".
    • sprites/*.png: images used by your sprites (except the tileset-dependent ones).
  • maps/: contains all maps of your quest.
  • tilesets/: contains all tilesets available to maps.
    • tilesets/xx.dat: definition of tileset "xx" and all its tile patterns.
    • tilesets/xx.tiles.png": image with all tile patterns of tileset \c "xx".
    • tilesets/xx.entities.png: image with all tileset-dependent sprite animations for tileset "xx".
  • items/: contains all equipment item Lua scripts.
    • items/xx.lua: Lua script that defines the properties and the behavior of equipment item "xx".
  • enemies/: contains all enemy Lua scripts.
    • enemies/xx.lua: Lua script that defines the properties and the behavior of the enemy model "xx".