From FIFE development wiki

Contents 1 Introduction 2 Map File Structure 2.1 Example 3 map 4 layer 5 Object File Structure 5.1 Example 6 object 6.1 action 6.2 Example 7 Animation File Structure 7.1 Example

[edit] Introduction

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

[edit] 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:

[edit] 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>

[edit] map

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

Only one map can be declared in a file.

• attributes
  • • id: The identifier for this map. Type = string
    • format: XML format version. Type = float
• import: Imported files. In particular, object files. See object section for more details
  • • file: Path to file to load. Relative to dir if specified; otherwise relative to this map file. Type = string
    • dir: Path to directory, relative to this map file. If file isn't specified, all importable files under this directory are loaded. Type = string
• layers: A map consists of layers. E.g. there could be two layers for the ground of the map: one layer for grass and other one for people. Maybe a third layer could be added for clouds. Order of layer declaration determines draw order, so declare lower layers first.

[edit] layer

Layer is always embedded into a map declaration. Layers determine the drawing order of objects (lower layer is drawn before 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. Higher stuff like airplanes and clouds should exist in a third layer.

Three layers (ground, object, air) should usually be enough, although more creative usage of layers will surely occur.

• 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. 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

[edit] Object File Structure

Object files begin with an object header: <?fife type="object"?>. After this, the object is defined between a set of <object></object> tags. Only one object may be declared per file. The components of the <object> section and its subsections are explained in the following sections of this page. Here is an example definition of an object file:

[edit] Example

 <?fife type="object"?>
 <object id="MyObject" namespace="MyObjectCollection" blocking="1" static="0">
     <image source="Source image path" direction='0' />
     
     <action id="MyObjectAction">
       <animation source="Animation file path for east facing." direction="0" />
       <animation source="Animation file path for west facing" direction="180" />
     </action>
   </object>
 </dataset>

[edit] object

• attributes
  • id: The identifier for this map. Type = string
  • parent: Identifier of the parent object. Type = string. Optional.
  • namespace : Namespace of the object. Type = string. Required.
  • blocking: Defines if object blocks the movement. Type = bool (0/1). Optional, default = 0
  • static: Defines if object does not move (ever). Used to optimize pathfinding. Type = bool (0/1). Optional, default = 0
  • pather: Defines which path finder object should used. If none defined, uses engine default. Type = string. Optional
    • Currently supported pathers = "LinearPather" and "RoutePather"
• action: See action section
• image
  • source: Location of the image in the filesystem. Type = string
  • direction: Direction where this image is pointing to (i.e. facing direction if there is such). Type = int
  • x_offset: X offset for image. Type = int, Optional
  • y_offset: Y offset for image. Type = int, Optional

[edit] action

An action is always embedded in an <object> section of a dataset

• attributes
  • id: The identifier for this action. Type = string
• animation For animation file definitions, see animation section
  • source
  • direction

[edit] Example

 <action id="walk">
   <animation source="Source animation xml file for east." direction="0" />
   <animation source="Source animation xml file for north." direction="90" />
   <animation source="Source animation xml file for west." direction="180" />
   <animation source="Source animation xml file for south." direction="270" />
 </action>

[edit] Animation File Structure

Animations defines how images are shown in a sequence.

• attributes
  • delay: common delay for all the frames in this animation. Type = int
  • action: action frame number (e.g. point when punch hits the target in punch animation). Type = int
  • x_offset: common x offset in pixels for all frames. Type = int
  • y_offset: common y offset in pixels for all frames. Type = int
• frame
  • source: path to image. Type = string
  • delay: frame specific delay, overrides common delay (for this frame). Type = int
  • x_offset: frame specific x offset in pixels, overrides common x_offset (for this frame). Type = int
  • y_offset: frame specific y offset in pixels, overrides common y_offset (for this frame). Type = int

[edit] Example

 <animation delay="130">
   <frame source="image1.jpg">
   <frame source="image2.jpg">
   <frame source="image3.jpg">
 </animation