BSPSource

BSPSource is designed for the Source engine.

• Supported: Most Source engine games work out of the box.
• Unsupported:
  • GoldSrc (older engine)
  • Source 2 (newer engine)

If you encounter errors with a specific Source engine game, you should open an issue on GitHub.

BSPSource is a Java-based map decompiler that converts Source engine .bsp files into .vmf files for use in the Hammer editor.

Installation Steps

1. Download the appropriate release from the releases page:
   • bspsrc-linux.zip for Linux.
   • bspsrc-windows.zip for Windows.
   • bspsrc-jar-only.zip for any system with Java 24+ installed and configured.
2. Extract the contents of the downloaded zip file to a new folder.

Launching the Application

Run the corresponding script for your operating system:

• Windows: bspsrc.bat or bspinfo.bat
• Linux: bspsrc.sh or bspinfo.sh

# Example for Linux users
chmod +x bspsrc.sh
./bspsrc.sh

BSPSource is a command-line tool used to decompile BSP files into VMF (Valve Map Format) files. You can provide one or more BSP files or directories as positional parameters. If you use the --list flag, the tool will treat the provided paths as text files containing lists of BSP file paths (one per line).

# Decompile a single BSP file
bspsrc map.bsp

# Decompile all BSP files in a directory
bspsrc ./maps_folder/

# Decompile using a text file containing a list of BSP paths
bspsrc --list list_of_maps.txt

# Decompile multiple files and specify an output directory
bspsrc -o ./output_dir/ map1.bsp map2.bsp

BSPSource is a command-line tool. You can launch it by executing the main class. If you run the application without any arguments, it will display the usage information (help text) to the console. To perform specific tasks, you must provide the appropriate commands and options as defined by the CLI surface.

# To view usage/help:
java -cp <classpath> info.ata4.bspsrc.app.src.cli.BspSourceCli

# To execute a command:
java -cp <classpath> info.ata4.bspsrc.app.src.cli.BspSourceCli <command> [options]

If decompiled maps show gray textures or error models in Hammer, it is likely because the materials/models were embedded in the .bsp file (common in workshop maps or maps using csgo's automcombine prop feature) rather than existing in the game's base files.

Solution

1. In the BSPSource decompiler, check the Extract embedded files option.
2. Once extracted, move the contents of the resulting material/model folders into your game's corresponding material/ or model/ directory.

Some internal entities that are entirely consumed by vbsp cannot be perfectly restored during decompilation. If your map relies heavily on these, they may not function as expected in the .vmf file:

• func_instance
• func_instance_parms
• func_instance_origin
• func_viscluster
• info_no_dynamic_shadow

Common flags available for the bspsrc command:

• -d, --debug: Enable debug mode. Increases verbosity and adds additional data to the VMF file.
• -r, --recursive: Recursively decompile files found in subdirectories.
• -o, --output <path>: Override output path for VMF file(s). Treated as a directory if multiple BSP files are provided.
• -l, --list: Treat specified files as text files containing a BSP file list (one path per line).

General settings for the decompilation process.

Miscellaneous Options:

• --no_vmf: Don't write any VMF files, read BSP only.
• --no_lumpfiles: Don't load lump files (.lmp) associated with the BSP file.
• --no_prot: Skip decompiling protection checking (increases speed for unprotected maps).
• --no_visgroups: Don't group entities from instances into visgroups.
• --no_cams: Don't create Hammer cameras above each player spawn.
• --appid <id>: Overrides game detection by using this Steam Application ID instead.
• --format <format>: Sets the VMF format:
  • AUTO: Automatic
  • OLD: Source 2004 to 2009
  • NEW: Source 2010 and later
• --unpack_embedded: Unpack embedded files in the bsp.
• --no_smart_unpack: Disable 'smart' extracting of embedded files (smart extracting skips files generated by vbsp).

Control how world brushes and displacement surfaces are handled during decompilation.

Brush Options:

• --no_brushes: Don't write any world brushes.
• --no_disps: Don't write displacement surfaces.
• --brushmode <mode>: Sets the brush decompiling mode. Valid modes are:
  • BRUSHPLANES: brushes and planes
  • ORIGFACE: original faces only
  • ORIGFACE_PLUS: original + split faces
  • SPLITFACE: split faces only
• --thickness <value>: Thickness of brushes created from flat faces in units.

Modify how textures are handled in the decompiled output.

Texture Options:

• --facetex <texture>: Replace all face textures with this one.
• --bfacetex <texture>: Replace all back-face textures with this one (used in face-based decompiling modes only).
• --no_cubemaptexfix: Don't fix environment-mapped materials.
• --no_ttfix: Don't fix tool textures (e.g., toolsnodraw, toolsblocklight).
• --nodraw_invis-sides: Apply toolsnodraw texture to brushsides which are not rendered in game (mainly sides facing the void).

Use the --appids flag to list all known Steam Application IDs supported by BSPSource for automatic game detection.

bspsrc --appids