PlayStation(R)Mobile MDX File Format

PlayStation(R)Mobile MDX file format is a file format which contains a model data.

MDX File Format

Model Data

MDX file can contain a model data with the following functions.

  • Hierarchical node (Transformation, Visibility, Skinning)
  • Shape data (Points, Lines, Triangles)
  • Vertex data (Position, Normal, Color, UV, Weights, Indices)
  • Material settings (Legacy material)
  • Texture mapping (Single layer)
  • Texture image (DDS, PNG, JPG, BMP, GIF)
  • Animation (Transformation, Material, UV)

The default settings of the model data are as follows.

  • 3D coordinate : Right-handed system (Y = up)
  • UV coordinate : Upper-left origin
  • Matrix order : Column-major
  • Face culling : CCW is front face
  • Normal vector : Front face direction

Block Structure

MDX file is structured as hierarchical blocks as follows.

File            // File body (only in binary format)
  Model         // Model body
    Bone        // Hierarchical node
    Part        // Shape data
      Mesh      // Drawing mesh
      Arrays    // Vertex data
    Material    // Material settings
      Layer     // Texture mapping
    Texture     // Texture image
    Motion      // Animation set
      FCurve    // Animation curve

Below is an example of a simple model data in text format.

.MDS 1.00

Model "model-0" {
    Bone "bone-0" {
        Translate 0.000000 0.000000 0.000000
        RotateYXZ 0.000000 0.000000 0.000000
        DrawPart "part-0"
    }
    Part "part-0" {
        Mesh "mesh-0" {
            SetMaterial "material-0"
            SetArrays "arrays-0"
            DrawArrays TRIANGLES 3 1 0 1 2
        }
        Arrays "arrays-0" POSITION|NORMAL 0 3 {
            0.000000 0.577350 0.000000 0.000000 0.000000 1.000000
            -0.500000 -0.288675 0.000000 0.000000 0.000000 1.000000
            0.500000 -0.288675 0.000000 0.000000 0.000000 1.000000
        }
    }
    Material "material-0" {
        Diffuse 0.000000 0.000000 1.000000
        Specular 1.000000 1.000000 1.000000
        Opacity 1.000000
        Shininess 10.000000
    }
}

Syntax

MDX file is described by the combination of a header, blocks, and commands,

FormatSignature $version

BlockType $name $arg1 $arg2 ... {
    CommandType $arg1 $arg2 ...
    CommandType $arg1 $arg2 ...

    BlockType $name $arg1 $arg2 ... {
        CommandType $arg1 $arg2 ...
        CommandType $arg1 $arg2 ...
    }

    BlockType $name $arg1 $arg2 ... {
        $data0 $data1 $data2 ...
    }
}
Header
Header represents the file format. Format signature and version number are described.
Block
Block represents a group of data set. Block type, name, and arguments are described. Multiple commands and multiple blocks can be contained as the child elements of the block. Additionally, an array of simple values can be contained as the block data.
Command
Command represents a simple data. Command type and arguments are described.

The types of the elements of command arguments, block arguments, and block data are as follows.

Type Data Example 1 Example 2
ref Reference to a block "bone-0" "Bone::bone-0" (with block type)
enum Enumeration constant POSITION POSITION|NORMAL (logical or)
string 8bit zero-terminated string "texture.png"  
float 32bit floating point number 10.0  
half 16bit floating point number 10.0  
int 32bit signed integer 10  
uint 32bit unsigned integer 10  
short 16bit signed integer 10  
ushort 16bit unsigned integer 10  
byte 8bit signed integer 10  
ubyte 8bit unsigned integer 10  

Text Format

In text format, model data is stored in text expression.

  • The extension of filename is ".MDS".
  • The format signature is ".MDS"
  • The size of a character is 8bit.
  • File block is omitted.
  • Vertex stride in arrays block is 0.

Binary Format

In binary format, model data is stored in binary expression.

  • The extension of filename is ".MDX".
  • The format signature is ".MDX"
  • The byte order is little endian.
  • File block is output.
  • Vertex stride in arrays block is a calculated value.

Header, blocks, and commands are stored in the following structures.

struct MdxHeader {
    uint Signature ;        // Format signature ( 0x2e4d4458 )
    uint Version ;          // Format version   ( 0x312e3030 )
    uint Style ;            // Format style     ( 0x0050534d )
    uint Option ;           // Format option    ( 0x00000000 )
}

struct MdxBlock {
    ushort Type ;           // Block type
    ushort NameEnd ;        // End position of the block name
    uint ArgsEnd ;          // End position of the block argument
    uint DataEnd ;          // End position of the block data
    uint ChildEnd ;         // End position of the child elements

    // Block name
    // Block arguments
    // Block data
    // Child elements
}

struct MdxCommand {
    ushort Type ;           // Command type | 0x8000
    ushort ArgsEnd ;        // End position of the command arguments

    // Command arguments
}
  • The positions of the structure and its elements are aligned in 4 bytes.
  • The start position of an element can be calculated from the end position of the element just before it.
  • The end position of an element is stored in the structure as the offset from the top of the structure.

The positions of the values contained in the command arguments, block arguments, and block data are aligned in the size of each data type. Reference to a block is stored as the following bitfield value.

struct MdxReference {
    uint Bits ;

    // Type of the block
    int Type { get { return (int)( Bits >> 16 ) & 0xffff ; } }
    // Relative level of the block
    int Level { get { return (int)( Bits >> 12 ) & 0x000f ; } }
    // Block number in the blocks of the same type in the same tier.
    int Index { get { return (int)( Bits >> 0 ) & 0x0fff ; } }
}

Blocks

File

[Summary]

    Block representing a file body

[Syntax]

    File $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    Model

Model

[Summary]

    Block representing a model body

[Syntax]

    Model $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    BoundingBox
    BoundingSphere
    Bone                        (can appear multiple time)
    Part                        (can appear multiple time)
    Material                    (can appear multiple time)
    Texture                     (can appear multiple time)
    Motion                      (can appear multiple time)

Bone

[Summary]

    Block representing a hierarchical node

[Syntax]

    Bone $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    BoundingBox
    BoundingSphere
    ParentBone
    Visibility
    Pivot
    Translate
    Rotate*
    Scale
    BlendBone                   (can appear multiple time)
    DrawPart                    (can appear multiple time)

Part

[Summary]

    Block representing a shape data

[Syntax]

    Part $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    BoundingBox
    BoundingSphere
    Mesh                        (can appear multiple time)
    Arrays                      (can appear multiple time)

Mesh

[Summary]

    Block representing a drawing mesh

[Syntax]

    Mesh $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    BoundingBox
    BoundingSphere
    SetMaterial
    SetArrays
    BlendIndices
    DrawArrays                  (can appear multiple time)

Arrays

[Summary]

    Block representing a vertex data

[Syntax]

    Arrays $name $format $stride $count {
        ...
    }

[Arguments]

    string $name                Block name
    enum VertexFormat $format   Vertex format
    int $stride                 Vertex stride
    int $count                  Vertex count

[Data]

    Vertex data is structured as (data of one vertex x vertex count).
    ------------------------------------------------
    Position Normal Color TexCoord Weights Indices  // Data for one vertex
    Position Normal Color TexCoord Weights Indices  // Data for one vertex
    Position Normal Color TexCoord Weights Indices  // Data for one vertex
    ...
    ------------------------------------------------

    The content of vertex data is defined by logical-or of vertex formats.

    Vertex formats and corresponding vertex elements are as follows
    ------------------------------------------------
    POSITION    float x 3   Position coordinate
    NORMAL      float x 3   Normal vector
    COLOR       float x 4   Vertex color
    TEXCOORD    float x 2   Texture coordinate
    WEIGHTn     float x n   Blend weights
    INDICES     ubyte x n   Blend indices
    ------------------------------------------------

Material

[Summary]

    Block representing a material settings

[Syntax]

    Material $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    Diffuse
    Ambient
    Specular
    Emission
    Opacity
    Shininess
    Layer                       (can appear multiple time)

Layer

[Summary]

    Block representing a texture mapping

[Syntax]

    Layer $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    SetTexture

Texture

[Summary]

    Block representing a texture image

[Syntax]

    Texture $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    FileName
    FileImage
    UVTranslate
    UVScale

Motion

[Summary]

    Block representing an animation set

[Syntax]

    Motion $name {
        ...
    }

[Arguments]

    string $name                Block name

[Elements]

    FrameLoop
    FrameRate
    FrameRepeat
    Animate                     (can appear multiple time)
    FCurve                      (can appear multiple time)

FCurve

[Summary]

    Block representing an animation curve

[Syntax]

    FCurve $name $interp $extrap $dimCount $keyCount {
        ...
    }

[Arguments]

    string $name                Block name
    enum InterpType $interp     Interpolation type
    enum ExtrapType $extrap     Extrapolation type
    int $dimCount               Dimension count
    int $keyCount               Key-frame count

[Data]

    Animation curve is structured as (data of one key-frame x key-frame count).

    Basically, frame and key value are stored in one key-frame. The count of elements is (dimension count + 1).
    ------------------------------------------------
    Frame Values[n]  // Data for one key-frame
    Frame Values[n]  // Data for one key-frame
    Frame Values[n]  // Data for one key-frame
    ...
    ------------------------------------------------

    If the interpolation type is HERMITE, Y components of the tangent vectors are also stored in it. The element count is (dimension count * 3 + 1).
    ------------------------------------------------
    Frame Values[n] InTangentY[n] OutTangentY[n]
    Frame Values[n] InTangentY[n] OutTangentY[n]
    Frame Values[n] InTangentY[n] OutTangentY[n]
    ...
    ------------------------------------------------

    If the interpolation type is CUBIC, X components of the tangent vectors are also stored in it. The element count is (dimension count * 5 + 1).
    ------------------------------------------------
    Frame Values[n] InTangentY[n] OutTangentY[n] InTangentX[n] OutTangentX[n]
    Frame Values[n] InTangentY[n] OutTangentY[n] InTangentX[n] OutTangentX[n]
    Frame Values[n] InTangentY[n] OutTangentY[n] InTangentX[n] OutTangentX[n]
    ...
    ------------------------------------------------

Common Commands

FileName

[Summary]

    Filename

[Syntax]

    FileName $name

[Arguments]

    string $name                Filename

FileImage

[Summary]

    File image

[Syntax]

    FileImage $size $data ...

[Arguments]

    uint $size                  Size (unit = byte)
    uint $data ...              Data (every 32bit)

BoundingBox

[Summary]

    Bounding box

[Syntax]

    BoundingBox $minX $minY $minZ $maxX $maxY $maxZ

[Arguments]

    float $minX                 Minimum X
    float $minY                 Minimum Y
    float $minZ                 Minimum Z
    float $maxX                 Maximum X
    float $maxY                 Maximum Y
    float $maxZ                 Maximum Z

BoundingSphere

[Summary]

    Bounding sphere

[Syntax]

    BoundingSphere $centerX $centerY $centerZ $radius

[Arguments]

    float $centerX              Center X
    float $centerY              Center Y
    float $centerZ              Center Z
    float $radius               Radius

Bone Commands

ParentBone

[Summary]

    Parent bone

[Syntax]

    ParentBone $bone

[Arguments]

    ref Bone $bone              Reference to the parent bone

Visibility

[Summary]

    Visibility

[Syntax]

    Visibility $visibility

[Arguments]

    uint $visibility            Visibility

Pivot

[Summary]

    Pivot

[Syntax]

    Pivot $x $y $z

[Arguments]

    float $x                    X
    float $y                    Y
    float $z                    Z

Translate

[Summary]

    Translation

[Syntax]

    Translate $x $y $z

[Arguments]

    float $x                    X
    float $y                    Y
    float $z                    Z

Rotate

[Summary]

    Rotation (quaternion)

[Syntax]

    Rotate $x $y $z $w

[Arguments]

    float $x                    X
    float $y                    Y
    float $z                    Z
    float $w                    W

RotateXYZ/YZX/ZXY/XZY/YXZ/ZYX

[Summary]

    Rotation (euler angles)

[Syntax]

    RotateXYZ $x $y $z
    RotateYZX $x $y $z
    RotateZXY $x $y $z
    RotateXZY $x $y $z
    RotateYXZ $x $y $z
    RotateZYX $x $y $z

[Arguments]

    float $x                    X (unit = degree)
    float $y                    Y (unit = degree)
    float $z                    Z (unit = degree)

Scale

[Summary]

    Scaling

[Syntax]

    Scale $x $y $z

[Arguments]

    float $x                    X
    float $y                    Y
    float $z                    Z

BlendBone

[Summary]

    Vertex blend bone

[Syntax]

    BlendBone $bone $m11 $m12 $m13 $m14 \
                    $m21 $m22 $m23 $m24 \
                    $m31 $m32 $m33 $m34 \
                    $m41 $m42 $m43 $m44

[Arguments]

    ref Bone $bone              Reference to the vertex blend bone
    float $m11 ... $m14         Column 1 of the offset matrix
    float $m21 ... $m24         Column 2 of the offset matrix
    float $m31 ... $m34         Column 3 of the offset matrix
    float $m41 ... $m44         Column 4 of the offset matrix

DrawPart

[Summary]

    Drawing part

[Syntax]

    DrawPart $part

[Arguments]

    ref Part $part              Reference to the drawing part

Mesh Commands

SetMaterial

[Summary]

    Material settings

[Syntax]

    SetMaterial $material

[Arguments]

    ref Material $material      Reference to the material settings

SetArrays

[Summary]

    Vertex data

[Syntax]

    SetArrays $arrays

[Arguments]

    ref Arrays $arrays          Reference to the vertex data

BlendIndices

[Summary]

    Vertex blend indices

[Syntax]

    BlendIndices $count $index ...

[Arguments]

    int $count                  Vertex blend count
    int $index ...              Vertex blend indices

DrawArrays

[Summary]

    Drawing primitive

[Syntax]

    DrawArrays $mode $vertCount $primCount $index ...

[Arguments]

    enum DrawMode $mode         Drawing mode
    int $vertCount              Vertex count
    int $primCount              Primitive count
    ushort $index ...           Vertex indices

Material Commands

Diffuse

[Summary]

    Diffuse color

[Syntax]

    Diffuse $r $g $b

[Arguments]

    float $r                    R
    float $g                    G
    float $b                    B

Ambient

[Summary]

    Ambient color

[Syntax]

    Ambient $r $g $b

[Arguments]

    float $r                    R
    float $g                    G
    float $b                    B

Specular

[Summary]

    Specular color

[Syntax]

    Specular $r $g $b

[Arguments]

    float $r                    R
    float $g                    G
    float $b                    B

Emission

[Summary]

    Emission color

[Syntax]

    Emission $r $g $b

[Arguments]

    float $r                    R
    float $g                    G
    float $b                    B

Opacity

[Summary]

    Opacity

[Syntax]

    Opacity $opacity

[Arguments]

    float $opacity              Opacity

Shininess

[Summary]

    Specular exponent

[Syntax]

    Shininess $shininess

[Arguments]

    float $shininess            Specular exponent

Layer Commands

SetTexture

[Summary]

    Texture image

[Syntax]

    SetTexture $texture

[Arguments]

    ref Texture $texture        Reference to the texture image

Texture Commands

UVTranslate

[Summary]

    UV translation

[Syntax]

    UVTranslate $u $v

[Arguments]

    float $u                    U
    float $v                    V

UVScale

[Summary]

    UV scaling

[Syntax]

    UVScale $u $v

[Arguments]

    float $u                    U
    float $v                    V

Motion Commands

FrameLoop

[Summary]

    Loop range

[Syntax]

    FrameLoop $start $end

[Arguments]

    $start                      Start frame
    $end                        End frame

FrameRate

[Summary]

    Frame rate

[Syntax]

    FrameRate $fps

[Arguments]

    float $fps                  Frame rate (unit = frames per second)

FrameRepeat

[Summary]

    Repeat mode

[Syntax]

    FrameRepeat $mode

[Arguments]

    enum RepeatMode $mode       Repeat mode

Animate

[Summary]

    Animation

[Syntax]

    Animate $block $command $option $fcurve

[Arguments]

    ref Block $block            Reference to the block
    enum CommandType $command   Command type
    int $option                 Option
    ref FCurve $fcurve          Reference to the animation curve

Enumeration Constants

BlockType

File            = 0x0002
Model           = 0x0010
Bone            = 0x0011
Part            = 0x0012
Mesh            = 0x0013
Arrays          = 0x0014
Material        = 0x0016
Layer           = 0x0017
Texture         = 0x0018
Motion          = 0x001b
FCurve          = 0x001c

CommandType

FileName        = 0x0080
FileImage       = 0x0081
BoundingBox     = 0x0082
BoundingSphere  = 0x0083
ParentBone      = 0x0440
Visibility      = 0x0441
Pivot           = 0x0442
Translate       = 0x0443
Rotate          = 0x0444
RotateXYZ       = 0x0445
RotateYZX       = 0x0446
RotateZXY       = 0x0447
RotateXZY       = 0x0448
RotateYXZ       = 0x0449
RotateZYX       = 0x044a
Scale           = 0x044b
BlendBone       = 0x0460
DrawPart        = 0x047f
SetMaterial     = 0x04c0
SetArrays       = 0x04c1
BlendIndices    = 0x04c2
DrawArrays      = 0x04e0
Diffuse         = 0x0581
Ambient         = 0x0582
Specular        = 0x0583
Emission        = 0x0584
Opacity         = 0x0588
Shininess       = 0x0589
SetTexture      = 0x05c0
UVTranslate     = 0x0621
UVScale         = 0x0623
FrameLoop       = 0x06c0
FrameRate       = 0x06c1
FrameRepeat     = 0x06c2
Animate         = 0x06e0

VertexFormat

POSITION        = 1 << 0
NORMAL          = 1 << 1
COLOR           = 1 << 3
TEXCOORD        = 1 << 5
WEIGHTn         = n << 8
INDICES         = 1 << 16

InterpType

CONSTANT        = 0x0000
LINEAR          = 0x0001
HERMITE         = 0x0002
CUBIC           = 0x0003
SPHERICAL       = 0x0004

ExtrapType

HOLD            = 0x0000
CYCLE           = 0x0011
SHUTTLE         = 0x0022
HOLD_HOLD       = 0x0000
HOLD_CYCLE      = 0x0001
HOLD_SHUTTLE    = 0x0002
CYCLE_HOLD      = 0x0010
CYCLE_CYCLE     = 0x0011
CYCLE_SHUTTLE   = 0x0012
SHUTTLE_HOLD    = 0x0020
SHUTTLE_CYCLE   = 0x0021
SHUTTLE_SHUTTLE = 0x0022

DrawMode

POINTS          = 0x0000
LINES           = 0x0001
LINE_STRIP      = 0x0002
TRIANGLES       = 0x0003
TRIANGLE_STRIP  = 0x0004
TRIANGLE_FAN    = 0x0005

RepeatMode

HOLD            = 0x0000
CYCLE           = 0x0001