From Valve Developer Community
Revision as of 05:35, 7 November 2019 by Luke18033 (talk | contribs) (Update instance I/O and precompiler info)

Jump to: navigation, search

An instance is a map (.vmf) file 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>Left 4 Dead 2, <Alien Swarm>Alien Swarm, [Portal 2]Portal 2, <Team Fortress 2>Team Fortress 2, <Counter-Strike: Global Offensive>Counter-Strike: Global Offensive, and Source 2013 include this by default. Instances can be enabled in other games by adding it, or using a pre-compiler as described below. To do: Only tested in [Portal]Portal, see if this works elsewhere
Note:In pre-<Left 4 Dead 2>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.

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.
  • 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

In <Left 4 Dead 2>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
Io11.png <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
Io11.png 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.

In older branches

Pre-L4D2 engine branches do not support the instance I/O system, so workarounds are needed to send and receive inputs and outputs in instances. For inputs, the fixed up entity name can be referenced directly.

My Output Target Entity Target Input Parameter Delay Only Once
Io11.png <output> <instance>-<entity> <input> <none> 0.00 No
Note:The target entity name will vary depending on the Entity Name Fix Up set on the instance.


To do


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.

Also see

External links