- Generated on Sat Dec 31 2011 01:40:24 for Solarus by
1.7.4
|
Solarus solarus-0.9.1
|
A map is composed of the following information:
All of this is stored in a file maps/mapXXXX.dat where XXXX is the id of the map (an integer on four digits). This page describes the syntax of this file. Another file maps/mapXXXX.lua contains the script of the map, i.e. the dynamic events that occur on the map. See the Lua scripting API specification to know how a map script can interact with the game.
Most of the information listed above is given in the first line of maps/mapXXXX.dat. The first line has the following syntax:
width height world floor x y small_keys_variable tileset_id music_id
width and height give the size of the map in pixels.
world indicates the world the map belongs to:
floor indicates in what floor the map is located, between -16 and 15. The floor is displayed on the screen during a few seconds when the player gets in it. If the map is not on a floor (like all maps of the outside world and most of non-dungeon maps), the value is -100. There is also a special value, -99, that corresponds to an unknown floor: the '?' symbol will be displayed instead of the floor when arriving there.
x and y are the coordinates of the map in pixels, relative to its context. If the map is in a dungeon, they are the coordinates of the top-left corner of the map relative to the whole floor (in big dungeons, a floor can have several maps). If the map is in the outside world, they are the coordinates of the top-left corner of the map relative to the whole outside world. If the map is in the inside world (but not a dungeon), they are the coordinates of the place on the outside world (this allows to show the hero's location on the outside world minimap when the player shows the minimap screen).
small_keys_variable is the index of the variable that stores in the savegame the number of small keys of this map. This value is the same for all the map of the same dungeon. A value of -1 means that there is no small key counter in this map (this is the case most of the time for non-dungeon maps).
tileset_id is the index of the tileset used to draw the map.
music_id is the file name of the background music to play (relative to the musics directory) or none to play no music on the map, or same to let the previous music continue.
Then, each line of the file describes an entity of the map. Here is the general syntax of the line of en entity (elements in square brackets are present only for some types of entities):
entity_type layer x y [width] [height] [entity_name] [direction] [subtype] [specific_info…]
entity_type indicates what type of entity it is (according to the enumeration EntityType): a tile, an enemy, a chest, a teletransporter, etc.
The following three values are common to all types of entities:
layer is the layer where the entity is placed:
x and y are the coordinates in pixels where the entity is placed relative to the map. More precisely, its origin point is placed on this point.
Then, width and height are the size of the entity in pixels (only for entities with variable size). The width and height are always multiples of 8 pixels.
If the entity can be identified, entity_name is its name. Some types of entities have a name which allows to identify uniquely an instance (an enemy, a switch) at runtime, typically by the script of the map. For instance, is you want to make a switch open a door, your script needs to refer to this particular switch and this particular door. The name is chosen by the creator of the map and cannot start with the character '_' or have whitespaces.
If the entity has a direction property, it is given in the value direction, which is an integer number. Some types of entities have a direction property (enemies, NPCs, conveyor belts…) while other do not (tiles, pots, teletransporters, chests…).
Then, subtype indicates the subtype of this entity (only for some types of entity).
The remaining part of the line (specific_info) may contain specific information depending on the type of entity.
For now, the following types of entities are available when creating a map:
We detail below the exact syntax of each entity type.
A tile has no direction and no name. This means that you cannot modify, add or remove a tile at runtime: use dynamic tiles if you need to. A tile has a size: you can indeed repeat its pattern several times instead of placing many times the same tile on the map.
Syntax of a tile:
0 layer x y width height tile_pattern_id
tile_pattern_id is the index of the tile pattern in the tileset, as defined by the tileset file.
Note that tiles in the same layer can overlap. They are placed on the map in the same order as they appear in the map file. In other words, if two tiles overlap, the one that appears last in the file is placed above.
A destination point is a point of the map which is used as the destination of a teletransporter. A destination point has a direction between 0 and 3: this is the direction that the hero takes when he comes on the destination point. A value of -1 means that his direction should not change. A destination point also has a name (used by the teletransporters). Its size is fixed (16*16 which is the size of the hero).
Syntax of a destination point:
1 layer x y entity_name direction subtype
Subtypes of destination points:
A teletransporter is a sensor that sends the hero to a destination point on the same map or on another map. You can specify its size and a name.
Syntax of a teletransporter:
2 layer x y width height entity_name subtype transition destination_map destination_point
Subtypes of teletransporters:
transition is a number that indicates the type of transition played when taking the teletransporter, according to the enumeration Transition.
destination_map is the id of the map where the player is sent (possibly the same one).
destination_point is the name of the destination point where the player is placed on the destination map. Two special values are also supported: _side and _same. _side can be used for a teletransporter placed on the side of the original map, and that sends the hero on the corresponding side of the destination map. The new coordinates are automatically calculated. _same means that the coordinates of the hero remain the same as in the previous map. This can be used when falling into a hole. No destination point entity is needed when the value is _side or _same.
A pickable item is a treasure directly placed on the floor. The hero can pick it.
Syntax of a pickable item:
3 layer x y treasure_name treasure_variant treasure_savegame_variable
treasure_name, treasure_variant and treasure_savegame_variable define the treasure to give to the player when he picks the item. treasure_name must be an item declared in the file items.dat and treasure_variant is an integer that must be a valid variant for this item.
treasure_savegame_variable is used for items that can be obtained only once and need to be saved (e.g. a key). It is the index of the variable that stores the pickable item's state in the savegame. A value of -1 indicates that the item is not saved.
Destructible items are the ones that can hide pickable items and that the hero can lift or cut (or both).
4 layer x y subtype treasure_name treasure_variant treasure_savegame_variable
Subtypes of destructible items:
treasure_name, treasure_variant and treasure_savegame_variable define the pickable item hidden under the destructible item. See the previous section for their meaning. treasure_name can be "_random" or "_none".
A chest contains a treasure. The hero can open it to obtain the treasure.
Syntax of a chest:
5 layer x y entity_name is_big_chest treasure_name treasure_variant treasure_savegame_variable
is_big_chest is a boolean (0 ou 1) that indicates whether this is a big chest (1) or a normal chest (0).
treasure_name is a string identifying the item placed in the chest, according to the file items.dat. A value of "_none" means that the chest is empty or controlled by the script of the map.
treasure_variant is an integer that corresponds to the possession state of the item. Most items have only one variant and for them, this value is set to 1.
treasure_savegame_variable is the index of the savegame variable that stores the state of this chest. A value of -1 means that the chest is not saved.
A jumper is an invisible sensor that makes the hero jump a number of pixels into a direction, with a direction that depends on the shape of the sensor. During the jump, the hero cannot be controlled by the player and he can traverse obstacles.
Syntax of a jumper:
6 layer x y width height entity_name direction jump_length
The direction property of the jumper (0 to 7) determines both the shape of the sensor and the direction of the jump.
The size is cutomizable in order to allow jumps from different places along the cliff. For diagonal jumpers, the size of the bounding box is always square.
jump_length is the length of the jump in pixels. Make sure the length cannot send the hero into a wall.
Syntax of an enemy:
7 layer x y entity_name direction breed rank savegame_variable treasure_name treasure_variant treasure_savegame_variable
There are various kind of enemies. A kind of enemy is called its breed. Each breed is implemented as a Lua script.
breed is the name of the breed of the enemy. It must correspond to a Lua script located in the enemies directory.
rank indicates whether the enemy is considered as a normal enemy (0), a miniboss (1) or a boss (2). It has an influence on the minimap of dungeons (the boss of a dungeon is represented on the minimap) and on the dying animation of the enemy.
savegame_variable is used for enemies that can be killed only once in the game. It indicates the index of the boolean variable that stores the state of the enemy in the savegame. A value of -1 means that the enemy is not saved.
treasure_name, treasure_variant and treasure_savegame_variable define the pickable item dropped by this enemy when it is killed, (see the section about pickable items above). treasure_name can be "_random" or "_none".
An NPC is an entity that the hero can interact with by pressing the action key or using an inventory item just in front of it. The NPC is not necessarily a person, it can be a more general, solid interactive entity. The hero may talk to it, read what it shows or do another action. Most of the time, the action consists in starting a dialog, but you can define a custom action with a script.
8 layer x y entity_name direction subtype sprite_name behavior
Subtypes of NPCs:
direction has a different meaning depending on the subtype of NPC. For a usual NPC, it indicates the initial direction of its sprite (0 to 4) For a generalized NPC, it indicates the direction where the interaction is possible (0 to 4, or -1 to allow the interaction in any direction). For example, if the direction is 3, the interaction will be started only if the hero touches the south face of the entity.
sprite_name is the name of the animation set of the sprite to display with this entity (or _none to make the entity invisible)
behavior describes what happens when the player presses the action key near this entity. There are three possible options:
Syntax of a block:
9 layer x y entity_name direction sprite_name pushable pullable maximum_moves
sprite_name is the animation set id of the sprite to display for this block.
pushable (0 or 1) indicates whether the block can be pushed.
pullable (0 or 1) indicates whether the block can be pulled.
maximum_moves indicates what happens when the hero tries to push or pull the block:
The direction of the block indicates in which direction (0 to 3) it can be pushed or pulled. A value of -1 means that it can be pushed or pulled in any direction.
A dynamic tile is a tile with the specialy ability to be enabled or disabled by the script of the map. Dynamic tiles need to be separated from normal tiles because normal tiles are optimized for the detection of collisions.
Syntax of a dynamic tile:
10 layer x y width height entity_name tile_pattern_id enabled_at_start
tile_id is the id of the tile pattern from the tileset, like in the case of normal tiles. enabled_at_start is a boolean value (0 ou 1) that indictaes whether the tile is enabled when the map starts. When the tile is disabled, it is invisible and can be traversed.
When the hero triggers a switch, the map script is called. Some switches can only be activated by a block. Some switches are inactivated when the hero leaves them. The size of a switch is always 16*16 pixels. Its sprite depends on its subtype.
Syntax of a switch:
11 layer x y entity_name subtype needs_block inactivate_when_leaving
Subtypes of switches:
needs_block is a boolean value indicating that a switch of subtype pressure plate needs a block to be activated (nothing happens when the hero walks on it).
inactivate_when_leaving is a boolean value indicating that when the hero (or the block) leaves the switch, the switch is inactivated.
A custom obstacle is an invisible entity of variable size where some types of moving entities cannot pass.
Syntax of a custom obstacle:
12 layer x y width height entity_name stops_hero stops_enemies stops_npcs stops_blocks
The last four values are boolean values that indicate whether this custom obstacle is an obstacle for the hero, the enemies, the non-playing characters and the blocks, respectively.
A sensor is an invisible place of variable size that triggers something when the player walks on it. Unlike a switch, a sensor cannot be avoided by a jump. If you want the hero to be detected for sure when he enters somewhere, use a sensor rather than an invisible switch.
Syntax of a sensor:
13 layer x y width height entity_name subtype
Subtypes of sensors:
When a crystal is activated, some colored blocks in the ground are lowered or raised.
Syntax of a crystal:
14 layer x y
These are the blocks controlled by a crystal. Such blocks can have two colors. When they are lowered in the ground, they can be traversed. When they are raised, they are obstacle. Activating a crystal inverts their configuration.
15 layer x y width height subtype
Subtypes of crystal blocks:
A shop item is a treasure one can buy in a shop in exchange for money.
Syntax of a shop item:
16 layer x y entity_name treasure_name treasure_variant treasure_savegame_variable price dialog_id
treasure_name, treasure_variant and treasure_savegame_variable define the treasure to give to the player when he buys the item (see Treasure.h). The behavior of these values is identical to the case of chests. When loading the map, is the savegame indicates that the player has already bought the item, then the item is not created. When the player buys the item, it is removed from the map. If the treasure is not saved, the item can be bought several times and is not removed from the map.
price is the number of rupees to pay to buy the item.
dialog_id is the id of the dialog to show when the player looks at the item. The dialog describes the item. It is automatically followed by a dialog that asks to the player if he wants to buy the item.
When the hero walks on a conveyor belt, he is moved automatically in the direction of the conveyor belt. The player does not control his movements anymore.
17 layer x y width height direction
direction is one of the 8 directions (0 to 7).
Syntax of a door:
18 layer x y entity_name direction subtype savegame_variable
Subtypes of doors:
The sprite of a door depends on its subtype and the tileset of the map. If the door is called doorname, hen the door is closed, all dynamic tiles with the prefix doorname_closed are enabled and the ones with the prefix doorname_open are disabled. When the door is open, this is the opposite.
savegame_variable indicates the index of the boolean value that stores this door's state in the savegame. For usual closed doors (i.e. if the subtype is 0), the value may be -1: this means that the door is not saved.
Stairs allow the hero to change his floor, or to get on a platform inside the same floor.
Syntax of a stairs entity:
19 layer x y entity_name direction subtype
Subtypes of stairs:
The direction is one of the four main directions (0 to 3). However, for stairs that go to another floor, the only possible directions are north (1) and south (3).
1.7.4