VisGroups and Visibility Control in the Editor

(December 17, 2017)

Levels get cluttered. It's just a simple fact of the matter. As you begin to stack entities and populate your level with weapons, props, decals, and other such detail, it can get a bit clumsy to work with. On slower machines, a lot of models to render can also mean a lot of slowdown.

VisGroups are Worldcraft's (and editors based on it) way of sorting through the clutter. A VisGroup is a user-definable set of objects that can be hidden or shown at will, broadly speaking. You can create a VisGroup, assign any number of brushes, models, or entities to it, and then hide the VisGroup whenever you like. The objects won't get shown in the editor, and (automatically in Hammer 4.0 and later and if specified in Worldcraft and J.A.C.K.) they won't get compiled into the final map.

(VisGroups have nothing to do with VIS, one of the compile tools your map needs to run through to be playable in-game.)

Exploring VisGroups further

VisGroups are created, toggled, and otherwise manipulated through the Filter Control toolbar. In Worldcraft and J.A.C.K., this appears as a box along the right of the editor with four buttons at the bottom. From left to right:

• Apply/Assign: Assigns the selected object to the selected VisGroup.
• Edit: Brings up the Edit VisGroups dialog, which lets you make VisGroups and delete ones already present.
• Mark: Selects all items within the selected VisGroup.
• Purge: Deletes empty VisGroups within the listing. Hammer 4.0 removes this button as empty VisGroups are automatically removed.

This is largely true of Hammer 4.0 and later's Filter Control toolbar, though with the addition of two tabs, "User" and "Auto". Hammer 4.0 also adds two arrow buttons for sorting your VisGroups within the listing, as well as a "Show" button for temporarily disabling VisGroups entirely and displaying the entire contents of the map file.

VisGroups are saved differently in every map format you'll run across. When maps are saved and exported in the standard MAP format, VisGroups won't get saved with them, as VisGroups are Worldcraft-specific and MAP is meant to be a generic format supported by a variety of mapping tools. RMF files support VisGroups, though objects in RMF files can't be added to multiple VisGroups at once. VMF and JMF (used by Hammer 4.0+ and J.A.C.K., respectively) support adding objects to as many VisGroups as you'd like.

You can drag VisGroups around in the Filter Control toolbar to manipulate and sort them. Dragging one onto another will merge them, while dragging a VisGroup out of the toolbar will delete it. You can also sort VisGroups in a hierarchy, with parent and child VisGroups. That way, you can hide a large amount of neatly-sorted items with a single click. To make a VisGroup a child of another VisGroup, drag the child onto the parent like you're about to merge them, but hold down the right mouse button instead of the left.

User VisGroups and Auto VisGroups

If you're mapping for a Source game, you already have VisGroups at your disposal. These VisGroups are automatically made when certain types of objects appear in the world, and are sorted hierarchically. Tool brushes, such as those textured with tools/toolsclip, are an entire category of VisGroup. Water and skybox brushes are other examples of Auto VisGroups at your disposal. To view them, click the "Auto" tab at the top of the Filter Control toolbar. The "User" tab shows you your own VisGroups, of course.

Creating and using VisGroups

Creating a VisGroup and adding items to it is a rather simple process. The process outlined below will work for any Worldcraft-like editor, though it'll look slightly different in each one. No worries if your editor appears different than the screenshots below.

For our example map, we'll be adding the ivy decals around a set of free-standing arches to their own VisGroup.

1. From the Filter Control toolbar, click the "Edit" button. Make a new VisGroup in the window that appears.

The Edit VisGroups dialog will appear, listing the VisGroups already available in the map. Don't worry if none are available. Click the "New group" button at the bottom of the dialog. A new VisGroup literally called "new group" will appear at the bottom of the list. Select it.

You'll be given the ability to rename it and pick the color that objects that get added to that VisGroup will get drawn with in the 2D viewports. Since we'll be adding the ivy on the arches to it, we'll call this VisGroup "ivy".

2. Select the items to be assigned to the VisGroup.

Of course, to manipulate objects in the editor, you'll need to have them selected. You can either Ctrl+click on them in the 2D or 3D viewports, or (helpful if you're selecting all entities of a single kind) use the Entity Report dialog under "Map" > "Entity Report..."

3. Pull up the Entity Properties dialog and switch to the VisGroup tab.

You can do this in any number of ways, but for large groups of objects, the easiest is to go into the "Edit" menu and select "Properties" from the list. The VisGroups tab should be the very last tab along the top.

4. Check the VisGroup you made in Step 1 at the bottom of the list.

The selected entities will be assigned to the "ivy" VisGroup. Click "Apply" and close out of the Properties dialog.

Notice that the ivy is gone in the above screenshot. The "ivy" VisGroup is unchecked, and so the decals in the VisGroup are hidden.

A practical application for VisGroups

I'm breaking out of the narrative voice I usually use for guides to tell you of one thing I find VisGroups especially useful for: hiding sprites in the editor. Adding glow sprites to light sources is a good way to add realism and detail to a scene, but because of a rendering bug, they tend to obfuscate what's around them. Using VisGroups, I can select all of the sprites in a scene, assign them to a VisGroup, and hide them when I need to work with the actual light entities.

A feature available in Hammer 4.0+, though sadly not Worldcraft and J.A.C.K., is the Move to VisGroup dialog in the View menu. To use it, select the items you want in the VisGroup as normal and pull up the dialog. You can create a new VisGroup, assign the items to it, and hide them if desired, all in one dialog box. This is much easier and more efficient than the above process, but since it's only available in Hammer 4.0 and up, its use is limited to Source maps.

How Valve uses VisGroups

There's a lot to gleam from the map sources available with the Source SDK, including how Valve made use of the VisGroups feature in their own levels. We'll be taking a look at two different sources, sdk_tr_dustbowl.vmf for Team Fortress 2 and cs_militia.vmf for Counter-Strike: Source.

sdk_tr_dustbowl.vmf

Dustbowl's source file contains so many VisGroups that they won't all fit in the screenshot. It's a bit difficult to show exactly which items are in which VisGroup, but given the names, Valve used VisGroups for tree models (new_trees), grass (grass_models), shrubs (shrubs_sage), the gravel lining the paths through the levels, soundscapes, func_nobuilds, and other such detailing. It's helpful to be able to hide detailing before compile for speed and gameplay testing purposes.

cs_militia.vmf

Militia has comparatively few visgroups, though Valve uses them similarly for general detailing. Notably, there's also VisGroups for terrorist and counter-terrorist spawn entities (ctspawnents and tspawnents). Given that both spawn in rather cramped quarters (the terrorists inside the home and counter-terrorists in the woods nearby), it'd be helpful to be able to work on those areas without the spawn entities scattered around and cluttering the room.

VisGroups are extremely useful for compartmentalizing and sorting through the clutter of entities and detail that comes with building a map.