Solarus quests  1.5
Quest maker's reference
Solarus 1.5 - 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 (either by the solarus-run executable or by the Solarus GUI).

When you run the solarus-run 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-run 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.

When you run the Solarus GUI (the solarus executable file), you can select graphically the quest to run and you can change some settings.

In both cases, the quest may have one of the following two forms:

  • A zip archive called data.solarus or data.solarus.zip 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 / data.solarus.zip 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.
  • logos/: icons and logos of your quest, used by the Solarus GUI to represent your game.
    • logos/logo.png: a 200x140 logo of your quest.
    • logos/icon_*.png: icon of your quest with various possible sizes.
  • sounds/: contains all sound effects.
    • sounds/*.ogg: your sound files.
  • musics/: contains all musics.
    • musics/*.{ogg, it, spc}: your music files.
  • fonts/: contains the fonts used to draw text in your quest.
    • text/*.{ttf, ttc, 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".
  • entities/: contains all custom entity Lua scripts.
    • entities/xx.lua: Lua script that defines the properties and the behavior of the custom entity model "xx".