View source for Instance

{{otherlang2

|ru=Примеры:ru

}}

{{stub}}
An '''instance''' is a [[VMF|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 <code>GameData</code> key must be present in [[gameinfo.txt]] pointing to the game's [[FGD]] file. ({{todo|Is <code>InstancePath</code> needed as well?}}) Only {{l4d2}}[[Left 4 Dead 2]] and later, along with {{tf2}}[[Team Fortress 2]], include this by default. Instances can be enabled in other games by adding this, or using a pre-compiler as described below.}}

{{note|In pre-{{l4d2}}[[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 {{l4d2}}[[Left 4 Dead 2]] and later, instances can send and receive inputs and outputs. To use this functionality, a {{ent|func_instance_io_proxy}} entity named <code>proxy</code> 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:
::{| class=standard-table
!   || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
|-
| [[Image: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 {{ent|func_instance}}:

::{| class=standard-table
!   || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
|-
| [[Image: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.

::{| class=standard-table
!   || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
|-
| [[Image: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.}}

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

{{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. [https://tf2maps.net/downloads/vmmc.3660/ VMMC] can collapse manifests into a single VMF before compilation, which fixes many of these issues.}}
{{fix|For {{Game link|Source 2013}} mods, many of VBSP's issues can be fixed with code modifications. [https://github.com/DeathByNukes/source-sdk-2013 This fork by DeathByNukes] includes several overall manifest fixes. [https://github.com/mapbase-source/source-sdk-2013 Mapbase's repository] modifies these fixes to work in {{Game link|Half-Life 2}} mapping and also incorporates instancing fixes intended for manifests.|code}}

== Precompiler == 

[http://steamcommunity.com/id/metapyziks 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 <code>GameData</code> 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.
* [https://github.com/Metapyziks/VMFInstanceInserter Set up tutorial and source code]
* [https://github.com/Metapyziks/VMFInstanceInserter/releases VMFII releases]

== Also see ==
* [[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 ==
* [http://www.youtube.com/watch?v=YvSZ2NEX1Y0 Source SDK Tutorial - Manifest Tool (YouTube)]
* [http://tf2maps.net/threads/mapping-collaboration-or-using-manifest-and-version-control.24787/ Manifests and Version Control Tutorial (TF2Maps.net)]
* [https://tf2maps.net/downloads/vmmc.3660/ Valve Map Manifest Collapser (VMMC)]

[[Category:Glossary]]
[[Category:Level Design]]
[[Category:Left 4 Dead 2]]
[[Category:Alien Swarm]]
[[Category:Portal 2]]
[[Category:Instances|*]]