Plumber

A Blender addon for importing Source 1 engine maps, models, materials and textures.

This addon makes it possible to import full CS:GO, TF2, CS:S or other Source 1 game maps into Blender. Source 2 games, such as CS2, are not supported. 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 and installed Source games on Steam are detected automatically. You just need to select the correct game and start importing.

Supported file types are .vmf, .mdl, .vmt and .vtf. For a more complete overview of supported features, see Supported features for imported assets.

Table of contents

• Requirements
• Quick start
• Installation
  • Installing latest from source (very advanced users)
• Usage
  • Detecting new Steam games
  • Importing from old CS:GO installation
  • Common import options
  • Maps
  • MDL
  • Materials
  • Textures
  • Game file browser
• Troubleshooting
• Credits
• License

Requirements

• OS: Windows recommended. Linux and macOS supported.
• Blender: 2.90 or newer (up to version 1.1.1), 4.2 or newer (version 1.1.2 onwards).

Quick start

• Make sure you are using Blender 2.90 or newer.
• Install the latest release of this addon and enable it.
• Open the Blender console to get progress updates and start importing from the File -> Import -> Plumber menu.

Installation

You can also follow a video tutorial, such as this one by ItsJustChris. If you are using Blender 4.2 or above, you need to follow the text instructions below for installation. This tutorial is recorded using a beta version, but also applies to the latest version apart from the addon installation.

Blender 4.2 and above

• Make sure you are using Blender 4.2 or newer.
• Download the latest extension release from the releases tab. Make sure you download a file starting with plumber-1.x.x, not the source code.
• Do not extract the downloaded files.
• Open Blender and install the extension by dragging and dropping the downloaded .zip file into the Blender window.

Blender 4.1 and below

• Make sure you are using Blender 2.90 or newer.
• Download the v1.1.1 addon release from the releases tab. Make sure you download a file starting with plumber-v1.1.1, not the source code. Also make sure that you downloaded the correct version for your operating system.
• Do not extract the downloaded files.
• Open Blender and install the addon:

Installing latest from source (very advanced users)

Make sure the following dependencies for building the addon are installed. The links are for Windows, for other platforms you need to figure it out yourself.

• Python 3 with "Add python to environment variables" selected in the installer
• Git with "Git from the command line and also from 3rd-party software" selected in the installer
• Rust language and the latest stable compiler
• Microsoft C++ Build Tools with "C++ MFC for latest build tools (x86 & x64)" selected in the installer under individual components.
• CMake

After installing the dependencies, follow the following steps:

• Download the repository as a .zip from the green "Code" button in the top right corner and extract it somewhere (or alternatively, clone it). Make sure you get the master branch, not the default release branch, if you want the latest changes.
• Run pip install -r requirements-dev.txt on a terminal.
• Run python setup.py build_rust --inplace --release.
• Figure out where your Blender is installed, and take note of the path of blender executable.
• Create the dist directory.
• Run {path/to/blender} --command extension build --source-dir plumber --output-dir dist
• The built extension will be in the dist directory.

Usage

Installed Steam games are automatically detected on the first addon startup. You can start importing immediately without any configuration required. Just remember to select the correct game when importing files.

Detecting new Steam games

If you have installed new Source games on Steam after installing the addon, you will need to redetect the installed games. This can be done from Edit -> Preferences -> Add-ons -> Plumber by pressing the Redetect installed games button.

If you need to manually detect a game that is not installed in Steam, you can use the Detect from gameinfo.txt button in the preferences.

Importing from old CS:GO installation

If you have the old CS:GO files somewhere, it is possible to manually configure a game to import old CS:GO assets.

You need to open preferences, and use the Detect from gameinfo.txt button. This opens a file select dialog, where you need to choose the gameinfo.txt file, which is present in csgo directory inside the old CS:GO installation.

Common import options

• Game: Select the game you're importing assets from.

Maps

File -> Import -> Plumber -> 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/. They can also be easily extracted using the addon's game file browser.

When importing decompiled maps, overlay related errors such as overlay contains invalid uv data or no geometry was imported for the sides the overlay was applied to can be safely ignored as BSPSource sometimes generates broken overlays.

Blender may appear frozen for a couple of seconds when importing complex maps. To see possible errors in realtime, open the Blender console from Window -> Toggle System Console before importing.

Options:

• Embedded files path: You can generally leave this empty, this will be automatically detected when importing decompiled maps.
• Brushes: Imports the "core" of the map: walls, floors etc.
  • Overlays: Imports overlays that are on top of solids, such as bomb site sprays.
  • Epsilon: You should not touch this.
  • Cut threshold: You should not touch this.
  • Merge solids: By choosing Merge, the importer will merge most of the map into a single object. This can improve performance, but makes the map harder to edit and may cause issues in 3D sky transformation.
  • Invisible solids: By default, invisible solids are not imported. If you want, you can import them by changing this.
• 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 output height: 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.
• Props: Imports all complex models in the map, such as cars and crates.
  • Dynamic props: The alternate options here remove more complex prop setups. This is useful when exporting the map into different software, since animated props may cause issues. Remove armatures should be usually used when exporting.
• Materials: Imports materials for solids, overlays and props.
  • See Materials for more options.
• Sky camera: Imports the origin point of the 3D sky used in 3D skybox transforming.
• Unknown entities: Imports other, unsupported entities as simple empty objects.
• Scale: Adjusts the scale everything is imported at. The default is 0.01, but 0.0254 can be used for a more realistic scale.

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.

Imported metadata for external scripts / addons

• Some extra metadata is imported as custom properties for Blender 3.0 and above.
• This can be used by external scripts and addons to further process the imported data.
• This includes full paths for props' models and materials as path_id, and Source engine-defined properties for entities as props.

MDL

File -> Import -> Plumber -> Source Model (.mdl)

Options:

• Materials: Imports materials for the model.
  • See Materials for more options.
• Import animations: Imports included animations for the model. Note: some animations are currently unsupported.
• Scale: Adjusts the scale the model is imported at. The default is 0.01, but 0.0254 can be used for more realistic scale.

Materials

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

Options:

• Simple materials: You should enable this if you plan on exporting outside Blender. This will disable advanced features such as blended materials.
• Texture format: Selects the file format for imported textures. Can be changed to TGA for better import performance, at the cost of higher memory usage.
• 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.

Textures

File -> Import -> Plumber -> Valve Texture Format (.vtf)

The texture is imported as an image in Blender, and is not immediately visible after import. It can be used in materials with a Image Texture node, for example.

Game file browser

Game file browser allows you to import models, materials or textures straight from the game files, or to extract any game files.

Can be accessed from the 3D view side bar under Plumber (recommended), or alternatively from File -> Import -> Plumber -> Browse game files.

The browser only browser supported file types by default. This can be changed to display all files by opening the arrow on the lower left corner of the file list.

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. When asking for help, always remember to open the Blender console from Window -> Toggle System Console before importing and to send the console logs afterwards with the help request by copy-pasting.

Credits

• Me for the addon, backing library and VTFLib wrapper.
• Nemesis for original VTFLib and panzi for a Linux-compatible port, and me for a version that is easier to run multi-threaded.

MDL reading is based on:

• ZeqMacaw's Crowbar
• REDxEYE's SourceIO
• Artfunkel's Blender Source Tools

Skybox conversion is based on:

• Alex Flint and Pete Florence's bilinear interpolation code.
• adamb70's Python-Spherical-Projection.

Also thanks to:

• Devostated for testing and bug reporting.
• Everyone else who reported bugs or suggested improvements.

License

Copyright (C) 2024 Lassi Säike

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.