Warning

All Source Engine file format parsers have been merged into a single monorepo: https://github.com/TAServers/source-parsers.

Updates will only be made to this new repository, while the individual repositories (such as this one) will remain archived to avoid breaking existing projects.

MDLParser

Simple and modern library for parsing the Valve model format.

Documentation: https://taservers.github.io/MDLParser/

See also: https://github.com/TAServers/BSPParser and https://github.com/TAServers/VTFParser.

What's included

• Classes for parsing and abstracting the MDL, VVD and VTX file formats for the Source engine.
• Helper functions to simplify accessing the disparate but related data in all three files (see below).
• Enums, limits and structs with almost 100% coverage* of the formats.
• Runtime errors for issues when parsing the data due to corruption or a bug in the parser.

*Much of the MDL data is not currently parsed or exposed. These can be used to either implement your own more complex or specialised parser, or to easily extend - and hopefully PR - the MdlParser::Mdl class.

Example

The following minimal example shows how you can easily and safely traverse the interconnected structure of the three files using the accessor helpers:

#include "MDLParser.hpp"

// Load from a file on disk, an API, or somewhere in memory
const auto mdlData = ...;
const auto vtxData = ...;
const auto vvdData = ...;

// Parse the data (you should wrap this in a try/catch)
const MdlParser::Mdl mdl(mdlData);
const MdlParser::Vtx vtx(vtxData, mdl.getChecksum());
const MdlParser::Vvd vvd(vvdData, mdl.getChecksum());

// You can construct all three with or without checksums,
// but passing one in will automatically check it against the header before parsing
// const Vtx vtx(vtxData);
// const Vvd vvd(vvdData);

// For each body part (body group) pair...
MdlParser::Accessors::iterateBodyParts(
  mdl,
  vtx,
  [&](const MdlParser::Mdl::BodyPart& mdlBodyPart, const MdlParser::Vtx::BodyPart& vtxBodyPart) {
    // For each model pair...
    MdlParser::Accessors::iterateModels(
      mdlBodyPart,
      vtxBodyPart,
      [&](const MdlParser::Mdl::Model& mdlModel, const MdlParser::Vtx::Model& vtxModel) {
        // Only using the highest LoD here
        const MdlParser::Vtx::ModelLod& vtxLod = vtxModel.levelOfDetails[0];

        // For each mesh pair...
        MdlParser::Accessors::iterateMeshes(
          mdlModel,
          vtxLod,
          [&](const MdlParser::Mdl::Mesh& mdlMesh, const MdlParser::Vtx::Mesh& vtxMesh) {
            // For each strip group...
            for (const MdlParser::Vtx::StripGroup& stripGroup : vtxMesh.stripGroups) {
              // For each vertex...
              MdlParser::Accessors::iterateVertices(
                vvd,
                mdlModel,
                mdlMesh,
                stripGroup,
                [&](
                  const MdlParser::Structs::Vtx::Vertex&,
                  const MdlParser::Structs::Vvd::Vertex& vvdVertex,
                  const MdlParser::Structs::Vector4D& tangent
                ) {
                  // ...
                }
              );
            }
          }
        );
      }
    );
  }
);