## Appendix B. XFF File Format

## 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

    Version 1:

       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)

    Version 2:

       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)
        4 bytes     Float   Polygon offset (for sorting)

    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

|  | X-Forge Documentation Confidential Copyright © 2003 Fathammer