Source Engine Collision Tools
Blender (3.x+ / 4.x+) addon for generating and optimizing collision models for use in Source Engine games (ie. TF2, GMod, L4D2). Works best when combined with the Blender Source Tools.
Features
Some features are customizeable and can be tweaked via optional settings. There is also a "Recommended Settings" button that will automatically guess the best settings for you based on the currently selected, active object.
Generate Collision Mesh - Generate a Source Engine-compliant collision model for every currently selected object.
- Supports (optional) decimation, to automatically reduce the complexity of the resulting collision model
Generate UV-based Collision - Generates a collision mesh for the currently selected objects, based on each object's UV Map. Each UV island becomes a separate hull.
Generate Fractured Collision - This operator uses the Cell Fracture addon built into Blender to generate more accurate and performant collision meshes for Source Engine. However, unlike the above operator, it is intended to be used on individual props, not entire scenes at once. Works best on fully sealed objects with no holes or non-manifold geometry.
- Automatically creates a gap between collision hulls to prevent overlapping. The size of the gap is determined by the "Gap Width" setting
- Attempts to generate only the amount of hulls specified by the "Fracture Target" setting. ie. A "Fracture Target" of 4 will try to split up the model into only 4 parts.
- Note that the Cell Fracture addon needs to be enabled in your Blender preferences first!
Split Up Collision Mesh - Splits up selected collision models into multiple separate objects, with every part having no more than 32 hulls.
Merge Adjacent Similars - Merges convex hulls with similar adjacent hulls aggressively, lowering the final amount of hulls & producing a (potentially) less accurate, but more performant model. Similarity is based on the face count and volume of the hulls.
Remove Thin Hulls - Removes any convex hulls that are significantly smaller than all other hulls.
Force Convex - Forces all existing hulls in every selected collision model to be convex. Especially useful after using Blender's built-in Decimate modifier on an existing collision mesh, to ensure that any decimated hulls are still convex.
Remove Inside Hulls - Removes any hulls that are completely or almost completely buried inside other hulls.
Convex Cut - A combination of the Bisect and Convex Hull operators in Blender. This lets you cut up the model and at the same time convert the cut pieces into convex hulls. Can be found via the Mesh menu in Edit Mode.
Generate Source Engine QC - Automatically generate QC files for one or more collision model(s), allowing you to quickly compile them with batch compile tools out there (ie. Crowbar)
- Supports adding custom QC commands via a QC Override system. This allows you to, for example, add a custom "$scale" or "$surfaceprop" command to all generated QC files.
Update VMF - Updates a selected VMF file by automatically adding any partitioned/split-up collision models that haven't already been added to the map.
Export Hulls to Hammer .VMF - Converts hulls in the selected collision mesh(es) into Source Engine brush solids and exports them as a .VMF file that can be opened in Hammer.
Tips
- The UI for the addon is found in the "Object Properties" tab on the right-hand side of the Blender window. The UI's features are greyed out if you have no object selected, so select an object first in the 3D VIewport.
- Decimation (by the Generate Collision Mesh operator) generally makes the Merge Adjacent Similars operator less effective, but Decimation is much faster at reducing the final complexity of the collision mesh. However, Decimation will reduce the complexity uniformly across the entire model, whereas Merge Adjacent Similars tries to reduce complexity only where similar hulls are found.
- Merge Adjacent Similars is less effective on overly large, complex models. For best results, split up a large complex model into several (3-5) separate pieces first, and then use Merge Adjacent Similars on each individual piece.
- For the "Update VMF" feature, the very first part of your split-up collision mesh, ending in 'part_000.mdl', must already be in the VMF somewhere (such as in a prop_static). The operator scans the VMF for any part_000, and any that are found are used as a template for all the other parts. So you'll need to add that first part manually in Hammer first.
- Source Engine has a limit of 32 hulls per collision mesh. Going beyond 32 hulls can lead to severe lag during gameplay. The "Split Up Collision Mesh" and "Update VMF" features are handy for this. By splitting up your collision mesh into 32-hull parts, you prevent lag, and the Update VMF feature can add numerous (even dozens or hundreds) of parts automatically for you to a VMF file.
- To utilize the QC override system, add a string-based Custom Property (in the bottom of the Object Properties panel) to one split-up collision object in your Blender scene, with the property name starting with "$". Enter the value/parameters for this property. Then press the Copy QC Overrides button to copy this override to all other selected collision parts. These will be included in the resulting generated QC files.
What's New
2.0.0 December 29th, 2024
Bugfixes:
- Fixed bug that occured when Merge Adjacent Similars was used on a parented object. The resulting collision was being rotated incorrectly due to the parent.
- Fixed bug in the "Generate Collision via UV Map" operator that was triggering an error if used on a mesh with no UV map
Changes:
- After generating collision via any of the available methods, the resulting collision meshes are now set as 'selected' automatically.
- The UI has been generally improved and reorganized for improved usability. Among those UI changes are the following name changes below:
- Renamed "Generate Collision Mesh" operator to "Generate Collision via Faces"
- Renamed "Generate UV-based Collision" operator to "Generate Collision via UV Map"
- Renamed "Generate Fractured Collision" operator to "Generate Collision via Fracture"
- The "Generate via Fracture" method now actually reads and uses the Decimate Ratio setting. It was previously the only 'generate' method that didn't use it.
- The addon's UI is now organized into 3 collapsible sections - Generate, Cleanup, and Compile. When you're only using one set of these tools, you can simply hide the others now for better usability.
New features:
- Added new operator - Generate Collision via Bisection. This is a new method for generating collision which uses the Bisect tool behind-the-scenes to automatically slice up the model in a grid-like fashion. It's incredibly effective for individual prop and character models. For large scenes, I would recommend separating specific sections of the scene and then using this new operator on individual parts only, not the entire scene at once.
This Blender addon is an absolute game-changer! It makes generating and optimizing collision models for TF2, GMod, and L4D2 a breeze. The customizable settings and smart features like UV-based collisions and easy QC generation save tons of time. If you want your models to be Source Engine-ready in no time, get this addon now! Highly recommended!