View source for Static Prop Combine

{{LanguageBar}}

'''Static Prop Combine''', or informally speaking "autocombine", is a feature in {{csgo|4}}'s [[VBSP]]. It allows VBSP to merge together multiple static props into a single static prop, either automatically or with user-defined rules. This has the effect of both reducing the overall number of static props in the map, while also reducing the number of performance-eating draw calls. To enable it, run VBSP with <code>-staticpropcombine</code>.
{{Tip|In {{src|4.1}}, there is one draw call per model per material. By combining models sharing the same materials, less draw calls are performed, which greatly helps optimization. Valve has stated that Nuke runs 40% faster after they implemented static prop combine.
:{{Note|Due to the fickle nature of VBSP's prop combination feature, it may be better to use {{TeamSpen|4.1}}. Alternatively, static prop models can be combined manually.}}
}}
{{tip|{{hammerpp|2}} can merge models together using it's built-in [[Hammer++/Propper++|Propper++]] tool.}}

== Operation ==

Static prop combine performs the following operations:
;Identify props to be combined.
: It either does this according to the rules specified in <code>spcombinerules.txt</code> or automatically based off of model use. 
: {{Note|<code>-staticpropcombine_considervis</code> is a useful command which makes it take into account visclusters when combining.}}
;Scan the [[QC]] source for each model it's combining, and extract certain info.
: This includes the names and locations of reference and physics meshes, the model's upaxis, the model's scale, and whether it's concave or not.
: It locates the QC by reading the <code>qc_path</code> keyvalue from the model, which is '''always''' considered relative to the game's content directory - even if it's an absolute path!
: {{Note|There are many restrictions relating to this step, see [[Static Prop Combine#Usage|Usage]] for details.}}
;Use that info, plus a [[Static Prop Combine#Stub QCs|stub QC]], to generate its own QC.
: [[$contentrootrelative]], [[$appendsource]], and [[$addconvexsrc]] are all new commands designed specifically for static prop combine, the latter two being ways to "add" geometry to a model with an arbitrary offset, rotation, and scale.
;Call [[studiomdl]] to compile this generated QC into a combined model.
: Combined models will always contain <code>_autocombine_</code> in their name.
;[[BSPZIP]] all combined models into the BSP's pack.
: {{Tip|Running with -keepsources will stop static prop combine from deleting its generated QCs and unpacked model files.}}

== Usage ==
=== VBSP Options ===
See [[VBSP]].

=== Hammer Options ===
Props that differ in the below keyvalues will '''NOT''' be combined, unless manually overriden with the appropriate VBSP option:
*'''Render in Fast Reflections''' (<code>-combineignore_fastreflection</code>)
*'''Ignore Normals''' (<code>-combineignore_normals</code>)
*'''Disable Shadows''' (<code>-combineignore_noshadows</code>)
*'''Disable Vertex lighting''' (<code>-combineignore_novertexlighting</code>)
*'''Disable Flashlight''' (<code>-combineignore_noflashlight</code>)
*'''Disable Self-Shadowing''' (<code>-combineignore_noselfshadowing</code>)
*'''Disable ShadowDepth''' (<code>-combineignore_disableshadowdepth</code>)
In addition, you can manually ''disable'' static prop combine for individual props with the '''Disable Prop Combine''' keyvalue.

=== Prop Setup ===
In order to use a prop with static prop combine, you MUST have the source files for the prop! 
{{Note|To use Valve props, you must recompile them under a different name - otherwise, the version of the prop that is packed in the VPK would overwrite your version.}}
The QC for the prop must be compiled from the game's content folder. For {{csgo|4}}, this should be <code>SteamApps/common/content/csgo/</code>. 
{{Tip|In reality, the location where it searches for content will always be <code>../../content/[-game name]</code>, relative to the bin folder. This can be useful to modders to know.}}


There are quite a few restrictions that are put in place. These include:
* Only the first <code>[[$body]]</code> is recognized.
* <code>[[$model]]</code> is not recognized.
* <code>[[$appendsource]]</code> and <code>[[$addconvexsrc]]</code> are not recognized.
* You can only use <code>[[$upaxis]]</code> '''Z''' or '''Y'''.

=== Rules Setup ===

Rules for static prop combine are defined in <code>scripts/hammer/spcombinerules/spcombinerules.txt</code>. It is a standard [[KeyValues]]-formatted text file. Each entry follows this format:
<source>
	"example_combined" //name of the combine group, used for the final model name in the level
	{
		// this is a stub qc that will be used to generate combined models
		"qc_template_path"	"scripts/hammer/spcombinerules/qc_templates/example.qc"
		
		// max models per cluster using these peers
		"cluster_limit" 8
		
		// don't cluster models greater than this far apart
		"distance_limit" 12

		// these are models that can combine with each other
		"peers"
		{
			"models/examples/example_A.mdl" ""
			"models/examples/example_B.mdl" ""
			"models/examples/example_C.mdl" ""
		}
	}
</source>

If you don't want to bother with creating rules, you can run <code>-staticpropcombine_autocombine</code>. However, this can cause issues if you do not have the source files for the models VBSP tries to combine.
{{Bug|The paths in the "peers" list MUST be written with forward slashes!}}

== Stub QCs ==
'''Stub QCs''' are [[QC|QCs]] or [[QCI|QCIs]] which contain a base template for the QCs which static prop combine generates. Generally, they should only include:
* [[$cdmaterials]]
* [[$surfaceprop]]
* [[$staticprop]]
* Any [[$texturegroup|$texturegroups]] used by the models. 
{{Tip|{{clr}}
* Static prop combine knows not to combine models using different skins.
* Since combined props cannot be listed in [[lights.rad]], [[$casttextureshadows]] can be applied to let this model cast [[Texture Shadows]].}}

=== Stub QC Example ===
<source>
$cdmaterials models\props\de_venice\venice_window_3

$staticprop
$surfaceprop "Plaster"

$texturegroup venice_window_3 {
	{ "venice_window_3" }
	{ "venice_window_3_lit" }
}
</source>

== See also ==

*[[VBSP]]