Instance

An instance is a map file (.vmf) referenced inside another map through a func_instance, possibly aided by a func_instance_parms and/or func_instance_io_proxy.

Note:In order for instances to be compiled into maps, a GameData key must be present in gameinfo.txt pointing to the game's FGD file. Only Left 4 Dead 2 and later, along with Team Fortress 2, include this by default. Instances can be enabled in other games by adding this. A precompiler can also be used, as described below, but this can be more expensive if the instance is rotated at a non-orthogonal angle.

Note:In pre- Left 4 Dead 2 branches, instances have some broken or missing functionality: instance I/O system is unsupported, instances cannot be nested, displacements within an instance may not compile properly, and any env_cubemaps inside of an instance will not be compiled into the final map.

Note:Referencing an instance in your map will make the compiled map's mapversion keyvalue be taken from one of the instances instead.

Instances are helpful in many ways:

• They provide a more dynamic alternative to prefabs, as any changes to the instanced map will be reflected in all instances of it.
• They provide an alternative to visgroups, as they can be used to divide a large, unwieldy map into several smaller, manageable ones (that can even be worked on by multiple authors simultaneously).
• They provide a simple way to edit portions of a map that needs to be at a non-orthogonal angle. (Build the map on-grid inside a separate map, and then instance it into another map through a func_instance rotated at the correct angle). This is also cheaper than compiling the map with the rotated geometry directly in the base VMF, as it produces fewer brushsides (although this can subtly break QPhysics, such as making surfing impossible).
• They provide a way for maps to work on multiple platforms, such as Left 4 Dead and Left 4 Dead 2 versions of the same map.

Instance I/O

With func_instance_io_proxy

In Left 4 Dead 2 and later, instances can send and receive inputs and outputs. To use this functionality, a func_instance_io_proxy entity named proxy must be present and properly configured in the instance. To send an input to an entity within the instance, the following output would be used:

	My Output	Target Entity	Target Input	Parameter	Delay	Only Once
	<output>	<instance>	instance:<entity>;<input>	<none>	0.00	No

To receive an output from an entity in the instance, this output would be used on the func_instance:

	My Output	Target Entity	Target Input	Parameter	Delay	Only Once
	instance:<entity>;<output>	<other entity>	<input>	<none>	0.00	No

Note:Hammer should auto-complete these inputs and outputs. They may also appear as invalid, but will work fine in-game.

Without func_instance_io_proxy

Games before Left 4 Dead 2 do not have I/O proxies, so in those games (or if I/O proxies need to be avoided for another reason) instance I/O must be done manually. For inputs, the fixed up entity name can be referenced directly.

	My Output	Target Entity	Target Input	Parameter	Delay	Only Once
	<output>	<fixupname>-<entity>	<input>	<none>	0.00	No

For outputs, a logic_auto can use AddOutput to add the outputs to an entity within the instance.

	My Output	Target Entity	Target Input	Parameter	Delay	Only Once
	OnMapSpawn	<fixupname>-<entity>	AddOutput	<output> <target_ent>:<target_input>::0:-1	0.00	No

Note:If you are using HammerAddons, the comp_kv_setter entity should be used instead so the outputs are added at compile time instead of at runtime.

Note:Hammer will not auto-complete these inputs and will display them as invalid, but they will work in-game. If the instance's Entity Name Fix Up is set to Postfix, the fix up name and entity name should be swapped.

Manifests

Instances can be taken a step further with manifests. A manifest splits all of the contents of a map into special instances known as "sub-maps". Unlike regular instances, Hammer can seamlessly switch between sub-maps without having to open the VMFs separately. Sub-maps are treated as extensions of the map itself and cannot use name fixup or have any offset, although sub-maps are capable of being used in multiple manifests simultaneously.

Manifests can be helpful in many ways:

• They allow multiple people to work on a map at the same time.
• They help protect a map against corruption, as problems with a VMF are limited to a single sub-map.
• They can be used to assign user-friendly names to different areas of a map.
• They can make a map's source files easier to track in version control software like Git.

A manifest can be created in the "Instancing" menu.

Note:Manifests are not supported under Hammer++. Instead, the instance tools have been expanded to be more feature complete with manifests. Tools -> Convert Instance to Selection can be used to convert selections to instances. Middle clicking an instance in 3D view or clicking Edit Instance (preview) in object properties will allow editing the instance with the main map shown relative in the views.

Warning:Manifests should be mostly functional in any^[confirm] version of Hammer, but in most games, VBSP's support for manifests is unfinished and cannot compile them properly. VMMC can collapse manifests into a single VMF before compilation, which fixes many of these issues.

Code Fix:For Source 2013 mods, many of VBSP's issues can be fixed with code modifications. This fork by DeathByNukes includes several overall manifest fixes. Mapbase's repository modifies these fixes to work in Half-Life 2 mapping and also incorporates instancing fixes intended for manifests.

Precompiler

Metapyziks wrote a program that merges instances into the main VMF before each compile. This was originally created to enable instance support in older engine branches, but the GameData method has since rendered it mostly obsolete. However, it would theoretically be possible for someone to fork the program to add additional functionality, such as instance I/O support or the ability to toggle VisGroups with a fixup variable.

• Set up tutorial and source code
• VMFII releases

See also

• L4D2 Level Design/VMF Instances - A Valve tutorial on how to use instances in Left 4 Dead 2.
• Working with instances - A tutorial on how to use instances in Portal 2.

External links

• Source SDK Tutorial - Manifest Tool (YouTube)
• Manifests and Version Control Tutorial (TF2Maps.net)
• Valve Map Manifest Collapser (VMMC)