VMF Instances

From Valve Developer Community
Jump to: navigation, search
English (en)中文 (zh)

VMF map instances are a simple yet powerful new tool for map editing. Basically, they let you reference one .VMF into another. Any changes to the file will be reflected in all instances.


.VMF Prefabs

Map data that will need to be placed repeatedly in your maps are convenient to save and edit as instances. This is similar to how Prefabs work. Basically, you collect entities that are meant to work together into a file, then reference that file into your map in as many locations as you like. Each instance gets it own "name fixup", so all logic still works when the file is referenced into another map. This is how the alarmed car lot in The Parish is set up. Also the town in Hard Rain is referenced into the forward and back version of map, allowing a single change to be reflected in both.


Instances may also be used to divide a large, unwieldy map into several smaller, easier to manage .VMFs. This also simplifies workflow when multiple authors are working on a single map simultaneously.

Working off grid

If you have a portion of a map that needs to be at a non-orthogonal angle, you can keep it on-grid inside a separate file. If you then instance the file into your main map, then rotate the instance, you can continue to enjoy the benefits of on editing on the grid for each file.

Updating a map for L4D2

If you have a L4D map that you'd like to update to run with L4D2 while maintaining a version that is compatible with L4D1, instances are the best way to go. You could save out a new version, but this "fork" can become a hassle to support, as common fixes or changes need to happen in two places. Alternatively, you could simply add the new content into a "L4D2" visgroup, but that approach isn't very scalable. It's error-prone, and the slightest bit of complexity can make it unwieldy.

Instead, you can now keep the common assets in one file that remains compatible with L4D1, and the "delta" for L4D2 in another file. To set this up, you will need to create a new L4D2 .VMF map, then place an instance entity that will reference the existing L4D1 map into it, thereby automatically importing the contents of the older map before each compile. Simply add your new L4D2-only entities to the L4D2 .VMF, and you can provide a version of your map for both games from a non-duplicated set of source data. The nice thing about this is that any updates you make in the older L4D1 map are automatically reflected in the new L4D2 version of the .VMF.

Let's run through using instances with one of the beginning tutorial levels.

Adding a new Instance

To start, go ahead and create a new level in Hammer from the menu: File > New

Save it as:


We will be referencing another file in the same folder, so it's important to keep it in the correct place.

Next, we need to place an entity called a func_instance that will represent the map data you wish to reference.

Go into the Entity tool Mt-entities.png and select "func_instance" from the Objects drop-down menu on the right hand side of the Hammer window.

Placing a func_instance at the origin

L4D2 instance 1place3.png

Place it at the origin (coordinates 0,0,0) by left-clicking where the dark cyan lines intersect in the Top (upper right) viewport. You can verify it's position from the right side of the status bar.

Since it's a point entity, you can place a func_instance anywhere, but placing it at the origin and with no rotation allows you to Cut and then Paste Special objects between the base map and instance very accurately. This is very handy when tightly coordinating between maps, which you'll find yourself doing a lot.

Next, select the func_instance with the arrow selection tool and open its properties by pressing Alt+ Enter.

Click on the VMF Filename field and click the Browse... button. Go ahead and select one of the finished tutorial files in the same folder:


L4D2 instance 2properties.png

If the name doesn't appear, make sure the .VMF you're editing is saved to the same folder. You can also try typing in the filename manually.

Note.pngNote: Instances must refer to VMF files that are either in the same folder as the main file or in a sub-folder. Paths are always relative.
Note.pngNote: Instances that are used by multiple files are usually placed in a sub-folder named "instance" to avoid confusion.
Instance with .VMF content loaded

The contents of tutorial05 are now referenced into your new map, and are tinted in yellowish-orange to distinguish the referenced content from other content that may be in the currently open .VMF.

Even though the currently open .VMF technically only contains one entity, the func_instance, when you compile your map, all instances will be temporarily "flattened" and included in your map. They appear in the final .BSP just as if they had been in the map itself.

Although you now need two VMF source files to create your level, you've provided yourself with much greater editing flexibility, as you can keep content in separate buckets. As we shall see in the next several tutorials, this will become very handy as you add support for multiple gamemodes or do other things that make your maps more complex.

Fixup naming and viewing options

Take a look at the Properties dialog again.

Putting text in the Fix Up Name field allows you to specify a prefix or suffix to nameable entities. This is very handy if you want to have multiple func_instances referencing the same file while targeting the entities separately. In fact, if you do not specify a fixup name, one will be provided automatically, thus allowing you to place multiple instances while still being able to trigger the entities inside individually.

Let's keep the fix up blank for the purposes of this tutorial but a good example can be found in the car alarm lot example in the Deadline2 add-on.

Tip.pngTip:You can toggle the tint as well as the overall visibility of instances from the Hammer Instancing menu. Let's keep it on the default setting for now since we will soon be mixing instanced and non-instanced objects.


Edit instance

Go ahead and select the instanced geometry and open the properties window again.

Along the bottom, you'll notice a button titled Edit Instance.

This will open the instance .VMF for editing if it isn't already while maintaining the exact same relative camera coordinates between the two files. Any changes you make will be reflected in the new map as you switch between them.

For our purposes, though, we want to "upgrade" a legacy map, and will want to keep out changes in the new file while avoiding editing the instance as much as possible. We'll touch on this again later, in particular when going over the multiple gamemode support entity info_gamemode. Let's move on to the L4D2-specific weapon spawning entities.