Map Format

From FIFE development wiki
Jump to: navigation, search
wiki
Document Data structures Data strucures
Concepts illustrated here are relevant to understand what kind of data FIFE engine is able to process.

Introduction

The purpose of this page is to explain the FIFE XML map format in full, with all the elements and their attributes fleshed out.

Map File Structure

Map files begin with the standard xml header: <?xml version="1.0">. After this, the map is then defined between a set of <map></map> tags. Only one map may be declared in a single map file. The components of the <map> section and its subsections are explained in the following sections of this page. Here is an example definition of a map file:

Example

  <?xml version="1.0">
  <map id="MyMapName" format="1.0">
    <import dir="./objects/" />
    <import file="./other_objects/my_object.xml" />
 
    <layer id="Layer on this map" grid_type="square" x_scale="1.0" y_scale="1.0" rotation="0.0">
      <instances>
        <i o="Some object id" ns="The namespace of the object" x="25.0" y="10.0" r="0" />
      </instances>
    </layer>
  </map>

map

The map section is the main entry point for map definitions. The map section cannot be embedded to other sections, nor is it referred to from any other section. The map in its entirety is a single game level consisting of layers.

Only one map can be declared in a file.

  • attributes
    • id: The unique identifier for this map. Note this must be unique across maps. Type = string
    • format: XML format version. Type = float
  • import:Specifies files and/or directories for game assets to load.
    • dir: Path to a game asset directory, specified relative to map file location. If no file attribute is present then all game asset files in this directory and any sub-directories are loaded recursively. Type = string
    • file: filename of a game asset to load. This is relative to the dir attribute value if present, otherwise this should be relative to the map file location. Type = string
  • layer: Specifies a description for a single layer in the map. Note a map can contain several layers each with their own XML description. The order in which layers are declared in the map file determines their draw order, so lower layers should be declared first. Please refer to the layer section for a more in depth description.

layer

Layer is always embedded into a map declaration. Layers determine the drawing order of objects (lower layer is drawn before the higher layer). As a rule of thumb, objects that interact with each other should be placed in the same layer.

For example, players and buildings are at the same general height (for example, a player can move behind a building, or go inside it) and so should exist on the same layer. "Tiles" for ground and water generally are under the player, so they can go in a lower layer. Anything higher than ground elevation, such as clouds, should be placed in a layer declared after the ground layer to ensure the draw order is correct.

  • attributes
    • id: The identifier for this map. Type = string
    • grid_type: The type of geometry grid used on this layer. Type = string. Current options are "square" and "hexagonal".
    • pathing: Type of pathing used in this layer. Possible values = "cell_edges_only", "cell_edges_and_diagonals", "freeform". Supported values depend on pather implementation that is tied to the moving object, Type = string.
      • "cell_edges_only" results pather to use only cell edges when moving instances from cell to cell on map
      • "cell_edges_and_diagonals" results pather to use both cell edges and diagonals when moving instances from cell to cell on map
      • "freeform" finds shortest route regardless of cellgrid used on the layer
    • x_scale: The x-axis scale of this layer relative to other layers on this map. Defaults to 1.0. Type = float
    • y_scale: The y-axis scale of this layer relative to other layers on this map. Defaults to 1.0. Type = float
    • rotation: The angle of rotation of this layer. Defaults to 0.0. Type = float
    • x_offset: X offset for this layer. Useful for e.g. roof layer. Defaults to 0.0. Type = float
    • y_offset: Y offset for this layer. Useful for e.g. roof layer. Defaults to 0.0. Type = float
    • transparency: Transparency value for the layer. Defaults to 0 (opaque). Max value is 255 (transparent).
  • instances: Instances residing in this layer
    • instance: Instance definition. Instances instantiate Objects. Abbreviated as "i".
      • object: The identifier of the object to instantiate. Abbreviated as "o". Type = string
      • id: Optional id for instance, can be used to refer to instances from script. Type = string
      • ns: The namespace the object is defined with. Required. Omission will result in the inheritance of the namespace value of the nearest prior namespace declaration. Corresponds to the namespace declared in the object file and any animation file for this instance. See the examples below. Type = string
      • x: Starting position of this object on map x-axis. Optional; omission will result x value of (previous declaration's x) + 1. Type = int
      • y: Starting position of this object on map y-axis. Optional; omission will result y value equal to that of the previous declaration. Type = float
      • z: Starting position of this object on map z-axis. Optional; omission will result z value 0. Type = float
      • r: Rotation of this instance. Optional; omission will result r value 0. Type = float
      • stackpos: Stack position for this object. Affects drawing order inside the layer. Basically instances on exactly the same location will be drawn according to stack position. Instances with higher values get drawn after ones with lower values. Optional; default is 0. Type = int   
        ♦ Note: Until the next release beyond 0.3.1, Please compile and use version 0.3.1.3426 or later from the trunk, as these later    versions will insure retention of any manual stackpos attribute/value pairs you may have added to the map.
          ♦ Tools and modules affected: editor - (FIFEdit), fife.extensions.savers.py.

Example

  <instances>
    <i o="some_object" ns="http://adomain.tv/xml/default" x="5.0" y="2.0" r="0" />
    <i o="another_object" x="6.0" y="3.0" r="0" />
    <i id="active_obj1" o="some_obj" ns="http://adomain.tv/xml/obj_class1" x="9.0" y="5.0" r="0" />
    <i id="active_obj2" o="some_obj2" ns="http://adomain.tv/xml/obj_class2" x="2.0" y="9.0" r="0" />
    <i id="active_obj3" o="some_obj3" ns="http://adomain.tv/xml/obj_class2" x="3.0" y="7.0" r="0" />
  </instances>

Notes:

  1. another_object inherits the ns="http://adomain.tv/xml/default" from the some_object instance.
  2. Consider the fact that active_obj1 and (active_obj2, active_obj3) have differing namespaces.

Possible use: Facilitate identification of custom object constructs such as "Collections" or "Asset Classes" in your application code.