This document provides a detailed description of the MDL/MDX file format used in Knights of the Old Republic (KotOR) games. The MDL (Model) and MDX (Model Extension) files together define 3D models, including geometry, animations, and other related data.

• KotOR MDL/MDX File Format Documentation
  • Table of Contents
  • File Structure Overview
  • File Headers
    • MDL File Header
    • Model Header
    • Geometry Header
    • Names Header
    • Animation Header
    • Event Structure
  • Node Structures
    • Node Header
    • Trimesh Header
    • Danglymesh Header
    • Skinmesh Header
    • Lightsaber Header
    • Light Header
    • Emitter Header
    • Reference Header
  • Controllers
    • Controller Structure
  • Additional Controller Types
    • Light Controllers
    • Emitter Controllers
  • Node Types
    • Node Type Bitmasks
    • Common Node Type Combinations
  • MDX Data Format
    • MDX Data Bitmap Masks
    • Skin Mesh Specific Data
  • Vertex and Face Data
    • Vertex Structure
    • Face Structure
  • Vertex Data Processing
    • Vertex Normal Calculation
    • Tangent Space Calculation
  • Model Classification Flags
  • File Identification
    • Binary vs ASCII Format
    • KotOR 1 vs KotOR 2 Models
  • Model Hierarchy
    • Node Relationships
    • Node Transformations
  • Smoothing Groups
  • ASCII MDL Format
    • Model Header Section
    • Geometry Section
    • Node Definitions
    • Animation Data
  • Controller Data Formats
    • Single Controllers
    • Keyed Controllers
    • Special Controller Cases
  • Skin Meshes and Skeletal Animation
    • Bone Mapping and Lookup Tables
      • Bone Map (bonemap)
      • Bone Serial and Node Number Lookups
    • Vertex Skinning
      • Bone Weight Format (MDX)
      • Vertex Transformation
    • Bind Pose Data
      • QBones (Quaternion Rotations)
      • TBones (Translation Vectors)
      • Bone Matrix Computation
  • Additional References
    • Editors
    • See Also

KotOR models are defined using two files:

• MDL: Contains the primary model data, including geometry and node structures.
• MDX: Contains additional mesh data, such as vertex buffers.

Implementation: Libraries/PyKotor/src/pykotor/resource/formats/mdl/

The MDL file begins with a file header, followed by a model header, geometry header, and various node structures. Offsets within the MDL file are typically relative to the start of the file, excluding the first 12 bytes (the file header).

Below is an overview of the typical layout:

+-----------------------------+
| MDL File Header             |
+-----------------------------+
| Model Header                |
+-----------------------------+
| Geometry Header             |
+-----------------------------+
| Name Header                 |
+-----------------------------+
| Animations                  |
+-----------------------------+
| Nodes                       |
+-----------------------------+

The MDL file header is 12 bytes in size and contains the following fields:

The Model Header is 92 bytes in size and immediately follows the Geometry Header. Together with the Geometry Header (80 bytes), the combined structure is 172 bytes from the start of the MDL data section (offset 12 in the file).

The Geometry Header is 80 bytes in size and is located at offset 12 in the file (immediately after the File Header). It contains fundamental model information and game engine version identifiers.

The Names Header is located at file offset 180 (28 bytes). It contains metadata for node name lookup and MDX file information. This section bridges the model header data and the animation/node structures.

Each animation begins with a Geometry Header (80 bytes) followed by an Animation Header (56 bytes), for a combined size of 136 bytes.

Each animation event is 36 bytes in size and triggers game actions at specific animation timestamps.

The Node Header is 80 bytes in size and is present in all node types. It defines the node's position in the hierarchy, its transform, and references to child nodes and animation controllers.

The Trimesh Header defines static mesh geometry and is 332 bytes in KotOR 1 and 340 bytes in KotOR 2 models. This header immediately follows the 80-byte Node Header.

The Danglymesh Header extends the Trimesh Header with 28 additional bytes for physics simulation parameters. Total size is 360 bytes (K1) or 368 bytes (K2). The danglymesh extension immediately follows the trimesh data.

The Skinmesh Header extends the Trimesh Header with 100 additional bytes for skeletal animation data. Total size is 432 bytes (K1) or 440 bytes (K2). The skinmesh extension immediately follows the trimesh data.

The Lightsaber Header extends the Trimesh Header with 20 additional bytes for lightsaber blade geometry. Total size is 352 bytes (K1) or 360 bytes (K2). The lightsaber extension immediately follows the trimesh data.

The Light Header follows the Node Header and defines light source properties including lens flare effects. Total size is 92 bytes.

The Emitter Header follows the Node Header and defines particle emitter properties and behavior. Total size is 224 bytes.

The Reference Header follows the Node Header and allows models to reference external model files. Total size is 36 bytes. This is commonly used for attachable models like weapons or helmets.

Each controller is 16 bytes in size and defines animation data for a node property over time. Controllers reference shared keyframe/data arrays stored separately in the model.

Note: If bit 4 (value 0x10) is set in the column count byte, the controller uses Bezier interpolation and stores 3× the data per keyframe (value, in-tangent, out-tangent).

Controllers specific to light nodes:

Controllers specific to emitter nodes:

Node types in KotOR models are defined using bitmask combinations. Each type of data a node contains corresponds to a specific bitmask.

#define NODE_HAS_HEADER    0x00000001
#define NODE_HAS_LIGHT     0x00000002
#define NODE_HAS_EMITTER   0x00000004
#define NODE_HAS_CAMERA    0x00000008
#define NODE_HAS_REFERENCE 0x00000010
#define NODE_HAS_MESH      0x00000020
#define NODE_HAS_SKIN      0x00000040
#define NODE_HAS_ANIM      0x00000080
#define NODE_HAS_DANGLY    0x00000100
#define NODE_HAS_AABB      0x00000200
#define NODE_HAS_SABER     0x00000800

Common node types are created by combining these bitmasks:

The MDX file contains additional mesh data that complements the MDL file. The data is organized based on flags indicating the presence of different data types.

The MDX Data Flags field in the Trimesh Header uses bitmask flags to indicate which vertex attributes are present in the MDX file:

#define MDX_VERTICES        0x00000001  // Vertex positions (3 floats: X, Y, Z)
#define MDX_TEX0_VERTICES   0x00000002  // Primary texture coordinates (2 floats: U, V)
#define MDX_TEX1_VERTICES   0x00000004  // Secondary texture coordinates (2 floats: U, V) 
#define MDX_TEX2_VERTICES   0x00000008  // Tertiary texture coordinates (2 floats: U, V)
#define MDX_TEX3_VERTICES   0x00000010  // Quaternary texture coordinates (2 floats: U, V)
#define MDX_VERTEX_NORMALS  0x00000020  // Vertex normals (3 floats: X, Y, Z)
#define MDX_VERTEX_COLORS   0x00000040  // Vertex colors (3 floats: R, G, B)
#define MDX_TANGENT_SPACE   0x00000080  // Tangent space data (9 floats: tangent XYZ, bitangent XYZ, normal XYZ)
// Skin Mesh Specific Data (set programmatically, not stored in MDX Data Flags field)
#define MDX_BONE_WEIGHTS    0x00000800  // Bone weights for skinning (4 floats)
#define MDX_BONE_INDICES    0x00001000  // Bone indices for skinning (4 floats, cast to uint16)

Note: The bone weight and bone index flags (0x00000800, 0x00001000) are not actually stored in the MDX Data Flags field but are used internally by parsers to track skin mesh vertex data presence.

For skin meshes, additional vertex attributes are stored in the MDX file for skeletal animation:

• Bone Weights (MDX Bone Weights Offset): 4 floats per vertex representing influence weights. Weights sum to 1.0 and correspond to the bone indices. A weight of 0.0 indicates no influence.

• Bone Indices (MDX Bone Indices Offset): 4 floats per vertex (cast to uint16) representing indices into the mesh's bone map array. Each index maps to a skeleton bone that influences the vertex.

The MDX data for skin meshes is interleaved based on the MDX Vertex Size and the active flags. The bone weight and bone index data are stored as separate attributes and accessed via their respective offsets.

Each vertex has the following structure:

Each face (triangle) is defined by:

Vertex normals are computed using surrounding face normals, with optional weighting methods:

1. Area Weighting: Faces contribute to the vertex normal based on their surface area.

   area = 0.5f * length(cross(edge1, edge2))
   weighted_normal = face_normal * area

   Reference: vendor/mdlops/MDLOpsM.pm:465-488 - Heron's formula implementation Uses Heron's formula for area calculation.

2. Angle Weighting: Faces contribute based on the angle at the vertex.

   angle = arccos(dot(normalize(v1 - v0), normalize(v2 - v0)))
   weighted_normal = face_normal * angle

3. Crease Angle Limiting: Faces are excluded if the angle between their normals exceeds a threshold (e.g., 60 degrees).

For normal/bump mapping, tangent and bitangent vectors are calculated per face. KotOR uses a specific tangent space convention that differs from standard implementations.

Reference: vendor/mdlops/MDLOpsM.pm:5470-5596 - Complete tangent space calculation
Based on: OpenGL Tutorial - Normal Mapping with KotOR-specific modifications

1. Per-Face Tangent and Bitangent:

   deltaPos1 = v1 - v0;
   deltaPos2 = v2 - v0;
   deltaUV1 = uv1 - uv0;
   deltaUV2 = uv2 - uv0;
   
   float r = 1.0f / (deltaUV1.x * deltaUV2.y - deltaUV1.y * deltaUV2.x);
   
   // Handle divide-by-zero from overlapping texture vertices
   if (r == 0.0f) {
       r = 2406.6388; // Magic factor from p_g0t01.mdl analysis ([mdlops:5510-5512](https://github.com/th3w1zard1/mdlops/blob/master/MDLOpsM.pm#L5510-L5512))
   }
   
   tangent = (deltaPos1 * deltaUV2.y - deltaPos2 * deltaUV1.y) * r;
   bitangent = (deltaPos2 * deltaUV1.x - deltaPos1 * deltaUV2.x) * r;
   
   // Normalize both vectors
   tangent = normalize(tangent);
   bitangent = normalize(bitangent);
   
   // Fix zero vectors from degenerate UVs ([mdlops:5536-5539, 5563-5566](https://github.com/th3w1zard1/mdlops/blob/master/MDLOpsM.pm#L5536-L5566))
   if (length(tangent) < epsilon) {
       tangent = vec3(1.0, 0.0, 0.0);
   }
   if (length(bitangent) < epsilon) {
       bitangent = vec3(1.0, 0.0, 0.0);
   }

2. KotOR-Specific Handedness Correction:

   Important: KotOR expects tangent space to NOT form a right-handed coordinate system. Reference: vendor/mdlops/MDLOpsM.pm:5570-5587

   // KotOR wants dot(cross(N,T), B) < 0 (NOT right-handed)
   if (dot(cross(normal, tangent), bitangent) > 0.0f) {
       tangent = -tangent;
   }

3. Texture Mirroring Detection and Correction:

   Reference: vendor/mdlops/MDLOpsM.pm:5588-5596

   // Detect texture mirroring via UV triangle orientation
   tNz = (uv0.x - uv1.x) * (uv2.y - uv1.y) - (uv0.y - uv1.y) * (uv2.x - uv1.x);
   
   // If texture is mirrored, invert both tangent and bitangent
   if (tNz > 0.0f) {
       tangent = -tangent;
       bitangent = -bitangent;
   }

4. Per-Vertex Tangent Space: Averaged from connected face tangents and bitangents, using the same weighting methods as normals.

The Model Header's Classification byte (offset 0 in Model Header, offset 92 from MDL data start) uses these values to categorize the model type:

Note: These values are not bitmask flags and should not be combined. Each model has exactly one classification value.

• Binary Model: The first 4 bytes are all zeros (0x00000000).
• ASCII Model: The first 4 bytes contain non-zero values (text header).

The game version can be determined by examining Function Pointer 0 in the Geometry Header (offset 12 in file, offset 0 in MDL data):

Usage: Parsers should check this value to determine:

• Whether the model is from KotOR 1 or KotOR 2 (affects Trimesh Header size: 332 vs 340 bytes)
• Whether this is a model geometry header (0x00) or animation geometry header (0x01)

• Each node can have a parent node, forming a hierarchy.
• The root node is referenced in the Geometry Header.
• Nodes inherit transformations from their parents.

1. Position Transform:

   • Stored in controller type 8.
   • Accumulated through the node hierarchy.
   • Applied as translation after orientation.

2. Orientation Transform:

   • Stored in controller type 20.
   • Uses quaternion multiplication.
   • Applied before position translation.

• Automatic Smoothing: Groups are created based on face connectivity and normal angles.
• Threshold Angles: Faces with normals within a certain angle are grouped.

KotOR models can be represented in an ASCII format, which is human-readable.

newmodel <model_name>
setsupermodel <model_name> <supermodel_name>
classification <classification_flags>
ignorefog <0_or_1>
setanimationscale <scale_factor>

beginmodelgeom <model_name>
  bmin <x> <y> <z>
  bmax <x> <y> <z>
  radius <value>

node <node_type> <node_name>
  parent <parent_name>
  position <x> <y> <z>
  orientation <x> <y> <z> <w>
  scale <value>
  <additional_properties>
endnode

newanim <animation_name> <model_name>
  length <duration>
  transtime <transition_time>
  animroot <root_node>
  event <time> <event_name>
  node <node_type> <node_name>
    parent <parent_name>
    <controllers>
  endnode
doneanim <animation_name> <model_name>

For constant values that don't change over time:

<controller_name> <value>

Reference: vendor/mdlops/MDLOpsM.pm:3734-3754 - Single controller reading
Example: position 0.0 1.5 0.0 (static position at X=0, Y=1.5, Z=0)

For animated values that change over time:

• Linear Interpolation:

  <controller_name>key
    <time> <value>
    ...
  endlist
  

  Reference: vendor/mdlops/MDLOpsM.pm:3760-3802 - Keyed controller reading
  Example:

  positionkey
    0.0 0.0 0.0 0.0
    1.0 0.0 1.0 0.0
    2.0 0.0 0.0 0.0
  endlist
  

  Linear interpolation between keyframes.

• Bezier Interpolation:

  Reference: vendor/mdlops/MDLOpsM.pm:1704-1710, 1721-1756 - Bezier flag detection and data reading
  Format: Each keyframe stores 3 values per column: (value, in_tangent, out_tangent)

  <controller_name>bezierkey
    <time> <value> <in_tangent> <out_tangent>
    ...
  endlist
  

  Example:

  positionbezierkey
    0.0 0.0 0.0 0.0  0.0 0.3 0.0  0.0 0.3 0.0
    1.0 0.0 1.0 0.0  0.0 0.7 0.0  0.0 0.7 0.0
  endlist
  

  Binary Storage: Bezier controllers use bit 4 (value 0x10) in the column count field to indicate bezier interpolation (mdlops:1704-1710). When this flag is set, the data section contains 3 times as many floats per keyframe (mdlops:1721-1723).

  Interpolation: Bezier curves provide smooth, non-linear interpolation between keyframes using control points (tangents) that define the curve shape entering and leaving each keyframe.

1. Compressed Quaternion Orientation (MDLControllerType.ORIENTATION with column_count=2):

   Reference: vendor/mdlops/MDLOpsM.pm:1714-1719 - Compressed quaternion detection
   Format: Single 32-bit packed value instead of 4 floats

   X: bits 0-10  (11 bits, bitmask 0x7FF, effective range [0, 1023] maps to [-1, 1])
   Y: bits 11-21 (11 bits, bitmask 0x7FF, effective range [0, 1023] maps to [-1, 1])
   Z: bits 22-31 (10 bits, bitmask 0x3FF, effective range [0, 511] maps to [-1, 1])
   W: computed from unit constraint (|q| = 1)

   Decompression: vendor/kotorblender/io_scene_kotor/format/mdl/reader.py:850-868 Decompression: Extract bits using bitmasks, divide by effective range (1023 for X/Y, 511 for Z), then subtract 1.0 to map to [-1, 1] range.

2. Position Delta Encoding (ASCII only):

   Reference: vendor/mdlops/MDLOpsM.pm:3788-3793
   In ASCII format animations, position controller values are stored as deltas from the geometry node's static position.

   animated_position = geometry_position + position_controller_value

3. Angle-Axis to Quaternion Conversion (ASCII only):

   Reference: vendor/mdlops/MDLOpsM.pm:3718-3728, 3787
   ASCII orientation controllers use angle-axis representation [x, y, z, angle] which is converted to quaternion [x, y, z, w] on import:

   sin_a = sin(angle / 2);
   quat.x = axis.x * sin_a;
   quat.y = axis.y * sin_a;
   quat.z = axis.z * sin_a;
   quat.w = cos(angle / 2);

Skinned meshes require bone mapping to connect mesh vertices to skeleton bones across model parts.

Reference: vendor/reone/src/libs/graphics/format/mdlmdxreader.cpp:703-723 - prepareSkinMeshes()

Maps local bone indices (0-15) to global skeleton bone numbers. Each skinned mesh part can reference different bones from the full character skeleton.

Example: Body part might use bones 0-10, while head uses bones 5-15. The bone map translates local indices to the correct skeleton bones.

After loading, bone lookup tables must be prepared for efficient matrix computation:

def prepare_bone_lookups(skin_mesh, all_nodes):
    for local_idx, bone_idx in enumerate(skin_mesh.bonemap):
        # Skip invalid bone slots (0xFFFF)
        if bone_idx == 0xFFFF:
            continue
        
        # Ensure lookup arrays are large enough
        if bone_idx >= len(skin_mesh.bone_serial):
            skin_mesh.bone_serial.extend([0] * (bone_idx + 1 - len(skin_mesh.bone_serial)))
            skin_mesh.bone_node_number.extend([0] * (bone_idx + 1 - len(skin_mesh.bone_node_number)))
        
        # Store serial position and node number
        bone_node = all_nodes[local_idx]
        skin_mesh.bone_serial[bone_idx] = local_idx
        skin_mesh.bone_node_number[bone_idx] = bone_node.node_id

Each vertex can be influenced by up to 4 bones with normalized weights.

References:

• vendor/reone/src/libs/graphics/format/mdlmdxreader.cpp:261-268 - Bone weight/index reading
• vendor/kotorblender/io_scene_kotor/format/mdl/reader.py:478-485 - Skinning data structure

Per-vertex data stored in MDX file:

• 4 bone indices (as floats, cast to int)
• 4 bone weights (as floats, should sum to 1.0)

Layout:

Offset   Type        Description
+0       float[4]    Bone indices (cast to uint16)
+16      float[4]    Bone weights (normalized to sum to 1.0)

// For each vertex
vec3 skinned_position = vec3(0.0);
vec3 skinned_normal = vec3(0.0);

for (int i = 0; i < 4; i++) {
    if (vertex.bone_weights[i] > 0.0) {
        int bone_idx = vertex.bone_indices[i];
        mat4 bone_matrix = getBoneMatrix(bone_idx);
        
        skinned_position += bone_matrix * vec4(vertex.position, 1.0) * vertex.bone_weights[i];
        skinned_normal += mat3(bone_matrix) * vertex.normal * vertex.bone_weights[i];
    }
}

// Renormalize skinned normal
skinned_normal = normalize(skinned_normal);

References:

• vendor/mdlops/MDLOpsM.pm:1760-1768 - Bind pose arrays
• Skin mesh stores bind pose transforms for each bone

Array of quaternions representing each bone's bind pose orientation:

struct QBone {
    float x, y, z, w;  // Quaternion components
};

Array of Vector3 representing each bone's bind pose position:

struct TBone {
    float x, y, z;  // Position in model space
};

mat4 computeBoneMatrix(int bone_idx, Animation anim, float time) {
    // Get bind pose
    quat q_bind = skin.qbones[bone_idx];
    vec3 t_bind = skin.tbones[bone_idx];
    mat4 inverse_bind = inverse(translate(t_bind) * mat4_cast(q_bind));
    
    // Get current pose from animation
    quat q_current = evaluateQuaternionController(bone_node, anim, time);
    vec3 t_current = evaluatePositionController(bone_node, anim, time);
    mat4 current = translate(t_current) * mat4_cast(q_current);
    
    // Final bone matrix: inverse bind pose * current pose
    return current * inverse_bind;
}

Note: KotOR uses left-handed coordinate system, ensure proper matrix conventions.

• MDLEdit
• MDLOps
• Toolbox Aurora
• KotorBlender
• KOTORmax

• KotOR/TSL Model Format MDL/MDX Technical Details
• MDL Info (Archived)
• xoreos Model Definitions
• xoreos Model Implementation

This documentation aims to provide a comprehensive and structured overview of the KotOR MDL/MDX file format, focusing on the detailed file structure and data formats used within the games.