Skip to content

# Quest Data Files Specification

## Solarus Quests

A quest is how we call a game made with Solarus. We explain here how a quest is built.

Concretely, a quest is a data package that may be run by Solarus C++ engine. The engine is used either by the `solarus-run` executable or by Solarus Launcher.

## How to Run a Quest

### With `solarus-run`

When you run the `solarus-run` executable file, it needs the path of the quest to launch. It can be a folder or a file. 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.

On Windows

While on Unix systems (macOS, Linux), the executables don't have file extensions, on Windows, the executable is `solarus-run.exe`.

### With Solarus Launcher

When you run Solarus Launcher, you can select graphically the quest to run and you can change some settings.

## Possible Quest Formats

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

- A `.zip` archive containing all data of your quest. This archive form is useful when your quest is finished and you distribute it to people.

- A `.solarus` archive containing. This is just a `.zip` archive, with a different extension.

- A directory called `data` and containing all data of your quest.

The latter form is handy when you are developing your quest. It is also the only possible form to edit your quest with Solarus Editor. In fact, when you modify a map in the editor, you don't even need to restart the game.

## Content of a Quest

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 / `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…) and additional information about quest files.

- `main.lua`: main Lua script of your quest.

- `**/*.lua:` other Lua scripts, possibly organized in subdirectories.
- `logos/`: images used by Solarus Launcher to represent your game.
- `sounds/`: contains all sound effects.
- `musics/`: contains all musics.
- `fonts/`: contains the fonts used to draw text in your quest.
- `languages/`: contains the language-specific files.
- `sprites/`: contains all animated sprites (`xx.dat` and `*.png`), possibly organized in subdirectories.
- `maps/`: contains all the maps of your quest (map definitions and their scripts).
- `tilesets/`: contains all tilesets available to maps (`xx.dat`, `xx.tiles.png` and `xx.entities.png`).
- `items/`: Lua scripts that define the properties and the behavior of equipment items.
- `enemies/`: Lua scripts that define the properties and the behavior of the enemies.
- `entities/`: contains all custom entity Lua scripts.
- `shaders/`: contain all shaders data files and their source code files (`*.glsl`).

April 1, 2025