MDL File Loader

Posted Sep 23, 2016
Last Updated Nov 20, 2023
Wall Worm and Black Mesa MDL plugin

The MDL loader in Wall Worm is a geometry plugin for 3ds Max that derives its mesh and skin data from MDL files. This plugin was developed by the following people:

The MDL Loader was a joint project of Black Mesa and Wall Worm. You can express your appreciation for this plugin by buying a copy of Black Mesa (buy on steam on banner above) and Wall Worm plugins.


The MDL Loader allows you to place MDL files from your computer (both from inside a game's VPK and on the file system) into a 3ds Max scene. The plugin allows you to display the following settings from the MDL:

  • Mesh
  • Bones and Skin Weights (Max 2018+)
  • Materials and Texture Groups
  • Bodygroup(s)
  • LOD(s)
  • Collision Model
  • List of Animations
  • Prop Fading

Except for the actual animations, all settings are visible in the Max viewport. Animation and flex data support is on the roadmap but there is no ETA on this feature.

Model Sources

The MDL loader allows you to derive the model's data from these sources: MDL File, WWMT Helper and QC File. When you load a MDL object, it will first look for the MDL file; if the MDL file is not found, it will check if there is a WWMT Helper node in the scene to derive data from; if there is no MDL file and WWMT Node found, it will attempt to find a QC file for that model in your modelsrc paths.

Note that the fastest implementation is the MDL file, followed by WWMT Helper and finally the QC file. The QC file implementation can be very slow, so only use it as a last resort.

Supported Versions of Max

At this time, the MDL loader can only load MDL files in 3ds Max 2015-2020. Older versions of Max only have support for WWMT Nodes and QC files. Support for other versions of Max may or may not come. The most compatibility for all features is in 3ds Max 2018+.

Creating a MDL Object

There are several ways to create MDL Nodes in a scene. The actual class name of this object type is WallWormMDL. This geometry class is now the default object for new Point Entities (created by the Point Entity Floater or when importing a VMF/MAP file). This is also now the geometry class used for new WWMT Proxies.

Create Prop

  1. Click Wall Worm > Wall Worm Level Design > Point Entities
  2. Select an entity that uses models (like prop_static)
  3. Enter the World Model Path into the World Model Field (or select from list of models already in the scene)
  4. Click Place Entities and start placing props.

Create WWMT Proxy

  1. Click Wall Worm > Wall Worm Level Design > WWMT Proxy Tools
  2. Select a WWMT Helper in the scene
  3. Click the Create Proxies from WWMT button

Create Manual Prop

  1. In the Create Tab of the Command Panel, click on Geometry
  2. Change the Catgeory drop down to Wall Worm
  3. Click the Source Model button
  4. Click in the scene to make WallWormMDL nodes
  5. When done, select a node and go to the Modify Tab of the Command Panel
  6. Click the Load Model From MDL file to browse your game models*

* You can also click the WWMT button to get a mesh from a WWMT node, the MDL Node to select model from another WallWormMDL node in the scene, or the QC button to import from a QC file.

Wall Worm Integration

The WallWormMDL objects have native integration with the Wall Worm VMF Exporter. When not tied to an entity, the exporter will export a WallWormMDL object with these rules:

  • Skip Prop: VMF Exclude = On
  • prop_physics: Physics Data compiled into Prop
  • prop_dynamic: Sequences Found
  • prop_static: None of the Above
  • cycler: All cases when the Engine is set to Goldsrc

If you want to override those defaults, you can select an entity from the Entity List in the Wall Worm Connection rollout and click the Tie To Entity Button. Once you've done this, that entity will now determine this prop's data.

Note that if you tie the prop to an entity that doesn't have a model property, the prop's scene mesh may not relate to what the actual entity looks like and does (for example, if you tie it to a env_cubemap, then the object will export as a cubemap and not as a prop).

When a WallWormMDL object is tied to a prop entity, those parameters in the entity that match the parameters of the WallWormMDL will always be disabled in the entity and only controlled by the WallWormMDL. Those parameters include World Model, Skin, Bodygroups, Default Animation and fade distances.

General Scene and ViewPort Management

To optimize the scene's viewport performance or to enforce some display settings, you can open the Global WallWormMDL settings by clicking the Global Display Settings in the MDL Utilities rollout when a WallWormMDL object is selected, or you can type this command into the MAXScript Listener:


LOD Policy: This setting controls how to preview LODs inside the viewport. The options are 1) Let Each Model Decide; 2) All Lowest LOD (show the model at lowest detail); 3) All Highest LOD (show each model at it's highest detail). All settings are dependent on the Preview LODS setting (below) being on.

Preview LODs: This setting turns on/off LOD previewing entirely based on camera position. You can still change the LOD level per prop in the prop's settings.

Preview Fade: This setting will fade the props based on their distance to the viewport camera and their fade settings. Note that at this time, screen space fading is not implemented, only distance fading.


Missing Materials & Textures: In order for the textures to appear in your model, WW must be able to reference an actual file on the filesystem. When it cannot find the VTF (WW Pro) in the game/materials path or TGA (all versions) in the MatGen path, it will pull the VTF from the VPK into the MatGen path; if the MatGen path is not set in your settings or is set to a path that is not writable, this will fail. In your global settings, change the MatGen to "$images" (without the quotation marks) or set the path manually to a specific location.

Message that the MDL Importer is only supported in Max ## and I'm running that version or newer: this means you did not restart 3ds Max after running the installation script. Please review the updated installation instructions in WW.

Known Issues

At this time, here are the current known issues:

  • Only currently available for 3ds Max 2015+.
  • When first installed, the plugin won't load MDL files until 3ds Max is restarted.
  • Bodygroup submodels do not always show up initially. If this occurs, cycling through the bodygroup submodels usually makes the missing submodels appear. This is a known bug that we hope to fix.
  • At this time, VTF files that are inside VPK files will be converted to TGA files in your MATGEN path; those TGA files do not currently have correct alpha in many cases. As such, you may want to extract your VTF files to the MATGEN path and WW will use those assets instead of creating TGA files (in WW Pro).
  • The materials for a MDL are saved into the scene and reloaded each time the scene is re-opened (meaning materials are not refreshed from VMT/VTF automatically) but are using a snapshot of the material from when the MDL was first loaded. Tools to clear that cache are not yet available.
  • Bones and Skin Weights are only available in 3ds Max 2018+.
  • Animations are not yet supported.
  • Flexes are not yet supported.
Importing Models

Articles and documents related to importing model assets into 3ds Max.

  1. MDL File Loader
  2. Mass Model Fetch

Newsletter Subscription