Quickstart

This guide will walk you through your first BSP decompilation using both the GUI and CLI interfaces.

Prerequisites

Before you begin, ensure you have:

BSPSource installed (see installation guide)
A Source engine BSP file to decompile
Basic familiarity with Source engine maps

Using the GUI

The graphical interface is the easiest way to get started with BSPSource.

Launch BSPSource GUI

Run the appropriate launcher for your platform:

Windows: Double-click bspsrc.bat
Linux: Run ./bspsrc.sh in terminal
JAR: Run java -jar bspsrc.jar (with no arguments)

Select your BSP file

Click Browse next to the input field and select the .bsp file you want to decompile.You can also drag and drop BSP files directly into the window.

Configure options (optional)

Common options to consider:

Extract embedded files - Essential for workshop maps with custom content
Brush mode - Choose decompilation method (default: BRUSHPLANES)
Debug mode - Adds extra information to output (useful for learning)

For your first run, the default settings work well.

Start decompilation

Click Decompile to begin the process.Progress will be shown in the output window. The VMF file will be created in the same directory as the BSP file.

Open in Hammer

Once complete, open the generated .vmf file in Hammer Editor:

hammer.exe path/to/decompiled_map.vmf

If you see gray textures or ERROR models, you may need to extract embedded files. See troubleshooting.

Using the CLI

The command-line interface offers more control and is ideal for batch processing.

Basic Decompilation

Decompile a single BSP file:

bspsrc path/to/map.bsp

This creates map.vmf in the same directory as the input file.

Common Options

Extract Embedded Files
Custom Output Path
Brush Mode
Selective Decompilation

Extract materials, models, and sounds embedded in the BSP:

bspsrc --unpack_embedded map.bsp

Creates a map/ folder with extracted content. Essential for workshop maps.

Specify where to save the VMF file:

bspsrc -o output/custom_name.vmf map.bsp

For multiple files, use a directory:

bspsrc -o output_folder/ map1.bsp map2.bsp map3.bsp

Choose how geometry is decompiled:

# Original faces only (smaller file)
bspsrc --brushmode ORIGFACE map.bsp

# Brushes and planes (default, most accurate)
bspsrc --brushmode BRUSHPLANES map.bsp

# Split faces (for complex geometry)
bspsrc --brushmode SPLITFACE map.bsp

See decompilation modes for details.

Exclude specific entity types:

# Skip static props (faster, smaller file)
bspsrc --no_sprp map.bsp

# Skip overlays and cubemaps
bspsrc --no_overlays --no_cubemaps map.bsp

# Only decompile world geometry
bspsrc --no_point_ents --no_brush_ents map.bsp

Debug Mode

Enable verbose output and extra VMF data:

bspsrc -d map.bsp

Debug mode:

Shows detailed processing information
Adds comments to VMF with source data
Helps diagnose decompilation issues

Batch Processing

Decompile all BSP files in a directory:

# Recursively find and decompile all BSP files
bspsrc -r maps_folder/

# Non-recursive (only current directory)
bspsrc maps_folder/

Complete Example: Workshop Map

Here’s a complete workflow for decompiling a Steam Workshop map:

Locate the BSP file

Workshop maps are typically in:

steamapps/workshop/content/[appid]/[workshopid]/

Decompile with embedded file extraction

bspsrc --unpack_embedded -d workshop_map.bsp

This creates:

workshop_map.vmf - The decompiled map
workshop_map/ - Folder with extracted materials/models

Install extracted content

Move extracted files to your game directory:

# Copy materials
cp -r workshop_map/materials/* "path/to/game/materials/"

# Copy models
cp -r workshop_map/models/* "path/to/game/models/"

Load in Hammer

Open the VMF in Hammer. Textures and models should now appear correctly.

Using BSPInfo

BSPSource includes bspinfo, a tool for inspecting BSP files without decompiling:

# View general information
bspinfo map.bsp

# List embedded files
bspinfo --list-embedded map.bsp

# Check for protection
bspinfo --check-protection map.bsp

The GUI version shows:

BSP version and game
Lump statistics
Entity count
Embedded files
Protection detection

Next Steps

CLI Reference

Explore all command-line options and flags

Decompilation Modes

Learn about different brush decompilation strategies

Configuration

Deep dive into configuration options

Troubleshooting

Solve common decompilation issues

Common Issues

Gray textures or ERROR models

The map contains embedded materials/models that weren’t extracted.Solution: Re-run with --unpack_embedded and move the extracted files to your game directory.

Decompilation fails with error

The map may be protected or use an unsupported BSP version.Solution:

Check BSP version with bspinfo map.bsp
Try --no_prot to skip protection checks
See protection detection for details

VMF won't open in Hammer

The VMF may be too large or contain invalid data.Solution:

Try selective decompilation (exclude entities with --no_* flags)
Use --brushmode ORIGFACE for a smaller file
Enable debug mode (-d) to see what’s failing

How do I know which game to specify?

BSPSource auto-detects the game from the BSP header.To see all supported games:

bspsrc --appids

To override detection:

bspsrc --appid 240 map.bsp  # Force Counter-Strike: Source

Getting Started

Usage

Features

Guides

Prerequisites

Using the GUI

Using the CLI

Basic Decompilation

Common Options

Debug Mode

Batch Processing

Complete Example: Workshop Map

Using BSPInfo

Next Steps

CLI Reference

Decompilation Modes

Configuration

Troubleshooting

Common Issues

Build docs developers (and LLMs) love

Getting Started

Usage

Features

Guides

​Prerequisites

​Using the GUI

​Using the CLI

​Basic Decompilation

​Common Options

​Debug Mode

​Batch Processing

​Complete Example: Workshop Map

​Using BSPInfo

​Next Steps

CLI Reference

Decompilation Modes

Configuration

Troubleshooting

​Common Issues

Build docs developers (and LLMs) love

Prerequisites

Using the GUI

Using the CLI

Basic Decompilation

Common Options

Debug Mode

Batch Processing

Complete Example: Workshop Map

Using BSPInfo

Next Steps

Common Issues