Appendix B. XFF File Format

Table of Contents

Overview
Type Definitions
Common Header
Chunk Types
Chunk Format Definitions
Group
Geometry
Mesh
Camera
Light
Helper
Particle System
Sprite
Sound Source
Microphone
Collider
Vertex Buffer
Face List
Triangle Info Buffer
Material
Texture
PRS Animation Group
Loader
Spring
Node attribute

Overview

The XFF file format is the X-Forge default format for 3D content. It is designed to be extensible to support, among other things, new user defined custom game graph nodes.

The XFF format consists of chunks of data, each having a 12 byte header that presents the type of chunk, the version of the chunk, a chunk ID and a block length. The block length describes the length of the data that follows after the header. Roughly speaking, each chunk corresponds to a node in the game graph that the file describes.

Type Definitions

INT8    8-bit signed integer (1 byte)
UINT8   8-bit unsigned integer (1 byte)
INT16   16-bit signed integer (2 bytes)
UINT16  16-bit unsigned integer (2 bytes)
INT32   32-bit signed integer (4 bytes)
UINT32  32-bit unsigned integer (4 bytes)
CHAR8   8-bit character (1 byte)
Float   Standard IEEE single-precision floating point number (4 bytes)
        (sign bit, 8-bit exponent, 23-bit mantissa = 32 bits)

Vector3 3 Floats = x,y,z (12 bytes)
Quat    4 Floats = x,y,z,w (16 bytes)

All basic type values are stored in little endian (LE) byte order.

Common Header

Every chunk in the file has the common header described below.

  2 bytes   UINT16  Chunk type
  2 bytes   UINT16  Chunk type version
  4 bytes   UINT32  Id
  4 bytes   UINT32  Block length

|2 byt|2 byt|   4 byt   |   4 byt   | BlockLength * bytes |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--   ...     --+--+
|Type |Ver  |Id         |BlockLength| Data Data Data Data |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--   ...     --+--+

Chunk Types

   1 = Not used
   2 = Group
   3 = Geometry
   4 = Mesh
   5 = Camera
   6 = Light
   7 = Helper
   8 = Particle system
   9 = Sprite
  10 = Sound source
  11 = Microphone
  12 = Collider
1001 = Vertex buffer
1002 = Face list
1003 = Material
1004 = Texture
1005 = PRS animation group
1006 = Loader
1007 = Spring
1008 = Triangle info buffer
1009 = Node attribute

Chunk Format Definitions

Group

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
   12 bytes     Vector3 Scale

Geometry

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
   12 bytes     Vector3 Scale

Mesh

Version 1:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    2 byte      UINT16  Sub mesh count (n)
n*( 4 bytes     UINT32  Vertex buffer id
    4 bytes     UINT32  Face list id       (max UINT32 if not indexed)
    4 bytes     UINT32  Material id
    4 bytes     UINT32  Diffuse texture id (max UINT32 if no texture)
    4 bytes     UINT32  Vertex offset
    4 bytes     UINT32  Vertex count
    1 byte )    UINT8   Primitive type (see below)

Version 2:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    2 byte      UINT16  Sub mesh count (n)
n*( 4 bytes     UINT32  Vertex buffer id
    4 bytes     UINT32  Face list id            (max UINT32 if not indexed)
    4 bytes     UINT32  Triangle info buffer id (max UINT32 if not used)
    4 bytes     UINT32  Material id
    4 bytes     UINT32  Diffuse texture id      (max UINT32 if no texture)
    4 bytes     UINT32  Vertex offset
    4 bytes     UINT32  Vertex count
    1 byte )    UINT8   Primitive type (see below)

Version 3:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    2 byte      UINT16  Sub mesh count (n)
n*( 4 bytes     UINT32  Vertex buffer id
    4 bytes     UINT32  Face list id            (max UINT32 if not indexed)
    4 bytes     UINT32  Triangle info buffer id (max UINT32 if not used)
    4 bytes     UINT32  Material id
    4 bytes     UINT32  Diffuse texture id      (max UINT32 if no texture)
    4 bytes     UINT32  Reflection map id       (max UINT32 if no map)
    4 bytes     UINT32  Vertex offset
    4 bytes     UINT32  Vertex count
    1 byte )    UINT8   Primitive type (see below)


Primitive types:
    Type                Value
    triangle list       1
    triangle strip      2
    triangle fan        3

Camera

   12 bytes             Header
    4 bytes     UINT32  Parent id
    4 bytes     UINT32  Target id (max UINT32 if not lookat)
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
    4 bytes     Float   Field of view (FOV)
    4 bytes     Float   Near clipping plane
    4 bytes     Float   Far clipping plane

Light

Version 1:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
    1 byte      UINT8   Light type (see below)
    4 bytes     UINT32  Diffuse color (0RGB)
    4 bytes     Float   Multiplier
    4 bytes     Float   Attenuation square
    4 bytes     Float   Range
    4 bytes     Float   Hotspot Angle
    4 bytes     Float   Falloff Angle

Version 2:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
    1 byte      UINT8   Light type (see below)
    4 bytes     UINT32  Diffuse color (0RGB)
    4 bytes     Float   Multiplier
    4 bytes     Float   Attenuation constant
    4 bytes     Float   Attenuation linear
    4 bytes     Float   Attenuation square
    4 bytes     Float   Range
    4 bytes     Float   Hotspot Angle
    4 bytes     Float   Falloff Angle

Light types:
    Type                Value
    point light         1
    directional light   2
    spot light          3

Helper

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position

Particle System

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    4 bytes     FLOAT32 Size scale
    1 byte      UINT8   Filename length
    n bytes     CHAR8   Filename

Sprite

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    4 bytes     Float   Width
    4 bytes     Float   Height
    1 byte      UINT8   Texture filename length
    n bytes     CHAR8   Texture filename
    1 byte      UINT8   Type
    1 byte      UINT8   Source blend; see XFCGLBLENDMODES
    1 byte      UINT8   Target blend; see XFCGLBLENDMODES
    4 bytes     UINT32  Color (ARGB)

Sprite types:
    Type            Value
    3D              1
    3D billboard    2

Sound Source

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
    1 byte      UINT8   Sound Source type (see below)
    4 bytes     Float   Multiplier
    4 bytes     Float   Attenuation start range
    4 bytes     Float   Attenuation end range
    1 byte      UINT8   Looping 
    1 byte      UINT8   Filename length
    n bytes     CHAR8   Filename

Sound source types:
    Type                Value
    omnidirectional     1
    directional         2

Microphone

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
    1 byte      UINT8   Microphone type (see below)
    4 bytes     Float   Multiplier
    4 bytes     Float   Range

Microphone types:
    Type                Value
    omnidirectional     1
    directional         2

Collider

   12 bytes             Header
    4 bytes     UINT32  Parent id
    2 bytes     UINT16  Collider type
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name

        Collider types:

        Type                          Value
        bounding volume                   1
        point                             2
        plane                             3
        heightfield                       4
        bounding volume from geometry   101
	

    Rest of the data depends on the collider type:

        Bounding volume:

    1 bytes     UINT8   Bounding volume type
   12 bytes     Vector3 Minimum
   12 bytes     Vector3 Maximum
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
   12 bytes     Vector3 Scale

        Bounding volume type can be
        Type                Value
        Sphere              1
        FastSphere          2
        Box                 3
        LocalBox            4

        For spherical types the center is the mid-point of minimum and
        maximum, and radius is the longest axis (NOT the diagonal of the box!)

        Bounding volume from geometry:

    1 bytes     UINT8   Bounding volume type
    4 bytes     UINT32  Geometry id

        Heightfield volume:

   12 bytes     Vector3 Minimum
   12 bytes     Vector3 Maximum
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
   12 bytes     Vector3 Scale
    4 bytes      UINT32  Construction start node id
    2 bytes      UINT16  Width of data
    2 bytes      UINT16  Height of data
    1 byte       UINT8   Base level
    1 byte       UINT8   Flags (see below)

        Flags:
    only static               2
    only contacting           4
    only contained polygons   8
    only same partent type    16

Vertex Buffer

   12 bytes             Header
    4 bytes     UINT32  Vertex buffer flags (see below)
    2 bytes     UINT16  Size of one vertex in bytes (m)
    4 bytes     UINT32  Number of vertices (n)
n*(12 bytes     Vector3 Position
   12 bytes     Vector3 Normal (present only with normals flag)
    4 bytes     UINT32  Diffuse Color (0RGB) (only with diffuse color flag)
    4 bytes     Float   U coordinate (only with u,v coords. flag)
    4 bytes)    Float   V coordinate (only with u,v coords. flag)

Vertex buffer flags:
    Type                Bitmask
    normals             0x0001
    diffuse color       0x0002
    u,v coords.         0x0004

Face List

Version 1:

   12 bytes             Header
    2 bytes     UINT16  Number of faces (n)
n*( 2 bytes     UINT16  1st vertex index
    2 bytes     UINT16  2nd vertex index
    2 bytes     UINT16  3rd vertex index)

Version 2:

   12 bytes             Header
    2 bytes     UINT16  Number of indexes (n)
n*( 2 bytes     UINT16  vertex index )

Triangle Info Buffer

   12 bytes             Header
    2 bytes     UINT16  Number of triangles (n)
    4 bytes     UINT32  Triangle info buffer flags (see below)
n*( 4 bytes     UINT32  Diffuse Color for corner 1 (only with diffuse color flag)
    4 bytes     UINT32  Diffuse Color for corner 2 (only with diffuse color flag)
    4 bytes     UINT32  Diffuse Color for corner 3 (only with diffuse color flag)
   12 bytes     Vector3 Normal (only with normals flag)
    4 bytes     Float   U coordinate for corner 1 (only with u,v coords. flag)
    4 bytes     Float   V coordinate for corner 1 (only with u,v coords. flag)
    4 bytes     Float   U coordinate for corner 2 (only with u,v coords. flag)
    4 bytes     Float   V coordinate for corner 2 (only with u,v coords. flag)
    4 bytes     Float   U coordinate for corner 3 (only with u,v coords. flag)
    4 bytes)    Float   V coordinate for corner 3 (only with u,v coords. flag)

Triangle info buffer flags:
    Type                Bitmask
    diffuse color       0x0001
    normal              0x0002
    u,v coords.         0x0004

Material

Version 1:

   12 bytes             Header
    4 bytes     UINT32  Diffuse color (0RGB)
    4 bytes     UINT32  Specular color (0RGB)
    4 bytes     UINT32  Ambient color (0RGB)
    4 bytes     UINT32  Emissive color (0RGB)
    4 bytes     Float   Specular exponent
    4 bytes     UINT32  Material flags (see below)
    4 bytes     UINT32  Shading mode; see XFCGLSHADINGMODES
    1 byte      UINT8   Source blend; see XFCGLBLENDMODES
    1 byte      UINT8   Target blend; see XFCGLBLENDMODES

Version 2:

   12 bytes             Header
    4 bytes     UINT32  Diffuse color (0RGB)
    4 bytes     UINT32  Specular color (0RGB)
    4 bytes     UINT32  Ambient color (0RGB)
    4 bytes     UINT32  Emissive color (0RGB)
    4 bytes     Float   Specular exponent
    4 bytes     UINT32  Material flags (see below)
    4 bytes     UINT32  Shading mode; see XFCGLSHADINGMODES
    1 byte      UINT8   Source blend; see XFCGLBLENDMODES
    1 byte      UINT8   Target blend; see XFCGLBLENDMODES
    4 bytes     Float   Polygon offset (for sorting)

Material flags:
    Type                        Bitmask
    alpha blending              0x0001
    perspective correction      0x0002
    wireframe mode              0x0004
    double sided                0x0008

Texture

   12 bytes             Header
    1 byte      UINT8   Filename length
    n bytes     CHAR8   Filename

PRS Animation Group

Version 1:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    4 bytes     UINT32  First frame = StartTime/DeltaTime
    4 bytes     UINT32  Last frame = EndTime/DeltaTime
    4 bytes     UINT32  Frame rate - frames per second
    4 bytes     UINT32  Delta time - ticks per frame
    2 bytes     UINT16  Sample rate
    1 byte      UINT8   Animation type (see below)
    2 bytes     UINT16  Frame count (n)
n*(12 bytes     Vector3 Position
   16 bytes     Quat    Rotation (if animation type is PRS or PR)
   12 bytes)    Vector3 Scale (only if animation type is PRS)

Animation types:
    Type                            Value
    PR = position, rotation           1
    PRS = position, rotation, scale   2
    P = position                      3

Version 2:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    2 bytes     UINT16  Sequence count (n)
n*( 4 bytes     INT32   Start time (ms) (sample data start at time 0)
    4 bytes     INT32   End time (ms)
    4 bytes     FLOAT32 Sample rate (samples / sec)
    2 bytes     UINT16  Animation flags (see below)
    4 bytes     UINT32  Sample count (m)
m*(12 bytes     Vector3 Position (only if position animation flag)
   16 bytes     Quat    Rotation (only if rotation animation flag)
   12 bytes)    Vector3 Scale (only if scale animation flag)
  ))

Version 3:

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
    2 bytes     UINT16  Sequence count (n)
n*( 4 bytes     INT32   Start time (ms) (sample data start at time 0)
    4 bytes     INT32   End time (ms)
    4 bytes     FLOAT32 Sample rate (samples / sec)
    2 bytes     UINT16  Animation flags (see below)
    12 bytes    Vector3 Default Position (only if not position animation flag)
    16 bytes    Quat    Default Rotation (only if not rotation animation flag)
    12 bytes    Vector3 Default Scale (only if not scale animation flag)
    4 bytes     UINT32  Sample count (m)
m*(12 bytes     Vector3 Position (only if position animation flag)
   16 bytes     Quat    Rotation (only if rotation animation flag)
   12 bytes)    Vector3 Scale (only if scale animation flag)
  ))


Animation flags:
    Type                        Bitmask
    looping                     0x0001
    position                    0x0002
    rotation                    0x0004
    scale                       0x0008 

Loader

   12 bytes             Header
    4 bytes     UINT32  Parent id
    1 byte      UINT8   Name length (n)
    n bytes     CHAR8   Name
   12 bytes     Vector3 Position
   16 bytes     Quat    Rotation
   12 bytes     Vector3 Scale
    1 byte      UINT8   File name length (n)
    n bytes     CHAR8   File name to load
    1 byte      UINT8   merge mode

Merge modes:

    0 = replace loader with scene root and give scene root the transformation
        that the loader had

  foo                foo
    \                  \
     LD + root   =>    root
          / | \       / | \

    1 = move all child nodes of the scene root to the parent of the loader
        and remove both loader and scene root

  foo
    \
     LD + root   =>    foo
          / | \       / | \

Spring

Version 1:

   12 bytes             Header
    4 bytes     UINT32  1st parent id
    4 bytes     UINT32  2nd parent id
    4 bytes     Float   Spring constant
    4 bytes     Float   Damping factor
    4 bytes     Float   Length (-1 = distance between parents)

Version 2:

   12 bytes             Header
    4 bytes     UINT32  1st parent id
    4 bytes     UINT32  2nd parent id
    4 bytes     Float   Spring constant
    4 bytes     Float   Damping factor
    4 bytes     Float   Length (-1 = distance between parents)
    4 bytes     Float   Minimum length scale (0.0 = not used)
    4 bytes     Float   Maximum length scale (0.0 = not used)

Node attribute

   12 bytes             Header
    4 bytes     UINT32  Parent id
    4 bytes     UINT32  Data length
    n bytes     UINT8   Data