Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

300 lines (237 sloc) 13.036 kb
\page quest Quests data files specification
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 \c solarus.
- One or several quests, each quest corresponding to a zip archive called \c data.solarus and containing all the data.
When you run the \c 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:
\c 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 \c data.solarus and located in this quest path.
The debug versions first look in a subdirectory of the quest path called \c 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 <a href="">get the source</a>
and <a href="">compile it</a>).
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 \c data subdirectory (the quest) in the same directory.
When running the program, the quest located in \c 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.
\section root Root directory
Two files are directly placed inside the \c data directory: \c info.dat and
\c project_db.dat.
\subsection info General quest information file
The \c quest file is an ini-like file that contains some general data regarding the quest.
This includes a group named \c info which contains (for now) the following values:
- \c title_bar: the text to display in the title bar of the game window.
- \c write_dir: name of the directory where the data of this quest will be saved
(this will be a subdirectory of \c $HOME/.solarus). This is usually a short name for your quest.
This allows games of different quests to be saved in different directories.
- \c outside_world_width and \c outside_world_height: size of the whole outside world in pixels (used to manage the minimap).
Another group named \c initial indicates some initialization parameters of the quest:
- \c starting_map and \c starting_point: initial location of the hero (id of the initial map
and name of the initial destination point) when starting a new game.
- \c max_life: maximum level of life when starting a new game.
# 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
starting_map = 0
starting_point = start_position
max_life = 12
\subsection project_db Project database
The \c project_db.dat file is used 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 quest 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 \c 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
\c resource_type is an integer identifying the type of resource (a map, a music, a sprite, etc.).
\c 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).
\c 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 the item's Lua script without its extension),
- 6: an enemy (the id is the name of the enemy's Lua script without its extension),
- 7: a language (the id is the language code),
- 8: a screen script (the id is the name of the screen's Lua script without its extension).
\section sounds Sounds
The \c sounds directory contains all small sound effects used by both the engine and the quest.
A sound file must have the extension \c .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.
\section musics Musics
The \c 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.
\section fonts Fonts
The \c 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 \c 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.
# the font used in dialog boxes
file = text/la.ttf
size = 11
default = true
# same as 'dialog' but bigger
file = text/la.ttf
size = 18
# fixed-width font used in the menus
file = text/fixed8.fon
size = 11
\section languages Language-specific files
Language features allow to translate a quest.
The language selected is saved independently of the savegames.
All language-specific data files (strings, dialogs and sprites)
are saved in the \c languages directory.
The \c languages/languages.lua file gives the list of the supported language
and indicates the default one.
We give here an example of this file:
code = "fr",
name = "Français"
code = "en",
name = "English",
default = true
code = "de",
name = "Deutsch"
The value \c code identifies the language.
It represents the name of the directory
containing the language-specific files of this translation.
The value \c name is a human-readable name for the language.
You can show this name to the user in your language selection menu.
The directory \c languages is divided into several directories
(one for each translation).
Then, there are two subdirectories:
- \c text: contains all strings and game dialogs localized in this language.
See the \subpage dialog_syntax page to know the syntax of these files.
- \c images: contains the images showing some text that needs to be translated.
\section sprites Sprites
The \c 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 \subpage sprite_syntax page.
\section maps Maps
The \c maps directory contains the full description and the script of each map.
It also includes a subdirectory called \c 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.
- \c mapXXXX.dat: full description of the map content (the walls, the enemies, the NPCs, the chests…).
See the \subpage map_syntax page for the detailed specification of the map file syntax.
- \c 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 \ref lua_api for scripting your maps.
In release versions, only
the compiled script (\c .luac) is used.
In debug versions, the engine first tries to open the source file (\c .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
<a href="">subversion</a> repository.
The \c maps/dungeons subdirectory contains important information for each dungeon.
See the \subpage dungeon_syntax page for the specification of those files.
\section tilesets 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 \c 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:
- \c tilesetXXXX_tiles.png: the PNG image containing all tile images.
- \c tilesetXXXX.dat: the description file for tilesetXXXX_tiles.png. Each line describes a tile
with its size and its properties. See the \subpage tileset_syntax page for the detailed specification.
- \c 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).
\section items 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 \c 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 \c items.dat
file of the \c zsdx quest.
TODO specification of the format of items.dat
\c 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 \c items subdirectory of the \c data
directory of your quest.
See the section \ref lua_api to know the Lua API provided by Solarus
to item scripts.
\section enemies Enemies
The properties and the behavior of each enemy is defined by a Lua script in the
\c enemies subdirectory of the \c data directory of your quest.
See the section \ref lua_api to know the Lua API provided by Solarus
to enemy scripts.
\section hud 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 \c hud subdirectory of the \c data directory of a
quest contains a single file \c inventory.dat.
\c inventory.dat defines the names of the 28 items that will be shown
in the inventory.
Jump to Line
Something went wrong with that request. Please try again.