io_import_vmf

A Valve Map Format (.vmf) and Valve Material Type (.vmt) importer addon for Blender.

This addon makes it possible to import full CS:GO, TF2, CS:S or other Source game maps into Blender. The imported maps have accurate materials and overlays and correctly placed props and lights. Skyboxes are converted into a Blender-compatible format and 3D skyboxes can be easily transformed into the correct position and scale with minimal user intervention. No manual game file extraction is required, you just need to point the addon at your game directory and start importing.

Also includes helpful wrappers for importing HLAE .agr files and .qc/.mdl models with materials using the included material importer.

The addon ships bundled with Crowbar-Command-Line for automatic model decompilation.

Table of contents

• Requirements
• Quick start
• Installation
  • Configuration
  • Installing latest from source (advanced users)
• Usage
  • Common import options
  • Maps
  • Materials
  • QC / MDL
  • AGR
• Troubleshooting
• Credits
• License

Requirements

• OS: Windows recommended. Linux supported (requires .NET Core 3.1 for model importing).
• Blender: 2.82 or newer.
• Blender Source Tools must be installed and enabled to import props or .qc models!

Quick start

• Make sure you are using Blender 2.82 or newer.
• Install Blender Source Tools and enable it.
• Install the latest release of this addon and enable it.
• Open the addon's preferences.
• (Optional) Specify a cache directory (used for caching processed game files).
• Add a game definition using the "+" button.
• Press "Detect from a game directory".
• Browse to the installation directory of a Source game of your choice.
• Select the game directory inside the game installation directory. (For example, the csgo directory for CS:GO.)
• Open the Blender console to get progress updates and start importing from the File -> Import menu.

Installation

You can also check the video tutorial.

• Make sure you are using Blender 2.82 or newer.
• Download Blender Source Tools.
• Download the latest addon release from the releases tab. Make sure you download a file called io_import_vmf.zip, not the source code.
• Do not extract the downloaded files.
• Open Blender and install Blender Source Tools:
• Follow the same steps to install io_import_vmf.zip.

Configuration

• Follow the instructions below to configure the addon for CS:GO:
• You can add multiple game definitions if you're using the addon for different games.
• Notes for other games:
  • The game directory is called csgo only for CS:GO. For other games it could be called cstrike, hl2 and so on.
  • Some games may have multiple game directories (usually hl2 in addition to the game-specific directory). In that case you need to click the detect button multiple times and select them all.
• (Advanced users) If the automatic detection fails to detect some required files, you can add them manually using the "+" buttons.

Installing latest from source (advanced users)

• Make sure Python 3 is installed and that you selected "Add python to environment variables" in the installer.
• Make sure Git is installed and that you selected "Git from the command line and also from 3rd-party software" in the installer.
• Download the repository as a .zip from the green "Code" button in the top right corner and extract it somewhere (or alternatively, clone it).
• Run install.sh or install.ps1 depending on your OS.
• Make sure there are no errors in the terminal/PowerShell window.
• Follow the installation instructions above for the newly created .zip file.

Usage

Blender may appear frozen when importing complex maps. To see the import progress and possible errors in realtime, open the Blender console from Window -> Toggle System Console. Unsupported material parameter warnings are normal, although they could mean that the importer can not recreate fully accurate materials.

Common import options

• Verbose: Prints more information into the console, useful if you're running into issues.
• Game definition: Select the game you're importing assets from.

Maps

File -> Import -> Valve Map Format (.vmf)

Source maps that ship with the game are in a compiled .bsp file format. This addon can only import them in the original .vmf format. You can use BSPSource to decompile the map files into the .vmf format supported by this addon. BSPSource requires Java to be installed. For CS:GO, the .bsp map files can be found inside Counter-Strike Global Offensive/csgo/maps/.

Options:

• Embedded files path: You should leave this empty.
• Solids: Imports the "core" of the map: walls, floors etc.
  • Brush epsilon: You should not touch this.
  • Invisible brushes: By default, invisible brushes are not imported. If you want, you can import them by changing this.
  • Import overlays: Imports overlays that are on top of solids, such as bomb site sprays.
• Props: Imports all complex models in the map, such as cars and crates.
  • Optimize props: Optimizes props by removing empty armatures. You should leave this on.
  • Reuse old models: Reuses previously imported models in the current .blend file.
  • See QC / MDL for more options.
• Materials: Imports materials for solids, overlays and props.
  • See Materials for more options.
• Lights: Imports point lights and spotlights and the environment light (the sun).
  • Brightness factors: Controls how the brightnesses are converted into Blender. The default values are not fully accurate but good enough for most use cases.
• Sky: Imports the skybox as the world background.
  • Sky resolution: Controls the quality of the imported sky. The skybox is converted into a different format, so quality might suffer if this is set too low. The default setting is 0, which automatically calculates an optimal resolution.
• Import 3D sky origin: Imports the origin point of the 3D sky used in 3D skybox transforming.
• Scale: Scales everything by this value. Usually you don't need to touch this.

Transforming the 3D sky

• After the import has finished, you need to manually select every object that belongs to the 3D sky.
• The 3D sky is usually clearly outside the main map area and in much smaller scale.
• Ensure you have the 3D sky origin (sky_camera) selected as the active object, and press Object -> Transform VMF 3D sky to transform the objects into the correct position and scale.

Materials

File -> Import -> Valve Material Type (.vmt)

Options:

• Simple materials: You should enable this if you plan on exporting outside Blender.
• Texture interpolation: Selects the interpolation type for textures, the default value is a good choice.
• Allow backface culling: You can enable this if you know you need it.
• Import editor materials: Imports the materials visible inside Hammer instead of invisible materials for tool materials etc.
• Reuse old textures: Reuses previously imported textures in the current .blend file.

QC / MDL (requires Blender Source Tools or SourceIO)

File -> Import -> Source Engine Model (enhanced) (.qc/.mdl)

Requires .NET Core 3.1 on Linux.

Options:

• Skip collision meshes: Skips collision meshes. You should leave this on.
• Skip LOD meshes: Skips importing different LOD levels for meshes. You should leave this on.
• MDL strategy: Selects which addon to use for .mdl importing. BST is recommended.
• Materials: Imports materials for the model.
  • See Materials for more options.

AGR (requires afx-blender-scripts)

File -> Import -> HLAE afxGameRecord (enhanced) (.agr)

Requires .NET Core 3.1 on Linux.

Options:

• See QC / MDL for options.

Troubleshooting

The FAQ has instructions for dealing with some common problems and errors. If you can't find your problem there, you can ask on the AGR TechSupport Discord's #blender channel or open a new issue.

Credits

• Me for the addon, VMF and VMT parser and VTFLib wrapper.
• ValvePython for VPK and Valve KeyValues parser.
• Nemesis for VTFLib.
• Artfunkel for Blender Source Tools.
• ZeqMacaw and UltraTechX for Crowbar and Crowbar-Command-Line.
• REDxEYE for SourceIO.
• Devostated for testing and bug reporting.
• Alex Flint and Pete Florence for bilinear interpolation code.
• adamb70 for Python-Spherical-Projection.

License

This project is licensed under the MIT license. See LICENSE for more information.