Skip to content

# Quest Database File

## Overview

The `project_db.dat` file declares all resources (maps, musics, sprites, items, enemies, fonts, etc.) of your quest and stores other additional information about quest files. Each resource has an id and a description, and usually corresponds to one or several files.

The engine needs this database file to preload or initialize some resources when the program starts. Solarus Editor needs it to provide graphical components that let the user choose a resource in a list of user-friendly names.

## Syntax of the Database File

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

We give here the syntax of `project_db.dat`

`project_db.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. Empty lines are also ignored.

### Resources

There are 9 types of resources:

- `map,`
- `tileset,`
- `sound,`
- `music,`
- `sprite,`
- `item,`
- `enemy,`
- `language`
- `shader`

The `project_db.dat` file declares the list of such resources, with their id and their user-friendly description. The id of a resource element determines the name of the file(s) where this element is stored: for example, an enemy with id `"soldier"` will be defined in the script file `"enemies/soldier.lua"` See below for more details.

The definition of each resource element starts with the name of a resource type (from the list above), followed by an opening brace, and ends with a closing brace. Inside the braces, the properties of the resource are specified. Properties are declared with the syntax `key = value` and separated with commas. It is allowed to have an extra comma after the last property. String values are enclosed within double quotes. The following properties are recognized on resources:

`id` (string)
  Id of the element. It should not contain spaces. The id determines the data file(s) of this element. The id is always a file name without extension:

- For a map: the id is the name of the map data file without its extension, relative to the `maps` directory. Note that the first map declared in this file will be the default map.
- For a tileset: the id is the name of the tileset data file without its extension, relative to the `tilesets` directory.
- For a sound: the id is the sound file name without its extension, relative to the `sounds` directory.
- For a music: the id is the music file name without its extension, relative to the `musics` directory.

- For a sprite: the id is the name of the sprite data file, relative to the `sprites` directory. The sprite data file may be in a hierarchy of subdirectories. Subdirectories must be separated by a slash "/" character in the sprite id.

- For an equipment item: the id is the name of the item's Lua script without its extension, relative to the `items` directory.

- For an enemy model: the id is the is name of the enemy's Lua script without its extension, relative to the `enemies` directory.

- For a language: the id is the name of a subdirectory of the `languages` directory.

- For a font: the id is the font file name without its extension, relative to the `fonts` directory.

- For a shader: the id is the shader data file without its extension, relative to the `shaders` directory.

`description` (string, optional)
  A human-readable name that describes this element. It may contain spaces. The engine does not uses this description, but Solarus Editor may use it to show to users something more user-friendly than the id.

### File Authors and Licenses

The quest database file can keep track of the author and license of the files in your quest. The engine does not use these properties at runtime, but they may help you keep up-to-date information about your files in a complex project.

Resources described above (maps, sounds, etc.) are the core game elements recognized by the engine, but a quest is more general than that. A quest is a directory (or an archive) that contains various files and directories. Some of these files and directories correspond to resources, but there may also be a lot of files that are not resources, like additional Lua scripts or PNG files used by sprites.

After the list of resources, the `project_db.dat` file gives information about individual files and directories, independently of whether they are resources or not.

Files that are not resources do not have to be declared in the quest database file, but if they are, it allows to store useful information about them.

Information about a file or directory start with `file{` and ends with `}` Inside the braces, the properties of the file or directory are specified. Properties are declared with the syntax `key = value` and separated with commas. It is allowed to have an extra comma after the last property. String values are enclosed within double quotes. Each file or directory declared here has the following properties:

`path` (string)
  Path of the file or directory relative to the quest `data` directory. including the file name with its extension,
`author` (string, optional)
  Author of the file.
`license` (string, optional)
  License of the file.

Note

Information attached to a directory are considered to apply to all its files and directories except if they specify their own information as well.

## Example

Here is an example of a valid quest database file:

    map{      id = "outside",      description = "Outside World" }
    map{      id = "hero_house",   description = "House of the hero" }
    map{      id = "shop",         description = "Shop" }
    map{      id = "dungeon_1_1f", description = "Dungeon 1 - First floor" }
    map{      id = "dungeon_1_2f", description = "Dungeon 1 - Second floor" }

    tileset{  id = "overworld",    description = "Overworld" }
    tileset{  id = "house",        description = "House" }
    tileset{  id = "dungeon",      description = "Dungeon" }

    sound{    id = "door_closed",  description = "Door closing" }
    sound{    id = "door_open",    description = "Door opening" }
    sound{    id = "enemy_hurt",   description = "Enemy hurt" }
    sound{    id = "jump",         description = "Jumping" }
    sound{    id = "treasure",     description = "Treasure" }

    item{     id = "sword",        description = "Sword" }
    item{     id = "bow",          description = "Bow" }
    item{     id = "arrow",        description = "Arrows (x1 / x5 / x10)" }

    enemy{    id = "soldier",      description = "Soldier" }
    enemy{    id = "dragon",       description = "Dragon" }

    language{ id = "en",           description = "English" }

    font{     id = "8_bit",        description = "8 bit font" }

    file{     path = "sprites/enemies/soldier.dat", author = "John", license = "CC BY-SA 4.0" }
    file{     path = "sprites/enemies/soldier.png", author = "John", license = "CC BY-SA 4.0" }
    file{     path = "sprites/enemies/dragon.dat",  author = "Jack", license = "CC BY-SA 4.0" }
    file{     path = "sprites/enemies/dragon.png",  author = "Jack", license = "CC BY-SA 4.0" }

In Solarus Editor, you can add, remove and change the id and the description of resources from the quest tree. Therefore, you probably don't need to edit this file by hand.

April 1, 2025