VBSP

VBSP is the tool that compiles a raw VMF file into the Binary Space Partition format. It is generally followed by VVIS and VRAD.

VBSP will:

• Convert brushes to 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
• Embed the entity block
• Merge groups of static props sharing the same material (only in )

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.  [todo tested in ?]

Launch options

Syntax

<vbsp.exe path> [options] <VMF File>

For example:

"Half-Life 2\bin\vbsp.exe" -onlyents sdk_trainstation_01

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

Common options

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). Use without any other parameters.

-onlyents

Only import the entities from the VMF. Brushes and internal entities are not modified. Conserves existing lighting 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.

-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>

Embed the contents of <directory> in the packfile.

Confirm:Which game introduced/removed this option, if any at all? Not present in any current games.

-instancepath <directory> (only in )

Overrides InstancePath key in gameinfo.

Advanced options

-autoviscluster # (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

Control the number of threads vbsp uses (defaults to the # of processors (times 2 for Hypertreading/SMT CPU's) on your machine).

-verboseentities

If -v is on, 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 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>

vbsp will 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).

-leaktest

Stop processing the map if a leak is detected. Whether or not this flag is set, a leak file will be written out at <vmf filename>.lin, and it can be imported into Hammer.

-bumpall

Force all surfaces to be bump mapped.

-snapaxial

Snap axial planes to integer coordinates.

-block # #

Control the grid size mins that vbsp chops the level on.

Bug:Causes VBSP to fail completely.  [todo tested in ?]

-blocks # # # #

Enter the mins and maxs for the grid size vbsp uses.

-blocksize <int> (in all games since )

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

-dumpstaticprops

Dump static props to staticprop*.txt.

-dumpcollide

Write files with collision info.

-forceskyvis

Enable vis calculations in 3D Skybox leaves.

-luxelscale <float>

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

-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 # # # (in all games since )

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

-replacematerials

Substitute materials according to materialsub.txt in content\maps.

-FullMinidumps

Write large minidumps on crash.

-novirtualmesh

Fix Physics entities fall through displacements at cost of bigger bsp size.

-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'.

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 <int>

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 Options

-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.)

-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

-xbox

Enable mandatory Xbox 1 optimisation.

Console output

Todo: Add description about every output (WriteBSP, other).

See also

• Map Compiling Theory
• Decompiling Maps