BSPSource: decompiling Source engine maps back into Hammer

The round trip it exists to enable

BSPSource is a map decompiler for Source engine maps, written in Java, and it does one job: it decompiles .bsp map files back to .vmf files that can be loaded in Hammer, Valve's official level editor. That round trip is the point. A .bsp is what the game ships, a compiled lump of geometry and entities, and once it is compiled you cannot open it in the editor. Decompiling it gives you text you can read, diff and edit, and then recompile. The project is explicitly not a map editor and does not try to be, it is the step that makes an existing map editable again. The primary language is Java, the licence field on the repository is a custom one that GitHub cannot classify with the terms in the LICENSE.md file, and the last push was on 2026-10-11 with the most recent release being 1.4.8 from April 2026.

It descends from VMEX, and fixes what was wrong with it

BSPSource is based on a reengineered version of VMEX 0.98g by Rof, and the reason for the fork is stated plainly: VMEX is no longer developed and lacks support for newer Source engine games. So this is a maintained successor rather than a new idea, and the improvements list reads as a changelog of what the original could not do. Support for more and newer Source engine games up to Dota 2. Support for new entity types including func_areaportal, func_areaportalwindow, func_occluder and info_lighting. Support for the tools/blocklight texture. Support for compressed and big-endian encoded maps, which it names as the XBox 360 and PS3 cases. Decompiling of VMEX maps flagged with protection, and at least detecting other anti-decompiling methods. Improved support for prop_static and info_overlay. Improved console output, a new graphical user interface with an output window, a new command line interface, and a new integrated pakfile extractor. There is also a long entry that simply says numerous bug fixes, and a final line that says open source, which was the thing VMEX was not.

Two binaries, one for the decompiler and one for map info

The running instructions are three steps and they distinguish two tools. You go to the releases page and, depending on your operating system, download either the Linux or the Windows archive, and there is a third option, a jar-only archive, that works on any system with Java 24 or newer installed and properly configured. You extract the contents of the zip to a new folder. And then to launch bspsrc or bspinfo you run the corresponding file, the .bat versions on Windows and the .sh versions on Linux. So the project ships two front ends. One is the decompiler proper, and the other is a separate program for inspecting a map, and both are distributed in the same archives. The Java 24 requirement for the jar-only route is a recent floor and is worth noting, since a map decompiler is exactly the kind of tool people expect to run on an older machine.

The grey texture problem, and the extraction that fixes it

The second entry in the FAQ is the most practically useful thing in the documentation. If all the textures are grey and the models are errors, that is most of the time because the textures and models do not exist in the base game but are embedded in the bsp file itself. That happens frequently with workshop maps and with maps using csgo's automcombine prop feature. The fix is to extract the embedded files, which you do by checking Extract embedded files in the decompiler, and then move the contents of the extracted folders into your game's own texture and model folders. The underlying reason is a compilation setting, and the reason this bites people is that the map looks broken in Hammer even though it plays correctly in the game, so a first-time user can easily conclude the decompiler is at fault rather than the assets being inside the map.

The entities that cannot be restored

The limitations section is specific and honest. Some internal entities that are entirely consumed by vbsp, the compiler, cannot be perfectly restored, and the list follows. It covers func_instance, func_instance_parms, func_instance_origin, func_viscluster and info_no_dynamic_shadow. The reason these are hard is structural rather than a gap in effort, since these entities are eaten by the compiler at build time, so the information simply is not in the .bsp for the decompiler to recover. A map that relies heavily on func_instance for set dressing will therefore come back with gaps, and that is a property of the format rather than a bug you can report. The same reasoning applies to the other entries, since anything the compiler folds away at compile time is gone by the time there is a .bsp to decompile.

Which games work, and which are out of scope

The first FAQ entry sets the scope. Generally speaking, most Source engine games should work with BSPSource out of the box, even though they might not be explicitly supported, and the instruction if you hit a problem with a particular game or map is to open an issue. The games that definitely do not work are named too. Games based on the older goldsrc engine and games based on the newer Source 2 engine are not supported, because their map format differs wildly from the one the Source engine uses. That is a hard boundary rather than a rough edge, so a project on Source 2, which is where the current Source engine games sit, needs a different approach entirely. The improvement list mentions support up to Dota 2, which dates the era the tool covers.

How the code is arranged

The repository is a Maven multi-module Java project, with a pom.xml at the root, a.mvn directory, a jitpack.yml for publishing, and four modules with names that describe the layers. bspsrc-app is the application layer, holding the command line and graphical front ends. bspsrc-decompiler is the part that does the actual work of turning a.bsp into a.vmf. bspsrc-common holds what the other modules share, and bspsrc-lib is the library layer. There is a test directory at the root, an icons directory for the interface, and a LICENSE.md file alongside the README. The release naming is worth noticing too, since the tags are 1.4.8, 1.4.7 and 1.4.6.1, and the third of those has a patch suffix on the minor line, which is a reasonable convention for a tool that needs to ship a fix without renumbering the series.

Editorial conclusion

BSPSource suits a level designer or a modder who needs to look inside a compiled Source map, either to learn how something was built or to fix it in Hammer. It does not suit a project working with Source 2 or GoldSrc, because their map formats differ enough that the tool does not support them at all, and it cannot restore every entity that the compiler consumed. Before you rely on it, check the entity list in the limitations section for the map you have in mind, and if the textures come out grey, use the embedded file extraction option and move the extracted materials and models into your game's folders.

Frequently asked questions

Official sources

1. ata4/bspsrc on GitHub
2. Issues
3. README
4. Releases