Object format

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


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

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:


  <?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" />


  • attributes
    • id: The identifier for this object. 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


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 format
    • source
    • direction


  <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" />

Animated spritesheet

Since FIFE 0.3.3 there's a new format called Animated spritesheet supported. Suppose you have object definition:

 <?fife type="object"?>
 <object id="hunter" namespace="units" static="0" blocking="1" >
   <action id="move_full">
     <animation source="move_full/0/animation.xml" direction="0" />
     <animation source="move_full/45/animation.xml" direction="45" />
     <animation source="move_full/90/animation.xml" direction="90" />
     <animation source="move_full/135/animation.xml" direction="135" />
     <animation source="move_full/180/animation.xml" direction="180" />
     <animation source="move_full/225/animation.xml" direction="225" />
     <animation source="move_full/270/animation.xml" direction="270" />
     <animation source="move_full/315/animation.xml" direction="315" />

One of the animation.xml file could look like this:

 <animation delay="200" namespace="units" id="hunter:move_full:0">
   <frame source="0001.png"/>
   <frame source="0002.png"/>
   <frame source="0003.png"/>
   <frame source="0004.png"/>

Now, with the old format, you needed to create one object xml file and eight animation xml files plus each of the frame was a separate image file. In total you needed 8*4+8+1=41 files to describe an object. That's a lot. With a new syntax you only need one object xml file and one .png image file for every action:

 <?fife type="object"?>
 <object blocking="1" id="hunter" namespace="units" static="0">
   <action id="move_full">
     <animation atlas="move_full.png" height="42" width="42">
       <direction delay="200" dir="0" frames="4"/>
       <direction delay="200" dir="45" frames="4"/>
       <direction delay="200" dir="90" frames="4"/>
       <direction delay="200" dir="135" frames="4"/>
       <direction delay="200" dir="180" frames="4"/>
       <direction delay="200" dir="225" frames="4"/>
       <direction delay="200" dir="270" frames="4"/>
       <direction delay="200" dir="315" frames="4"/>

Each of the row consists of animation for specific direction with consecutive frames. The only requirement is that every frame is the same size.

Corresponding animated spritesheet looks like this:

Example of animated spritesheet

In order to quickly convert all your animated files FIFE provides a simple conversion tool in tools/pack_anim.py.