propcombine

Propcombine

Inspired by the feature in CSGO, the postcompiler includes the ability to nearby static props together into a single combined model. This can significantly improve performance at the cost of file size, by avoiding the need to set up rendering for each prop. The system uses the source files for the models, generates new SMDs and QCs, then calls studiomdl on the fly.

Models are cached and reused for the next compile of the map, so usually only a few changed groups need to be built.

Source Files

To generate new models, the geometry and physics mesh SMDs are required. If the originals are available, the propcombine_qc_folder config option can be used to specify the source location. Otherwise, an included copy of Crowbar will be used to decompile each model as required. This initially will take some time, but once done the decompiled copies will be reused for future compiles.

Eligable Groups

Only some props can be combined with each other. During rendering, each material in a prop is mostly drawn seperately, so there is little benefit to merging props with dissimilar materials. For that reason, only props with matching skins will be merged (taking into considation which skin number is chosen). To preserve the same appearance, props also have to have most other keyvalues match exactly - tint, shadow options, etc. However, lighting origin and fade distances are ignored entirely since they're not really meaningful for a group of props. The model scale and collisions can be set individually per-prop, and will be combined as appropriate. In particular, using a bounding box collision can be useful to simplify the collision for each sub-prop.

Manual Grouping

To specifically indicate props that should be grouped together, two compiler-only entities can be used:

• comp_propcombine_volume is a brush entity, textured with tools/toolspropcombine. Props are included if their origin is inside any of the brushes. The volume is easier to use, but will count towards the brush/face/etc limits since VBSP processes it before the postcompiler can remove it.
• comp_propcombine_set is a point entity. Props get included if their origin is inside the (potentially rotated) bounding box specified by the min/max offsets. This is more annoying to use, but is entirely free making it better suited for instances and the like where one configuration gets reused multiple times.

Both can be intermixed, and have similar keyvalues.

• "Name": If two group entities have the name set to the same value, they will be treated as the same group. This is useful if you want to describe a more complex shape. In addition, if a group entity fails to match any props, the name will be written to the compile log.

• "Model"/"Skin": Normally no filter is needed (since props are just skipped if there isn't at least propcombine_min_cluster matching props inside the group), but if set these are used to look up the materials used for this model. Then the group entities only apply to models with those materials.

Group entities are processed smallest to largest, allowing a larger group to be placed around a smaller one.

Automatic Grouping

Instead of or in addition to manual grouping, the compiler can also search for props close together in order to compile them. To enable this, set propcombine_auto_range in the configuration to some distance. The compiler will find props with origins at least this close together, then chain them together into groups. This can be fine-tuned further with propcombine_max_auto_range, to prevent creating massively long lines of props. Excessively large groups are likely to defeat visleaf culling, rendering almost all of the time.

If both manual and automatic grouping are used, the manual groups are performed first and override the automatic groups. In addition, propcombine_min_cluster_auto allows setting how many props must be present in a group to make it actually be combined together. This can be set higher than the similar limit for manual groups, to reduce wasted effort.

Debugging the Grouping Process

Since the result should ideally look identical to before combining, it can be tricky to identify if grouping has done anything to the map.

• For a general overview, the compiler outputs a number of statistics during grouping, and even more detail in the log file.
• Ingame, the r_colorstaticprops 1 ConVar can be set to randomly tint each prop a different colour.
• Running the postcompiler with the --dumpgroups parameter will cause it to produce a mapname_propcombine_reject.vmf file. This map contains every prop that was not combined, allowing you to look for groups that should have been found.