Custom file formats

Urho3D tries to use existing file formats whenever possible, and define custom file formats only when absolutely necessary. Currently used custom file formats are:

binary model format (.mdl)

Model geometry and vertex morph data

byte[4]    Identifier "UMDL" or "UMD2"
uint       Number of vertex buffers

  For each vertex buffer:
  uint       Vertex count
  uint       Legacy vertex element mask (determines vertex size)
  uint       Morphable vertex range start index
  uint       Morphable vertex count
  byte[]     Vertex data (vertex count * vertex size)

  In "UMD2" format, the legacy vertex element mask is replaced with the following:
  uint       Vertex element count
  uint[]     Descriptions for each vertex element, where
             bits 0-7 = element data type, bits 8-15 = semantic, bits 16-23 = semantic index

uint    Number of index buffers

  For each index buffer:
  uint       Index count
  uint       Index size (2 for 16-bit indices, 4 for 32-bit indices)
  byte[]     Index data (index count * index size)

uint    Number of geometries

  For each geometry:
  uint       Number of bone mapping entries
  uint[]     Bone mapping data, Maps geometry bone indices to global bone indices for HW skinning.
             May be empty, in this case identity mapping will be used.
  uint       Number of LOD levels

    For each LOD level:
    float      LOD distance
    uint       Primitive type (0 = triangle list, 1 = line list)
    uint       Vertex buffer index, starting from 0
    uint       Index buffer index, starting from 0
    uint       Draw range: index start
    uint       Draw range: index count

uint    Number of vertex morphs (may be 0)

  For each vertex morph:
  cstring    Name of morph
  uint       Number of affected vertex buffers

    For each affected vertex buffer:
    uint       Vertex buffer index, starting from 0
    uint       Vertex element mask for morph data. Only positions, normals & tangents are supported.
    uint       Vertex count

      For each vertex:
      uint       Vertex index
      Vector3    Position (if included in the mask)
      Vector3    Normal (if included in the mask)
      Vector3    Tangent (if included in the mask)

Skeleton data

uint       Number of bones (may be 0)

  For each bone:
  cstring    Bone name
  uint       Parent bone index starting from 0. Same as own bone index for the root bone
  Vector3    Initial position
  Quaternion Initial rotation
  Vector3    Initial scale
  float[12]  4x3 offset matrix for skinning
  byte       Bone collision info bitmask. 1 = bounding sphere 2 = bounding box

  If bounding sphere data included:
  float      Bone radius

  If bounding box data included:
  Vector3    Bone bounding box minimum
  Vector3    Bone bounding box maximum

Bounding box data

Vector3    Model bounding box minimum
Vector3    Model bounding box maximum

Geometry center data

  For each geometry:
  Vector3    Geometry center

binary animation format (.ani)

byte[4]    Identifier "UANI"
cstring    Animation name
float      Length in seconds
uint       Number of tracks

  For each track:
  cstring    Track name (practically same as the bone name that should be driven)
  byte       Mask of included animation data. 1 = bone positions 2 = bone rotations 4 = bone scaling
  uint       Number of keyframes

    For each keyframe:
    float      Time position in seconds
    Vector3    Position (if included in data)
    Quaternion Rotation (if included in data)
    Vector3    Scale (if included in data)

Note: animations are stored using absolute bone transformations. Therefore only lerp-blending between animations is supported; additive pose modification is not.

Direct3D9 binary shader format (.vs3, .ps3)

byte[4]    Identifier "USHD"

short      Shader type (0 = vertex, 1 = pixel)
short      Shader model (3)

uint       Number of constant parameters

    For each constant parameter:
    cstring    Parameter name
    byte       Register index
    byte       Number of registers

uint       Number of texture units

    For each texture unit:
    cstring    Texture unit name
    byte       Sampler index

uint       Bytecode size
byte[]     Bytecode

Direct3D11 binary shader format (.vs4, .ps4)

byte[4]    Identifier "USHD"

short      Shader type (0 = vertex, 1 = pixel)
short      Shader model (4)
uint       Vertex element hash code (0 for pixel shaders)

uint       Number of constant parameters

    For each constant parameter:
    cstring    Parameter name
    byte       CBuffer index
    uint       Start byte offset in CBuffer
    uint       Byte size

uint       Number of texture units

    For each texture unit:
    cstring    Texture unit name
    byte       Sampler index

uint       Bytecode size
byte[]     Bytecode

Package file (.pak)

byte[4]    Identifier "UPAK" or "ULZ4" if compressed
uint       Number of file entries
uint       Whole package checksum

    For each file entry:
    cstring    Name
    uint       Start offset
    uint       Size
    uint       Checksum

    The compressed data for each file is the following, repeated until the file is done:
    ushort     Uncompressed length of block
    ushort     Compressed length of block
    byte[]     Compressed data

Compiled AngelScript (.asc)

byte[4]    Identifier "ASBC"
byte[]     Bytecode, produced by AngelScript serializer