We explain here how a quest is built. A quest is a data package that may be run by the C++ engine (the executable file).

When it is installed, the project is divided in two parts:

Solarus (the engine), which is an executable file written in C++ under GPL and called solarus.
One or several quests, each quest corresponding to a zip archive called data.solarus and containing all the data.

When you run the solarus binary, it needs the path of the quest to launch. This can be done at runtime by specifying the path as an command-line argument: solarus path/to/your/quest flag of the executable. If the quest path is not specified, the current directory is considered by default. The release versions require the quest files to be in a zip archive called data.solarus and located in this quest path. The debug versions first look in a subdirectory of the quest path called data (if existing) and directly pick the data files in this subdirectory. Thus, when developping your quest, you should use the development version (see the documentation to get the source and compile it). You will then be able to edit your quest and see the changes immediately in the game without having to rebuild the zip archive. In fact, when you modify a map, you don't even need to restart the game.

In other words, the simplest way of editing a quest is the following. Put the debug version of the executable file (the engine) in a directory, and put the data subdirectory (the quest) in the same directory. When running the program, the quest located in data is run.

For now, only one quest is available (zsdx), and this quest is not under GPL since it uses elements from Nintendo. If you are interested in creating a quest, I recommend to copy zsdx and modify it instead of starting from nothing.

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

Root directory

Two files are directly placed inside the data directory: info.dat and project_db.solarus.

General quest information file

The quest file is an ini-like file that contains some general data regarding the quest. This includes a group named info which contains (for now) the following values:

title_bar: the text to display in the title bar of the game window.
write_dir: name of the directory where the data of this quest will be saved (this will be a subdirectory of $HOME/.solarus). This is usually a short name for your quest. This allows games of different quests to be saved in different directories.
outside_world_width and outside_world_height: size of the whole outside world in pixels (used to manage the minimap).

Another group named initial indicates some initialization parameters of the quest:

starting_map and starting_point: initial location of the hero (id of the initial map and name of the initial destination point) when starting a new game.
max_life: maximum level of life when starting a new game.

Example:

[info]
# General information about this quest
title_bar = Zelda: Mystery of Solarus DX
write_dir = zsdx
outside_world_width = 2080
outside_world_height = 3584

# Somes initial values when creating a new savegame
[initial]
starting_map = 0
starting_point = start_position
max_life = 12

Project database

The project_db.dat file is NOT used by the engine, but only by the quest editor. The quest editor is still in development and there is no stable release. This file contains a list of all resources (maps, musics, sprites, items, enemies, etc.) of the quest and their human-readable names. Each resource is usually represented by a data file. The map editor needs it only to provide graphical components that let the user choose a resource in a list of human-readable names.

For instance, when the user creates a teletransporter on the map, a graphical list lets him choose the destination map of the teletransporter. This list contains the human name of each map. The engine does not need this, it only needs an internal id that identifies the map.

We give here the syntax of project_db.dat. This is a text file where each line represents a single resource. Each line has the following syntax:

resource_type	id	human readable name

resource_type is an integer identifying the type of resource (a map, a music, a sprite, etc.). id is a value that identifies the resource. The id allows to find the resource file. Depending on the type of resource, this may be an integer or a string (without spaces). human readable name is a name that describes the resource. The map editor will display this name to the user but will use the id internally.

The current types of resources are:

0: a map (the id is an integer),
1: a tileset (the id is an integer),
2: a music (the id is the music file name with its extension),
3: a sprite (the id is the sprite file name without extension),
4: a sound (the id is the music file name with its extension),
5: an item (the id is the name of item's Lua script without its extension),
6: an enemy (the id is the name of enemy's Lua script without its extension),
7: a dialogs file (the id is the dialogs file)

Sounds

The sounds directory contains all small sound effects used by both the engine and the quest. A sound file must have the extension .ogg (Ogg Vorbis). Note that in previous versions of the engine such as the demo version released on December 18th, 2009, the sounds were in WAV format. The files are lighter with the Ogg compression.

Musics

The musics directory contains all musics used by both the engine and the quest. For now, the following formats are recognized:

SPC: a Super NES original music file,
IT: Impulse Tracker Module,
OGG: Ogg Vorbis audio file. Future releases may support more music formats. You can ask me.

Fonts

The text directory contains the font files used by the engine. The formats recognized are the ones supported by the SDL_ttf library, including .ttf or .fon. It also contains a fonts.dat file with the syntax of an ini file. An example is self-speaking:

# This file defines the fonts available to the game engine.
# The engine relies on 3 fonts named 'dialog', 'dialog_big' and 'fixed'.
# The main purpose of this file is to make the engine independent from the font file names.

[dialog]
# the font used in dialog boxes
file = text/la.ttf
size = 11
default = true

[dialog_big]
# same as 'dialog' but bigger
file = text/la.ttf
size = 18

[fixed]
# fixed-width font used in the menus
file = text/fixed8.fon
size = 11

Language-specific files

When running the game for the first time, a language selection menu is displayed before the title screen. The language selected is then saved (independently of the savegames) and can be changed later from the options menu. The languages directory contains all language-specific data files (strings, dialogs and sprites).

The languages.dat ini-like file gives the list of the supported language and indicates the default one. We give here an example of this file:

[fr]
name = Français

[en]
name = English
default = true

[de]
name = Deutsch

[nl]
name = Nederlands

The language code (in square brackets) represents the name of the directory containing the language-specific files of this language. The value name is a human-readable name for the language. This name is displayed to the user in the language selection screen and in the options menu.

The directory languages is divided into several directories (one for each language). Then, there are two subdirectories:

text: contains all strings and game dialogs localized in this language. See the Text and dialog files syntax specification page to know the syntax of these files.
images: contains the images showing some text that needs to be translated.

Sprites

The sprites directory contains all images (animated or not) used by both the game and the engine. It also contains the sprite description files. The syntax of these files is specified in the Sprite syntax specification page.

Maps

The maps directory contains the full description and the script of each map. It also includes a subdirectory called dungeons that gives specific information about the dungeons.

Each map is specified with two files. Let us call XXXX the id of the map (which is an integer number). The id is represented with four digits in the file names.

mapXXXX.dat: full description of the map content (the walls, the enemies, the NPCs, the chests…). See the Map syntax specification page for the detailed specification of the map file syntax.
mapXXXX.lua: script of the map in Lua language. The script triggers dynamic events in this map, such as opening a door, making enemies appear, etc. See the Lua scripting API specification for scripting your maps.
mapXXXX.luac: compiled version of the Lua script.

In release versions, only the compiled script (.luac) is used. In debug versions, the engine first tries to open the source file (.lua) if it exists. Thus, you don't need to compile your scripts to test them when you make a change. The Lua source files of the zsdx quest are available on the subversion repository.

The maps/dungeons subdirectory contains important information for each dungeon. See the Dungeon files page for the specification of those files.

Tilesets

The maps are composed of small bricks called "tiles". The tiles are static: 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. Tiles can overlap each other and have different sizes. A tileset is a set of tiles that 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 the houses, another one for the dungeons, etc. The tilesets directory contains the tilesets and their images. For each tileset, if we denote by XXXX its id (an integer number on four digits, like the maps), we have three files:

tilesetXXXX_tiles.png: the PNG image containing all tile images.
tilesetXXXX.dat: the description file for tilesetXXXX_tiles.png. Each line describes a tile with its size and its properties. See the Tileset syntax specification page for the detailed specification.
tilesetXXXX_entities.png: some dynamic entities (i.e. other that tiles) such as doors and blocks have a skin that actually depends on the tileset. A door inside a dungeon has different graphics and colors from a door inside a cave. Such dynamic entities are skin-dependent and we need to store their graphics in this file. There is no description file (this file is organized the same way for each tileset).

Items

The list of all items the player can get (e.g. the inventory items, the equipment items, the treasures dropped by enemies or hidden under bushes, etc.) is specified in the file items.dat. This file as an ini-like syntax which is not specified in this documentation yet. However, the syntax is entirely specified in the comments of the items.dat file of the zsdx quest.

TODO specification of the format of items.dat

items.dat specifies the static properties of each item (e.g. its number of variants, its probability to be dropped by an enemy, its counter if any, etc.). The dynamic properties of each item is defined by a Lua script (e.g. what happens when the item appears, what happens when the player receives the items, etc.). These Lua scripts are located in the items subdirectory of the data directory of your quest.

See the section Lua scripting API specification to know the Lua API provided by Solarus to item scripts.

Enemies

The properties and the behavior of each enemy is defined by a Lua script in the enemies subdirectory of the data directory of your quest.

See the section Lua scripting API specification to know the Lua API provided by Solarus to enemy scripts.

Head up display

The HUD includes the elements shown on the screen such as the icons, the life bar, the money counter as well as the pause subscreens. Most of the HUD is hardcoded in the C++ code of the engine, but eventually, it will be defined by each quest as Lua scripts. In the meantime, the hud subdirectory of the data directory of a quest contains a single file inventory.dat. inventory.dat defines the names of the 28 items that will be shown in the inventory.