The VMF Importer in Wall Worm was commissioned for largely by Robert Briscoe of Dear Esther and released in a polished state in early October, 2013. More improvements were added for Black Mesa in 2016. At this time, the best version for importing levels is 3ds Max 2020.3; there is a bug in 3ds Max 2021 that causes the scenes to crash when importing blend materials.

The VMF Importer will allow you to import a VMF file (Valve Map File) into 3ds Max. It will allow you to convert scenes into a format that Wall Worm can then re-export back into Source from 3ds Max.

Below is an overview of the current abilities of VMF Importer 1.0.

Import Capabilities

• Brush Geometry
• Displacements
• Displacement Alphas & Multiblends
• Entities
• Entity Outputs
• Entity Parameters
• Props
• Scene Materials
• Visgroups
• Hidden state of objects
• Groups
• Cameras

Before Importing a Level

The effectiveness of the VMF Importer can be affected by some of the settings you have in Wall Worm! Before importing a level, you should make sure that the following conditions are met:

1. You have WW 5.035 or later installed.
2. Make sure your global settings in WW are set, including the Game Info path--without this WW cannot load your models.
3. Your Entity Cache is up-to-date. If you have not set a FGD for your mod, the FGD is invalid, or the WW Entity Cache is out-of-date (because there have been updates to WW that affect entities) then the importer may fail or create incomplete entities.
4. You have set your global MatGen path (or opened the Wall Worm Material Library Generator at least once and set the root materials folder) to the root folder for material imports (must be a writable path). It's fine for this to be $images.
5. SKIP THIS STEP for 3ds Max 2015+: If you want to automatically import Prop world models, you should make sure to have Crowbar 0.26+ before importing and decompile your QC/SMD files into your Modelsrc folders. If you have those models decompiled, click the Prop Library From VMF File before importing your level to ensure that the models can be found. (If you don't see that button, update Wall Worm.) See Unpacking CGF and VPK Files for information on this.

Step 3 is necessary to correctly import entities into your scene. If you have problems parsing entities, see the docs on the Entity Cache.

Steps 4 is essential in order for the level to import the materials that are used in your level if your VTF files are stored inside a VPK. Also see the Washed Out Colors info in the Troubleshooting section.

Step 5 only works if all the QC/SMD files exist in your modelsrc folders. You do not need to do step 5 if using 3ds Max 2015+.

Using the VMF Importer

The VMF Importer is not a live link to the VMF file. The primary purpose is to bring current levels into Max so that you can finish them entirely inside 3ds Max with Wall Worm. It is not intended to keep going back and forth between Max and Hammer via the VMF importer/exporter.

The recommended process is:

1. Create new empty scene.
2. Click Wall Worm > Wall Worm Importers > Import VMF or Map File.
3. Choose appropriate options: Skip Hidden if you do not want to bring in objects that are hidden in the VMF; Instances if you want to import instances (can increase import times); Import Missing Models from QC (do a QC lookup to import models for those not imported via MDL--not recommended for Max 2015+).
4. Click Choose VMF or Map File and browse for VMF file.
5. When Scene is imported, click Hide Tool Textures to create visgroups from common tools and hide Skybox/NoDRAW brushes.

To use the importer, click Wall Worm > Wall Worm Importers > VMF Importer. You'll see a dialog explained below:

Bitmap Size

This menu exists to set the default texture size that the importer will use to help calculate UVW scale. This option is necessary in the event that the importer cannot find a bitmap for a material in the imported scene--because the scaling of textures on faces in Source is determined in part by the actual texture size (unlike 3ds Max where the texture dimensions are irrelevant).

Parse Failure Retry Limit

This spinner is a relic of when the VMF Importer was prone to the "Unknown System Exception" problem in the past. That problem has largely been circumvented. If you have a problem importing a scene and see the **unknown system exception** in the MAXScript listener, then you can bring this spinner up some to try and get past the problem. You should probably never bring this value above 10. 

Rounding Threshold

The rounding threshold is used to control a parameter for slicing brushes in the world. Leave it at 0.005 for your initial import. See troubleshooting below.

Choose and Import File

Press this button to browse for the VMF file that you want to import. If there are already objects in the scene, you will be prompted to continue the import or cancel the action.

• The import process can take a few seconds to several minutes (or an hour) depending on the complexity of your imported scene and the speed of your computer. The more objects in your scene, the longer it will take; displacements will increase the time of import. While developing this importer, I had access to the wildly complex and displacement-heavy level Esther from Dear Esther. That level took my computer around an hour to import (with Max 2014). With the newer MDL support (Max 2015+), Esther took about five (5) minutes.

Skip Hidden

This option will force the importer to skip generating objects that were hidden in the VMF.

Instances

This options will force the importer to import all VMF files from func_instances before importing this scene. It can take longer to import the scene with instances but is necessary if the VMF has instances and you want to import the scene entirely.

Import Missing Models from QC (for Max 2014 and older)

This option is NOT recommended for Max 2015+. For versions of Max that do not support native MDL importing, you can turn this option on for the importer to do QC lookups in the modelsrc folders. If the QC is found, WW will bind the Wall WormMDL node to the QC. Understand that this slows down the import significantly and will slow down the opening of the scene in future Max sessions. You are recommended to use Max 2015+ to avoid this.

Other functions

Import Props from Scene Entities (Not meant for Max 2015+)

This option is NOT recommended for Max 2015+. For older versions of Max, the recommendation in Wall Worm is to now import your props to the Prop Library before you import your level with the Prop Library From VMF File button. The steps below are for importing props in levels that were already imported before you made a Prop Library.

If you've made a Prop Library already, then pressing the Import Props from Scene button will bring in the WWMT helpers as XREF Scenes. If not, then the import will import the WWMT Helpers as embedded WWMT helpers in the scene.

Props are first imported to a hidden layer called VMF_Exclude. Then WW creates proxies of these hidden objects and places them at the entity locations. Note that the root (hidden) models are assigned WWMT helpers that have much of the data from the original QC.

Import Prop Details

This button launches the VBSP parser and prop detail importer. That tool works best if you own the Detailer plugin from Wall Worm.

Hide Tool Textures

Use this button on scenes already imported. It will generate Named Selection Sets based on common Source "Autovisgroups". It will then immediately hide those belonging to the various tool texture types.

Displacements to Mesh

This function is not to be used if you intend to re-use the scene back in Source. It will destroy the Displacements and convert them to editable poly objects that are no longer understood as displacements.

Displacement Materials to Blend

This option is mainly to convert the Direct X Shaders on imported displacements to be removed and just use the standard Blend material in Max. Mainly for versions of 3ds Max that do not support the latest blend shaders in WW.

Save Imported Material Library

This is to create a matlib file from the materials in the scene.

Select Imported Geometry that Needs Attention

This function will select any brushes in the scene that imported with a different number of sides than the VMF data provided. This can happen if there was an error rounding the data for brush slices. See troubleshooting below.

UV Fix

This will launch a little floater that will update as you select different brushes and show the UV/Material data used in that brush. See troubleshooting below.

Delete Imported Objects and Rebuild

This function will delete objects in the scene and rebuild them from the VMF data. See troubleshooting below.

It's imported... now what?

Once your scene is imported, you may need to do some tweaking. There are occassions that some brushes fail to import correctly. There are also times that objects imported that you do not need (WW helper objects that may not be necessary if you are porting to a different game). Below are some topics to troubleshoot your imports.

Troubleshooting

Below are topics relating with fixing import problems.

Rebuilding Broken Brushes

Immediately after importing a VMF you should check for problems.

1. Click the button Select Imported Geometry that Needs Attention. This will select all brushes (sometimes part of groups) that have geometry that is questionable. Take note of how many objects are selected in the command panel.
2. Change the Rounding Threshold value to a very tiny value (right-click the spinner arrows to jump to the smallest available).
3. Click Delete Imported Objects and Rebuild.
4. In the query box that appears, click No so that only those brushes that the system knows to be bad will rebuild.
5. After the rebuild is done, click the Select Imported Geometry that Needs Attention again. Note the difference in objects selected from step one.
6. Click Isolate Selection in Max.
7. Now you have a set of objects that you may need to manually fix. See below for UVW and material problems.

The ability to rebuild a brush is temporary! You can only rebuild a brush as long as you have not run another VMF Import or closed the file. Once you re-import the scene, the rebuild function is actually dangerous and should not be used again! In other words, only rebuild immediately after an import and do not import multiple VMFs into the same Max scene!

• Rebuilding a piece of geometry does not guarantee that it will be correct. There are sometimes some rounding errors in the math that cannot be alleviated at this point in time. In such cases, you may need to manually tweak some brushes. Turn on edged faces to more easily locate brushes that might need tweaked.

Fixing UVW Issues: Sometimes the UVW on a brush face is incorrect. There is a function to change the face's UVW. Like with the function for rebuilding geometry, above, the information for each brush's UVW coordinates is only available temporarily after the import. So it is important to do this after you import the scene.

1. Click the Fix UVW button in the VMF Importer window.
2. Browse for brushes with bad UVs.
3. Select the brush with Bad UVs.
4. In the modify tab, go to Polygon sub-object mode.
5. Select a Polygon with Bad UVs.
6. Click Get Face Normal to acquire the one controlling the UV plane.
7. Select one of the other UV Planes in the list until you find the one that should have been assigned to this face.
8. Optionally choose another Material for this face from the Materials drop-down if the material is also incorrect.

Dealing with Washed Out Colors: If you are experiencing problems with washed out colors, see this document on troubleshooting washed out colors.

func_instance is empty: This has two causes. The first is that you did not import the scene with the Instances option turned on. If this is the case, then click the Import Instances button (not this method can cause strange doubling of nodes and is not recommended; it's recommended to import the instances before the scene which happens if you import the instances with the main scene). If you did import the VMF with the Instances option turned on, then you may need to update the instances:

1. Click Wall Worm > Wall Worm Level Design > Point Entities
2. Select func_instance from the entity list
3. Click the Select All of Type in Scene Button
4. Click Isolate Selection in Max
5. Select each func_instance individually, open the Modify tab and click the Update button. The icon should turn green.

General VMF Import Tips

Here is a collection of tips on getting going from here:

Details coming soon.

• Why are my props appearing as cubes?
• Saving the materials as a Library
• Tweaking the materials
• Re-exporting the level
• Controlling the lighting
• Converting obsolete or missing entities