2.11 - Map definition file

The maps directory contains the full description and the script of each map.

Maps are areas where the game takes place. They may be rooms, houses, entire dungeon floors, parts of the outside world or any place.

A map with id xx is defined with two files:

A map is composed of the following information:

All of this is stored in the map data file xx.dat. We now specify its syntax.

Syntax of the map data file

Solarus Quest Editor fully supports the edition of maps. You should not have to edit map data files by hand unless you know what you are doing.

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.

Map properties

The first element in the map data file describes the properties of the map. The definition of these properties starts with properties{ and ends with }. 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 should be enclosed within double quotes. The following properties must be defined:

Example of map properties definition:

properties{
  width = 2048,
  height = 2048,
  world = "outside",
  x = 0,
  y = 0,
  tileset = "overworld",
  music = "village",
}

Declaration of map entities

The rest of the map data file declares all entities (tiles, enemies, chests, etc.) initially present on the map when this map is loaded during the game.

Remarks
Recall that during the game, after this loading phase, map entities can also be created or destroyed dynamically using the Lua map scripting API.

There exists many types of entities and most of them can be declared in the map data file. Here is their list (if you want all types of map entities, including the ones that cannot be declared in the map data file, see the map entity API):

The definition of a map entity starts with entity_type{ and ends with }, where entity_type is a type of entity (see below). Inside the braces, the properties of the entity 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 should be enclosed within double quotes and cannot have line breaks. Table values are enclosed within braces: { and } and contain elements separated by commas (an extra comma is allowed after the last element).

In each layer, entities are ordered like they are declared in the map data file: the first entity in the map data file is the most to the back, the last one is the most to the front. But tiles are always below all other types of entities because they are optimized at runtime. Therefore, tiles are always declared first in the map data file for each layer.

Common properties

The following properties exist for all types of entities:

name, x, y, layer and properties are common to all types of entities (except name for tiles).

Example of entity that includes additional properties:

sensor{
  layer = 0,
  x = 912,
  y = 453,
  width = 16,
  height = 16,
  properties = {
    {
      key = "sound",
      value = "fanfare",
    },
    {
      key = "image",
      value = "smiley.png",
    },
  }
}

We now detail the specific properties of each type of entity.

Tile

Tiles are the small fixed bricks that compose the map.

The engine makes a special performance treatment for them. For this reason, this map data file is the only place where they can be declared: they can never be accessed or created at runtime. If you want to access a tile at runtime (typically, to make it appear or disappear), use a dynamic tile instead.

A tile must be declared in the map data file with tile{ ... }.

Additional properties:

Example of tile:

tile{
  layer = 0,
  x = 1656,
  y = 104,
  width = 96,
  height = 16,
  pattern = "dark_wall",
}

Dynamic tile

Dynamic tiles are like tiles, except that they are not optimized at runtime. Therefore, they can be enabled, disabled, created and deleted using the Lua API.

A dynamic tile can be declared in the map data file with dynamic_tile{ ... }.

Additional properties:

Example of dynamic tile:

dynamic_tile{
  layer = 0,
  x = 552,
  y = 488,
  width = 48,
  height = 8,
  name = "bridge",
  pattern = "bridge_path",
  enabled_at_start = false,
}

Teletransporter

A teletransporter is a detector that sends the hero to another place when he walks on it.

A teletransporter can be declared in the map data file with teletransporter{ ... }.

Additional properties:

Example of teletransporter:

teletransporter{
  layer = 1,
  x = 112,
  y = 600,
  width = 16,
  height = 16,
  transition = "fade",
  destination_map = "dungeon_1_1f",
  destination = "from_outside",
}

Destination

A destination is a possible arrival place for teletransporters.

A destination can be declared in the map data file with destination{ ... }.

Additional properties:

Example of destination:

destination{
  name = "from_outside",
  layer = 0,
  x = 160,
  y = 37,
  direction = 1,
  default = true,
}

Pickable treasure

A pickable treasure is a treasure on the ground that the hero can pick up.

A pickable treasure can be declared in the map data file with pickable{ ... }.

Additional properties:

Example of pickable treasure:

pickable{
  layer = 0,
  x = 216,
  y = 845,
  treasure_name = "rupee",
  treasure_variant = 3,
  treasure_savegame_variable = "castle_rupee_1_found",
}

Destructible object

A destructible object is an entity that can be cut or lifted by the hero and that may hide a pickable treasure.

A destructible object can be declared in the map data file with destructible{ ... }.

Additional properties:

Examples of destructible objects:

destructible{
  layer = 0,
  x = 232,
  y = 165,
  treasure_name = "heart",
  sprite = "entities/white_stone",
  destruction_sound = "stone",
  weight = 1,
  damage_on_enemies = 2,
}

destructible{
  layer = 0,
  x = 264,
  y = 165,
  treasure_name = "heart",
  sprite = "entities/grass",
  can_be_cut = true,
  ground = "grass",
}

Chest

A chest is a box that contains a treasure.

A chest can be declared in the map data file with chest{ ... }.

Additional properties:

Example of chest:

chest{
  layer = 1,
  x = 168,
  y = 645,
  treasure_name = "sword",
  treasure_variant = 2,
  treasure_savegame_variable = "dungeon_6_sword_2_found",
  sprite = "entities/chest",
}

Shop treasure

A shop treasure is a treasure that can be purchased by the hero for money.

A shop treasure can be declared in the map data file with shop_item{ ... }.

Additional properties:

Example of shop treasure:

shop_item{
  layer = 1,
  x = 200,
  y = 104,
  treasure_name = "health_potion",
  price = 160,
  dialog = "witch_shop.health_potion",
}

Enemy

An enemy is a bad guy that hurts the hero when touching him.

An enemy can be declared in the map data file with enemy{ ... }.

Additional properties:

Example of enemy:

enemy{
  layer = 0,
  x = 912,
  y = 453,
  direction = 3,
  breed = "knight_soldier",
  treasure_name = "rupee",
}

Non-playing character

A non-playing character (NPC) is somebody or something that the hero can interact with by pressing the action command or by using an equipment item just in front of it.

A non-playing character can be declared in the map data file with npc{ ... }.

Additional properties:

Example of non-playing character:

npc{
  layer = 0,
  x = 648,
  y = 389,
  direction = 3,
  subtype = "0",
  sprite = "entities/sign",
  behavior = "dialog#outside_world.old_castle_sign",
}

Block

Blocks are solid entities that may be pushed or pulled by the hero.

A block can be declared in the map data file with block{ ... }.

Additional properties:

Example of block:

block{
  layer = 1,
  x = 584,
  y = 69,
  direction = 3,
  sprite = "entities/block",
  pushable = true,
  pullable = false,
  maximum_moves = 1,
}

Jumper

A jumper is an invisible detector that makes the hero jump into one of the 8 main directions when touching it.

A jumper can be declared in the map data file with jumper{ ... }.

Additional properties:

Example of jumper:

jumper{
  layer = 0,
  x = 192,
  y = 824,
  width = 8,
  height = 32,
  direction = 6,
  jump_length = 40,
}

Switch

A switch is a button that can be activated to trigger a mechanism.

A switch can be declared in the map data file with switch{ ... }.

Additional properties:

Example of switch:

switch{
  name = "open_door_2_switch",
  layer = 1,
  x = 376,
  y = 152,
  subtype = "walkable",
  sprite = "entities/switch",
  sound = "switch_pressed",
  needs_block = false,
  inactivate_when_leaving = true,
}

Sensor

A sensor is an invisible detector that triggers something when the hero overlaps it.

A sensor can be declared in the map data file with sensor{ ... }.

Additional properties:

Example of sensor:

sensor{
  name = "start_boss_sensor",
  layer = 0,
  x = 392,
  y = 301,
  width = 16,
  height = 16,
}

Wall

A wall is an invisible obstacle that stops some specific types of map entities.

A wall can be declared in the map data file with wall{ ... }.

Additional properties:

Example of wall:

wall{
  layer = 1,
  x = 416,
  y = 256,
  width = 24,
  height = 8,
  stops_hero = false,
  stops_enemies = true,
  stops_npcs = true,
  stops_blocks = true,
  stops_projectiles = true,
}

Crystal

A crystal is a switch that lowers or raises alternatively some special colored blocks in the ground called crystal blocks.

A crystal can be declared in the map data file with crystal{ ... }.

Additional properties: none.

Example of crystal:

crystal{
  layer = 0,
  x = 176,
  y = 965,
}

Crystal block

A crystal block is a colored low wall that may be raised or lowered in the ground.

A crystal block can be declared in the map data file with crystal_block{ ... }.

Additional properties:

Example of crystal block:

crystal_block{
  layer = 0,
  x = 120,
  y = 856,
  width = 112,
  height = 16,
  subtype = 1,
}

Stream

When walking on a stream, the hero automatically moves into one of the 8 main directions. The stream can allow or not the hero to move and use items. Streams can be used for example to make conveyor belts, water streams or air streams.

A stream can be declared in the map data file with stream{ ... }.

Additional properties:

Example of stream:

stream{
  layer = 1,
  x = 200,
  y = 157,
  direction = 5,
  sprite = "entities/air_stream",
  allow_movement = false,
  allow_attack = true,
  allow_item = true,
}

Door

A door is an obstacle that can be opened by Lua scripts and optionally by the hero under some conditions.

A door can be declared in the map data file with door{ ... }.

Additional properties:

Example of door:

door{
  layer = 1,
  x = 872,
  y = 184,
  direction = 2,
  sprite = "entities/door_small_key",
  savegame_variable = "dungeon_6_locked_door_1_open",
  opening_method = "interaction_if_savegame_variable",
  opening_condition = "dungeon_6_small_keys",
  opening_condition_consumed = true,
  cannot_open_dialog = "small_key_required",
}

Stairs

Stairs make fancy animations, movements and sounds when the hero takes them between two maps or to a platform of a single map.

Stairs can be declared in the map data file with stairs{ ... }.

Additional properties:

Example of stairs:

stairs{
  layer = 0,
  x = 384,
  y = 272,
  direction = 3,
  subtype = "1",
}

Separator

Separators allow to visually separate different regions of a map like if they were several maps. When the camera touches the separation, it stops like if there was a limit of a map. If the hero touches the separation, he scrolls to the other side.

A separator can be declared in the map data file with separator{ ... }.

Additional properties:

Example of separator:

separator{
  layer = 2,
  x = 320,
  y = 0,
  width = 16,
  height = 1280,
}

Custom entity

Custom entities have no special properties or behavior. You can define them entirely in your scripts. Optionally, a custom entity may be managed by model. The model is the name of a Lua script that will be applied to all custom entities refering to it. This works exactly like the breed of enemies, except that it is optional. The model is useful if you have a lot of identical (or very similar) custom entities in your game, like for example torches.

A custom entity can be declared in the map data file with custom_entity{ ... }.

Additional properties:

Examples of custom entities:

-- A cannon that exists only at this place of the game.
custom_entity{
  name = "cannon"
  layer = 0,
  x = 496,
  y = 232,
  width = 16,
  height = 16,
  sprite = "entities/cannon",
}

-- A minecart.
-- Managed by a model because several minecarts may exist in the game.
custom_entity{
  layer = 0,
  x = 152,
  y = 272,
  width = 16,
  height = 16,
  model = "minecart",
}
Remarks
The syntax of map data files is actually valid Lua. The engine and the editor internally use Lua to parse it.