Solarus quests  1.6
Quest maker's reference
Quest properties file

Some general information regarding your quest are stored in the quest properties file quest.dat. This include information that the Solarus GUI can use to show a description of each quest before the user plays, as well as technical settings indicating how your quest should run.

quest.dat is mandatory: if this file does not exist, the engine considers that there is no quest in the directory.

Syntax of the quest properties file

Solarus Quest Editor fully supports the edition of the quest properties file. You should not have to edit quest.dat by hand unless you know what you are doing.

quest.dat is a text file encoded in UTF-8.

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.

The definition of your quest properties starts with quest{ and ends with }. Each property is 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, except when specified otherwise.

The recognized properties are listed below. Only solarus_version and title are mandatory, but write_dir is also required if you want to be able to use savegames.

  • solarus_version (string): Format of the engine your data files are compatible with. This string should be a major and minor version, for example "1.6". You can also indicate a full version string, including the patch number (like "1.6.1") but the patch number will be ignored. Patch versions are ignored because they don't break compatibility.
  • title (string): Name of your quest.
  • short_description (string, optional): A one-line description of the quest.
  • long_description (multi-line string, optional): A longer description of the quest. The text should be enclosed between [[ and ]], which is the notation for multiline strings.
  • author (string, optional): Person or team who created the quest.
  • quest_version (string, optional): Current version of your quest.
  • release_date (string, optional): Date of your last quest release (YYYY-MM-DD).
  • website (string, optional): URL of your website.
  • write_dir (string, optional): Directory where Solarus will write savegames and setting files for your quest. It will be a subdirectory of '$HOME/.solarus/', automatically created by the engine. Its name should identify your quest, to avoid confusion with other Solarus quests that might also be installed on the user's machine. You must define it before you can use savegames or setting files.
  • normal_quest_size (string, optional): Usual size of the game screen in pixels, as two integer values separated by "x". Example: "320x240". The default value is "320x240".
  • min_quest_size (string, optional): Minimum size of the game screen in pixels. Example: "320x200". No value means the same value as normal_quest_size.
  • max_quest_size (table, optional): Maximum size of the game screen in pixels. Example: "400x240". No value means the same value as normal_quest_size.

About the quest size

normal_quest_size, min_quest_size and max_quest_size define the range of possible sizes of the game screen. This is the logical size of the game area. It represents how much content the user can see on the map when playing your quest. Allowing a range of sizes instead of only one size improves the portability: each system and each user can choose a size that occupies the full ratio of the screen instead of having black bars. However, be aware that if you allow a range, some users will be able to see more game content than others!

At compilation time, systems can specify their preferred quest size. It will be used if it is in the range of sizes allowed by your quest. And the quest size can also be overriden at runtime with a command-line option.

At runtime, you are guaranteed that the actual quest size will be in the range allowed in this quest properties file.

The quest size is the logical size of your quest and it never changes at runtime. Don't confuse it with the size of the window. The actual window shown to the user may be bigger or smaller than that. It can resized and it can also be in fullscreen mode. When the window size is different from the quest size, the quest image is scaled to fit the window. Black bars are added if necessary to keep the correct ratio.


Example of quest.dat file:

  solarus_version = "1.6",
  title = "My incredible quest",
  write_dir = "my_quest",
  short_description = "This is the best game ever",
  long_description = [[
Travel the world and save the princess.
You will encounter great characters, epic battles and awesome puzzles.]],
  author = "John Doe",
  quest_version = "1.0",
  release_date = "",
  website = "",
  normal_quest_size = "320x240",
  min_quest_size = "320x240",
  max_quest_size = "320x240",
The syntax of the quest properties file is actually valid Lua. The engine internally uses Lua to parse it.