VMEX - a HL2 map decompiler

VMEX is a simple map decompiler for Half-Life 2 Source engine maps (i.e., for HL2, HL2DM, CS:S, and DoD:S). It converts compiled .bsp map files into .vmf files which can be loaded into Hammer.

The .vmf files produced can be loaded to see how various mapping techniques are used in the official Valve maps. Note that you will first need to extract the .bsp files from the game cache files using GCF Scape (download, mirror), if you wish to decompile these maps.

You can see examples of the decompiled output here.

Download and installation instructions are here. If you're having trouble running VMEX, see this page. Also see the FAQ page for frequently asked questions about VMEX.

14th Oct 2007 - Version 0.98g for Episode 2 & TF2

This new update (download) is a first attempt at fixing problems when decompiling some HL2: Episode 2 maps. The slightly changed prop_static lump in some maps is now handled. Some small problems with envmapped displacement textures have been corrected.

I don't know how complete the decompilation is at the moment. Several previously unused data lumps in the maps are now active, but whether this is important can't be known until the release of the Ep2 SDK update.

This update should also be able to decompile maps from TF2, though I have not been able to test this (Edit: I have now confirmed this works). Portal maps seem to be decompilable with the previous version of Vmex without problems (except for one map, test chamber 11, which this new version of Vmex will decompile succesfully).

25th May 2007 - Version 0.98f

A tiny update that fixes a problem with maps that have lots of displacement surface data. Download the new version here.

1st October 2006 - Lightmap resolutions, and a special version for The Ship

A minor point I forgot to mention yesterday, the new version 0.98e will now decode and output the lightmap resolution of a face.

On another note, at the request of ts2do I've created a special version of VMEX that will understand the modified prop_static lumps used by maps for The Ship (Source version). Because the modified structures aren't flagged in the files, this special release will only work for The Ship's BSP files, and won't work for maps from regular HL2 (and mods). There is no need to download this special version unless you wish to decompile maps from The Ship.

30th September 2006 - Version 0.98e

I'm no longer doing much with HL2 nowadays, but it seems that VMEX was having trouble handling the DoD:S map dod_jagd, and would only decompile it if displacement were disabled. (Thanks to Ville Lindsberg for bring this to my attention.) This new release fixes a problem with displacement triange tags that was preventing the map from being decompiled.

Also included in this release (separate from the above fix) is an option to output a modified form of displacement brushes that are less susceptible to problems due to rounding errors than the previous form. By default this option is on; uncheck the "new disp. brushes" or use the "-u" command-line option to revert to the old type of brushes.

11th January 2006 - Another day, another update - Version 0.98b

If you've tried decompiling the DoD:S maps, or other maps produced by the recent release of the SDK compile tools, you've probably noticed that in Hammer some of the brushes with tool textures (playerclip, trigger, skybox etc.) look a bit strange. That's because the new version of VBSP does some rationalisation of non-visible textures to reduce the number of texinfos in a map (you'll see this during compiling as a "Reduced XXXX texinfos to YYYY" message).

This is good, because it saves map resources, but as a side effect VMEX was producing some very strange looking tool brushes with the textures smeared out on some sides. The latest VMEX version now automatically re-orientates textures that are perpendicular to the brush face, fixing this problem.

A side effect of the compiler change also stopped VMEX from assigning overlays to the correct brush faces. The new version also fixes this, and also improves the way overlays are assigned to displacement surfaces.

I'm currently trying to fix bugs with env_cubemaps, and also finally get func_areaportals and func_occluders working right.

8th January 2006 - Version 0.98

The latest release fixes a crash bug with some maps that have odd entity formats (thanks to DarkTree for the report). This version also by default performs "crunching" of brush face vertices that are very close together. This fixes the "solids were not loaded" errors that some decompiled maps produced when loaded into Hammer.

I haven't extensively checked this feature with a large range of maps, so the crunching process can be disabled with the "-w" command line option, or by unchecking "crunch faces" in the GUI.

1st October 2005 - Version 0.97

The latest release now supports version 20 BSP files, as used in the recent Day of Defeat: Source release. Note that the source SDK hasn't yet been updated to support DoD:S, so most textures and props will be missing when loading the dod_ maps into Hammer. Because of this, it's also difficult for me to tell if anything is going wrong with the decompilation, however the basic map structures seem to be working OK. As soon as the SDK is updated, we'll see if everything is working alright.

29th September 2005 - DoD:S

With the release of DoD:Source, the map file format has changed to a new version (20) and VMEX can't yet cope with it. Apart from some new lumps that presumably hold HDR lighting info, the leaf lump format has changed. I'm working on it now, and I'll try to release an updated version soon.

15th May 2005 - Version 0.96

This small update fixes the texture problems with de_port, and also a small bug involving how clip brushes are assigned.

14th May 2005 - bug with de_port

The new CS:S map de_port shows some strange texture effects on displacements when decompiled. (Most of them turn out with a stretched metal grate texture.) It seems that Valve have made a few changes to their compilers again. The fix is simple, so I should have a new version of the decompiler that fixes this and a few other small bugs within a day or so. There may also be some subtle problems with decompiling de_inferno; I am investigating.

7th April 2005 - Version 0.95

This version (download) integrates the graphical interface with the command line versions. To run in GUI mode, double-click on the vmex.bat (or vmex2.bat) file. To run in command-line mode, invoke with a map filename as an argument, as before.

Also, Source engine version 17 BSP files (as used in Vampire: The Masquerade Bloodlines) are now partially supported. They can be decompiled and viewed in Hammer. Note however that the HL2 SDK compile tools are not compatible with the version of the Source engine used in VTMB, and so the maps cannot be recompiled for use in the game.

4th April 2005 - Version 0.93G

This new version includes a graphical interface to VMEX. The number one question I keep getting about the decompiler is how to run it from a command line, so now VMEX includes a simple GUI to make things easier for people. If you prefer the standard command-line interface, there is no reason to download the new version.

Most decompilation options are available from the GUI version, but as usual the default options will be suitable for almost all maps.

To run the program, double-click on the vmex_g.bat batch file. Then use the "browse" button to locate a .bsp file, and press the "decompile" button to run the decompiler. The decompilation process can be seen as usual in the command-line window.

28th February 2005 - Version 0.93

This small update fixes the bug with overlays on certain maps, that prevented proper decompilation.

25th February 2005 - overlay bug

The new CS:S map de_train shows up a bug in the current version of the decompiler. For the moment, use the -v option to turn off overlay decompilation. You might also see this bug on other maps that use overlays; I will release a fixed version presently.

8th February 2005 - Version 0.92

Version 0.92 (download) now outputs overlays as info_overlay entities. It also fixes a bug which prevented the last worldbrush in the map from being decompiled.

1st February 2005 - Version 0.91

This version (download) fixes a (rare) bug with texture handling that prevented some maps from being decompiled.

27th January 2005 - Version 0.90

A new version is now available to download. Displacement surfaces are now decompiled by default. Use the -h switch to turn them off.

This version now walks the map's BSP tree to determine which brushes belong to which brush entities. This method eliminates the guessing needed in the previous version, so VMEX no longer needs to use face-decompilation when decompiling some entities.

A bug in the previous version (which caused problems when decompiling maps with large numbers of planes) is now fixed.

26th January 2005 - Displacements!

I got displacement surfaces working! Finally. Turns out I was better off letting Hammer guess some of the missing information, rather than try to guess it myself. They're not totally perfect (in rare cases there are some glitches where displacements meet) but they're good enough. The next release will have displacement support, along with a fix for a bug that cropped up in the last version, that prevents some larger maps being decompiled.

Update - 24th January 2005 - Version 0.80

VMEX version 0.80 is now available to download. This version, by default, uses a new decompiling method that is much better than the old one. In fact, it almost completely recovers the original .vmf file (though as always, it is not possible to do so perfectly), including things that couldn't be decompiled before, such as clip and hint brushes.

However, the new mode (-m3) may get confused when decompiling brush entities on some maps, and fall-back to the old face-decompiling method where it needs to. On some maps this may not be enough to correct the problem. If you see odd-looking brush entities, try decompiling using one of the old modes (-m0, -m1 or -m2 options) to check them.

Displacements, which are still not decoded (I'm working on it), tend to be more obviously missing in this version. If you see a large hole textured with the yellow NODRAW texture, it's likely that a displacement surface was originally present.

Since this new version produces decompiled files that are a bit too good, I've added the ability for map authors to prevent VMEX from decompiling their maps. See the FAQ page for details.

This version fixes the bug with locale-specific number formats, and so the workaround below is no longer needed.

Update - 19th January 2005 - Bug!

Thanks due to several people contacting me, I've realised there's a bug in all versions of vmex. If you live in a place that uses a comma as a decimal separator (so you'd write 123.45 as 123,45) then you may find that you can't decompile any maps successfully. The problem is Vmex is producing .vmf files with comma-separated decimals that Hammer cannot read (Hammer always expects files with numbers in US/English format).

I'll fix the bug properly in the next version, but for now there is a workaround. Use this command line to run vmex:

java -Duser.language=en -jar vmex.jar <mapname.bsp>

This switches Java to english temporarily, so that number formats are written correctly. Sorry for the bug, I hope nobody got too frustrated.

Update - 18th January 2005

Version 0.75 (download) - adds a new decompilation mode switch (-m#) which changes how VMEX decodes map faces. The method now used by default (-m2) is a good compromise between the number of brushes produced, and avoiding missing faces. Set -m0 for the old method, which produces smaller files, but has occasional missing faces, or -m1 for a method which produces 60-80% larger files, but almost no missing faces. The -m2 method is somewhat slower than the other two.

There is also a new algorithm for picking vertices in plane calculations. This reduces the possibility of bad brushes and out-of-memory errors on loading the file in Hammer. Some of the maps still produce these, though. Set the option -v to go back to the previous (slightly faster) method.

Update - 16th January 2005

Version 0.72 (download) - fixes a bug triggered by some envmapped texture names. This prevented decompiling the d2_coast_* levels.

Update - 16th January 2005

Version 0.71 (download) fixes a bug introduced into the last release. The decompiler should now handle larger maps again.

Update - 16th January 2005

Version 0.7 can now be downloaded. It has support for env_cubemap entities, and the some output options can be adjusted using command-line parameters.

Update - 14th January 2005

VMEX version 0.6 is now available for download. This version is able to decompile prop_static entities.

Download and installation

VMEX is a Java application, and requires Sun's Java Runtime Environment 5.0 (also known as v1.5.0). If you do not have this installed, you may download it from this page, using the Download JRE link (not the "Download JDK" link). Depending on how you download it, the JRE is up to 15 Mbytes in size.

Note that you may be required to restart your computer after the JRE is installed.

The current version VMEX v0.98g can be downloaded here (56 kbyte download). Unzip the vmex.bat and vmex.jar files into a folder containing the compiled map files, for maximum convenience.

To run VMEX, double click on the vmex.bat file, or open a command prompt or DOS box in the folder containing the maps and vmex files. Vmex is run using the command:

vmex [options] <mapname.bsp>

or alternately

java -jar vmex.jar [options] <mapname.bsp>

If you are using windows 98 or earlier, use the command:

vmex2 [options] <mapname>

If these commands do not work, you have probably not installed the Java Runtime Environment properly.

Note that if VMEX is run without a map name being specified, the GUI version is started automatically.

VMEX creates a file called <mapname>_d.vmf in the same folder as the original bsp file. This file can be loaded into Hammer as normal. Note that the file may be very large (~10 Mb) for some of the official maps.


VMEX has a number of command-line options that change the decompilation process. You may wish to change these options if you are having problems with decompiling certain maps, but usually the defaults are sufficient. Most of these options can also be altered when using the GUI interface to VMEX.

The decompilation mode. 0 for original faces (smallest number of brushes, but some missing faces), 1 for split faces (more brushes, but almost no missing faces), 2 for original faces where possible, else write split brushes (medium number of brushes, few missing faces). Use option 3 (default) to decompile via brushes and planes, which is slow, but gives the smallest files and the best match to the original .vmf file.
The depth (thickness) of brushes created by vmex, in map units. Setting this too small may lead to more brush errors. Set too high and you will see the backs of brushes protruding through opposite faces. The default value is 1.0.
The texture to apply to decompiled faces. 0 for white, 1 for black, 2 for the orange grid texture (dev/dev_measuregeneric01) and 3 (default) for the original face texture.
The texture to apply to back faces (faces which were not originally part of the map). 0 for white, 1 for black, 2 (default) for tools/toolsinvisible, 3 for the same texture as applied to the front (decompiled) face.
The decimal precision (number of decimal places) that floating-point numbers will be written to the .vmf file. Setting too high will make the decompiled files larger. Setting too small will make vertex, face and texture placement inaccurate. The default value is 8.
Don't fixup the origins of brush entities to be back in their original positions. If you set this option, all brush entities will be located at the map origin (0,0,0), as they are stored in the .bsp file.
Don't output prop_statics. Vmex will not attempt to decode or output the prop_static list as entities.
Don't fixup texture names. Texture names stored in the .bsp file are altered for faces that receive reflections, etc., from env_cubemap entities. Usually vmex will revert the textures to their original names. Set this option to not do that.
Controls env_cubemap entities. 0 for no cubemaps; 1 for cubemaps which specify location only. For value greater than 1, a list of sides tied to that cubemap (receiving environment maps from it) will be output, if there are less than value sides in the list. The default is 8; Setting value higher than about 50 risks crashing Hammer.
Don't output info_overlay entities.
Don't output displacement surfaces.
Output debug infomation to console.
Don't crunch brush face windings.
Use old pyramid-style displacement brushes for hidden faces.

Back to Index
Rof - (rof (at) bagthorpe.org)