VBSP

VBSP is the command-line tool that compiles a raw VMF file into Source 1's BSP format. It is generally followed by VVIS and VRAD.

VBSP will:

Convert brushes into polygons.
Generate visleaves.
Generate detail props.
Swallow most internal entities into the world.
Replace specular materials with patched versions that link to the nearest cubemap. Also generate blank cubemap textures (some custom VBSPs may skip this by default).
Report leaks as LIN files.
Embed the entity block.
Merge groups of static props sharing the same material. (in all games since )

While the resulting BSP file can be played directly it has no visibility control (poor performance) and no lighting.

Bug:In non-Left 4 Dead engine branch games, MDL files that have the IDST1 header will fail to load for VBSP, see VRAD's bugs.

Bug:Smoothing groups are not properly written for func_detail brush faces. The code for this fix can be found in

pull request 391.
Fixed in the Slammin' Source Map Tools, Garry's Mod, Mapbase and VBSP++. (tested in: Source 2013)

Bug:Vanilla VBSP doesn't recognize custom lightmapped shaders, and thus it won't allow VRAD to generate lightmaps for them.
Fixed in the Slammin' Source Map Tools, Mapbase and VBSP++. (tested in: Source 2013)

Syntax

vbsp.exe [options] <mapname>.vmf

Note:The commandline.cfg file can be used to inject per-map command-line options.

Example

"C:\Games\Half-Life 2\bin\vbsp.exe" -onlyents "sdk_trainstation_01.vmf"

This will re-embed the entity block without affecting the world geometry.

Command-line options

Common

Note:-onlyents and -keepstalezip will mark the map as stale by embedding the file stale.txt into the BSP. Loading stale maps in the engine will cause a "This map is not final!!" warning message in the console.

-v

-verbose

Turn on verbose output (also shows more command-line options if used without any other parameters).

-onlyents

Only import the entities from the VMF. Brushes and internal entities are not modified. Brush Entities' boundaries will not be modified, however, their keyvalues will be. Conserves existing lighting and VIS data.

-onlyprops

Only update static and detail props (i.e. the internal entities). Does not generate a .prt file, making VVIS fail!

-glview

Writes glview data to the VMF's directory. -tmpout will cause the files will be written to \tmp instead.

-nodetail

Removes func_detail brushes. The geometry left over is what affects visibility.

-nowater

Get rid of water brushes.

Confirm:Does this affect CONTENTS_SLIME, or only CONTENTS_WATER?

-low

Run as an idle-priority process.

-vproject <directory>

Override the VPROJECT environment variable.

-game <directory>

Specify the folder of the gameinfo.txt file.

-insert_search_path <directory>

Includes an extra base directory for mounting additional content (like gameinfo.txt entries). Useful if you want to separate some assets from the mod for whatever reason.

-embed <directory> (in all games since )

Embed the contents of <directory> in the pakfile lump.

-instancepath <directory> (only in )

Overrides InstancePath key in gameinfo.

Advanced

-autoviscluster <integer> (in all games since )

Todo: Used on dz_sirocco, found in scripts/mapautocompile.txt.

-novconfig

Don't bring up graphical UI on vproject errors.

-threads <integer>

Control the number of threads VBSP uses. Defaults to the number of processors/cores (times 2 for Hypertheading/SMT CPU's) on your machine.

-verboseentities

If verbose is enabled, this disables verbose output for submodels.

-noweld

Don't join face vertexes together.

-nocsg

Don't chop out intersecting brush areas.

-noshare

Emit unique face edges instead of sharing them.

-notjunc

Don't fixup any t-junctions.

-allowdetailcracks

Don't fixup t-junctions on func_detail.

-nodrawtriggers

Compiles all triggers as if they were using the Nodraw texture. Only affects triggers using a texture with %CompileTrigger.

-noopt

By default, VBSP removes the 'outer shell' of the map, which are all the faces you can't see because you can never get outside the map. -noopt disables this behavior.

-noprune

Don't prune neighboring solid nodes.

-nomerge

Don't merge together chopped faces on nodes.

-nomergewater

Don't merge together chopped faces on water.

-nosubdiv

Don't subdivide faces for lightmapping.

-micro <float>

Warn when brushes are output with a volume less than this number (default: 1.0).

-fulldetail

Mark all detail geometry as normal geometry (so all detail geometry will affect visibility).

-alldetail (only in )

Convert all structural brushes to detail brushes, except func_brush entities whose names begin with structure_.

-leaktest (not in )

Stop processing the map if a leak is detected. Regardless of whether or not this flag is set, a leak file will be written out as <mapname>.lin, and it can be imported into

Hammer.

-noleaktest (only in )

Disables leaktest, as it is enabled by default.

-bumpall

Force all surfaces to be treated as if they were bump mapped (generating four lightmaps for the surface instead of one), regardless of if they actually are.

-snapaxial

Snap axial planes to integer coordinates.

-block <X_index> <Y_index>

-blocks <minX_index> <minY_index> <maxX_index> <maxY_index>

Limits compilation to only the specified sectors of the map's coordinate grid. This parameter accepts the indices of these blocks, not Hammer units. For default block size 1024x1024: from -16 to 15 where -block 0 0 will be coordinates between 0 0 -16384 and 1024 1024 16384. Using these parameters almost always results in leaks, as the map is literally cut at the world block boundary. In this case, compile the map using VBSP only.

-blocksize <integer> (in all games since ) (also in )

Control the size of each grid square that VBSP chops the level on. Default is 1024.

Directly affects the grid calculation for -block and -blocks. Changing this value scales the size of each sector, requiring you to recalculate block indices based on the new size.

-dumpstaticprops

Bug:The VBSP help lists this parameter in the plural (-dumpstaticprops), but the code only handles the version without the "s".

Dump static props to staticprop###.txt.

-dumpcollide

Write files with collision info.

-forceskyvis

Enable vis calculations in 3D Skybox leaves.

Tip:Use this if the 3D skybox room can be accessed without noclip.

-luxelscale <float>

Scale all lightmaps by this amount (default: 1.0).

-minluxelscale <float>

Lets you limit the minimum luxel scale in your map.

-maxluxelscale (only in )

Lets you limit the maximum luxel scale in your map.

-lightifmissing

Force lightmaps to be generated for all surfaces even if they don't need lightmaps.

-localphysx

Todo: Currently unknown.

-keepstalezip

Keep the BSP's zip files intact but regenerate everything else.

-visgranularity <vector3> (in all games since ) (also in )

Force visibility splits # of units along X, Y, Z.

-replacematerials

Substitute materials according to cfg/materialsub.cfg.

-FullMinidumps

Write large minidumps on crash.

-novirtualmesh

Fix physics entities falling through displacements in older versions of Source at cost of bigger BSP size.

-xbox

Treat %CompileTrigger surfaces as nodraw, and treat %CompileWater surfaces as having %CompileNoLight (but not %CompileSlime). Implies -nodrawtriggers.

-nodefaultcubemap (only in )

Disables automatic skybox cubemap generation.

-defaultcubemap (only in )

By default in Mapbase "dummy" cubemaps are not generated during map compilation but can be forced to generate again by this parameter.

-allowdynamicpropsasstatic (only in )

Allow all models with the 'static' flag in the model viewer to be used on prop_static, even when their propdata doesn't contain 'allowstatic'.

Warning:This will compile dynamic models with animation to Static too, which may causes visual glitches.

-dxlevel <integer> (removed since )

Don't include entities whose mindxlevel and maxdxlevel KVs preclude this dxlevel. This is the only way that internal entities which collapse to worldspawn (such as func_detail and func_ladder) will respect these keyvalues.

Static Prop Combine

(in all games since )

-StaticPropCombine: Merges static props together according to the rules defined in scripts/hammer/spcombinerules/spcombinerules.txt. This lowers the number of draw calls, increasing performance. It can also be used to lower the number of static props present in a map. See Static Prop Combine.

-StaticPropCombine_AutoCombine: Automatically generate static prop combine rules for props that VBSP deems should be combined.
Note:This does not write to spcombinerules.txt.

-StaticPropCombine_ConsiderVis: Instead of using the distance limit, combine all props in the group that share visclusters.

-StaticPropCombine_SuggestRules: Lists models sharing the same material that should be added to spcombinerules.txt.

-StaticPropCombine_MinInstances <integer>

Set the minimum number of props in a combine group required to create a combined prop.

Tip:Valve had this set to 3 for the new Dust 2.

-StaticPropCombine_PrintCombineRules

Confirm:Prints the combine rules? Hasn't been working for me.

-StaticPropCombine_ColorInstances

Confirm:Does this color the instances?

-KeepSources: Don't delete the autogenerated QCs and unpacked model files after finishing.

-CombineIgnore_FastReflection: Combine props, even if they have differing Render in Fast Reflections settings.

-CombineIgnore_Normals: Combine props, even if they have differing Ignore Normals settings.

-CombineIgnore_NoShadow: Combine props, even if they have differing Disable Shadows settings.

-CombineIgnore_NoVertexLighting: Combine props, even if they have differing Disable Vertex lighting settings.

-CombineIgnore_NoFlashlight: Combine props, even if they have differing Disable flashlight settings.

-CombineIgnore_NoSelfShadowing: Combine props, even if they have differing Disable Self-Shadowing settings.

-CombineIgnore_DisableShadowDepth: Combine props, even if they have differing Disable ShadowDepth settings.

Nonfunctional

-linuxdata: Force it to write physics data for Linux multiplayer servers. (It will automatically write this data if it finds certain entities like info_player_terrorist, info_player_deathmatch, info_player_teamspawn, info_player_axis, or info_player_coop.)
Deprecated:(removed since ) All modern branches of Source use the same physics data on all platforms.

-nolinuxdata: Force it to not write physics data for Linux multiplayer servers, even if there are multiplayer entities in the map.

-virtualdispphysics: Use virtual (not precomputed) displacement collision models

Commented-out

The following options have been commented out with #if 0 in the VBSP source code, but still function if VBSP is recompiled with these uncommented.

Both options are restored in VBSP++ and Garry's Mod's VBSP.

-maxlightmapdim <float>: Default 32. Set the maximum size a brush face's lightmap can be. VBSP will subdivide faces each time a brush face exceeds one minus this many luxels. Displacements do not get subdivided, but are still limited to this minus one times four.
Warning:Going above the default of 32 will result in the lightmap not loading in engine versions other than .

-defaultluxelsize <float>: Default 16. Set the default luxel scale that is used if a brush face's lightmapscale is set to 0 or is missing.
Important:Editing the face attributes of a face with a luxel scale of zero in Hammer or Hammer++ will result in the luxel scale being rounded up to 1!

Console output

Todo: Add descriptions for other VBSP outputs (WriteBSP, PruneNodes, ProcessBlock_Thread, etc).

VBSP prints various information about the compile process to the console. Note that output from older versions of the tool can be different.

Patching WVT material: material path to patched WVT material: The map contains WorldVertexTransition materials that are being used on non-displacement faces. VBSP patches these materials to use a different material shader (such as LightmappedGeneric) so that they properly render on these map faces.
FixTjuncs...: T-junctions are created when func_detail brushes touch world geometry. To avoid visual cracks or seams, VBSP fixes up these T-junctions.
Placing detail props : 0...1...2...3...4...5...6...7...8...9...10: Detail props are being placed in the map.

Navigation

VBSP

Contents