Skip to main content

​
Overview

BSPSource provides a graphical user interface (GUI) for users who prefer a visual workflow over the command line. The GUI exposes all the same options as the CLI in an easy-to-use interface.

​
Launching the GUI

​
Windows

Double-click bspsrc-gui.exe or bspsrc.jar. Alternatively, run from the command line: 
java -jar bspsrc.jar

​
macOS / Linux

Run the JAR file: 
java -jar bspsrc.jar
Or make it executable and double-click: 
chmod +x bspsrc.jar
./bspsrc.jar

​
Interface Overview

The BSPSource GUI is organized into several sections:

​
File Selection

The main panel displays a list where you can add BSP files to decompile. Add Files
  • Click Add Files to browse for individual .bsp files
  • Click Add Folder to add all BSP files from a directory
  • Use Remove to delete selected files from the list
  • Use Clear to remove all files from the list
Output Options
  • Default Output: VMF files are created in the same directory as source BSP files
  • Custom Output: Specify a custom output directory for all decompiled VMF files

​
Configuration Tabs

The configuration panel is organized into tabs, matching the CLI option groups:
Control which entity types are written to the VMF file.Entity Types
  • ✓ Point Entities - Write point entities (lights, spawns, etc.)
  • ✓ Brush Entities - Write brush entities (doors, triggers, etc.)
  • ✓ Static Props - Write prop_static entities
  • ✓ Overlays - Write info_overlay entities
  • ✓ Cubemaps - Write env_cubemap entities
  • ✓ Details - Write func_detail entities
  • ✓ Areaportals - Write func_areaportal entities
  • ✓ Occluders - Write func_occluder entities
  • ✓ Ladders - Write func_ladder entities
  • ✓ Vis Clusters - Write func_viscluster entities
Advanced Entity Options
  • ✓ Fix Entity Rotation - Fix instance entity brush rotations for Hammer
  • ☐ Force Manual Areaportal Mapping - Force manual entity mapping for areaportals
  • ☐ Merge Detail Brushes - Merge touching func_detail brushes into one entity
Checkboxes marked with ✓ are enabled by default. Uncheck them to disable that entity type.

​
Workflow

​
Basic Decompilation

1

Add BSP Files

Click Add Files and select one or more .bsp files, or click Add Folder to add all BSP files from a directory.
2

Configure Options (Optional)

Adjust settings in the configuration tabs if needed. Default settings work well for most maps.
3

Start Decompilation

Click Decompile to begin processing.
4

Monitor Progress

The progress bar and status log show decompilation progress. Green messages indicate success, red messages indicate errors.
5

Open VMF Files

Once complete, VMF files are saved to the output location. Open them in Hammer Editor to view and edit.

​
Batch Decompilation

Decompile multiple maps with the same settings:
1

Add Multiple Files

Use Add Files to select multiple BSP files, or use Add Folder to add an entire directory.
2

Set Output Directory

Select Custom Output and choose a directory where all VMF files will be saved.
3

Configure Settings

Set your preferred options. These settings apply to all files in the list.
4

Decompile All

Click Decompile to process all files in the queue.

​
Selective Entity Decompilation

Decompile only specific parts of a map:
1

Add BSP File

Add the BSP file you want to decompile.
2

Configure Entity Options

Go to the Entity Options tab and uncheck entity types you don’t want.For example, to decompile only world geometry:
  • Uncheck Point Entities
  • Uncheck Brush Entities
  • Uncheck Static Props
  • Keep World Brushes checked in the Brush Options tab
3

Decompile

Click Decompile to generate a VMF with only the selected elements.

​
Troubleshooting Failed Decompilation

If a map fails to decompile or produces incorrect results:
1

Enable Debug Mode

Go to the Advanced tab and enable Debug Mode.
2

Try Different Brush Mode

Go to the Brush Options tab and try a different brush mode:
  • If BRUSHPLANES fails, try ORIGFACE
  • If ORIGFACE fails, try SPLITFACE
3

Check Game Detection

Go to the Other Options tab and verify the App ID:
  • Click List App IDs to see all games
  • Set the correct App ID if auto-detection failed
4

Review Logs

Check the status log for error messages. Debug mode provides more detailed information.

​
Presets

The GUI allows you to save and load configuration presets for different use cases.

​
Common Presets

All options enabled, BRUSHPLANES mode.Best for:
  • Complete map decompilation
  • Editing and studying maps
  • Creating modified versions
Only world brushes and displacements, no entities.Best for:
  • Extracting map layout
  • Creating simplified versions
  • Performance testing
Settings:
  • Entity Options: All unchecked
  • Brush Options: World Brushes ✓, Displacements ✓
Full decompilation with debug information.Best for:
  • Troubleshooting issues
  • Understanding decompilation process
  • Reporting bugs
Settings:
  • Advanced: Debug Mode ✓
  • All other defaults
Skip protection checks and optional features for speed.Best for:
  • Batch processing many maps
  • Processing known-unprotected maps
  • Quick previews
Settings:
  • Other Options: Skip Protection Check ✓
  • Other Options: Write Cameras ☐
  • Other Options: Write Visgroups ☐

​
Keyboard Shortcuts

ShortcutAction
Ctrl+OAdd Files
Ctrl+Shift+OAdd Folder
Ctrl+DDecompile
DeleteRemove Selected Files
Ctrl+ASelect All Files
Ctrl+QQuit

​
Tips

Save Time with Defaults: The default settings work well for most maps. Only adjust options when you need specific behavior.
Use Custom Output: When decompiling multiple maps, set a custom output directory to keep VMF files organized.
Preview with Geometry Only: To quickly preview a map’s layout, disable all entities and decompile just the world geometry.
Extract Resources: Enable “Unpack Embedded Files” to extract custom textures, models, and sounds from the BSP.

​
Limitations

The GUI uses the same decompilation engine as the CLI. All limitations that apply to CLI decompilation also apply to the GUI.
  • Some maps with heavy protection may not decompile correctly
  • Very large maps may take significant time to process
  • Complex custom entities may not be perfectly reconstructed
  • Not all Source engine games are supported (see Supported Games)

​
Error Messages

​
Common Errors

“Failed to read BSP file”
  • The file is corrupted or not a valid BSP file
  • Try opening the map in-game to verify it works
“Unknown game/app ID”
  • Game detection failed
  • Manually set the correct App ID in Other Options
“Protected map detected”
  • The map has decompile protection
  • Results may be incomplete or incorrect
  • Try enabling “Skip Protection Check” (may not help)
“Out of memory”
  • The map is too large for available memory
  • Increase Java heap size: java -Xmx4G -jar bspsrc.jar
  • Try disabling some entity types to reduce memory usage

​
Next Steps

After decompiling a map:
  1. Open the VMF file in Hammer Editor
  2. Check for any errors or warnings
  3. If using a face-based brush mode, you may need to clean up geometry
  4. Save the VMF and compile it to test functionality
  5. Make your edits and modifications
For more information on configuration options, see Configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us