Difference between revisions of "Instance"

From Valve Developer Community
Jump to: navigation, search
(Slight edit)
(Clarified some info on manifests)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{otherlang2
 +
 +
|ru=Примеры:ru
 +
 +
}}
 +
 
{{stub}}
 
{{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]].
 
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|While working inside [[Hammer]] for all Source games, instances are currently only supported by the map compilers for {{l4d2}}[[Left 4 Dead 2]], {{as}}[[Alien Swarm]], {{portal2}}[[Portal 2]], {{tf2}}[[Team Fortress 2]], {{csgo}}[[Counter-Strike: Global Offensive]], and Source 2013, and therefore will not work for any other games. To use them in unsupported games, see below.}}
+
{{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 {{tf2}}[[Team Fortress 2]] and Source 2013, 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|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:
 
Instances are helpful in many ways:
Line 13: Line 19:
 
* 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.
 
* 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.
  
==How to==
+
== Instance I/O ==
In Portal 2 to give input to an entity within a instance use this:
+
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
 
::{| class=standard-table
 
!  || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
 
!  || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
 
|-
 
|-
| [[Image:Io11.png]] || <Output> || <Instance> || instance:<entity>;<input> || <none> || 0.00 || No
+
| [[Image:Io11.png]] || <output> || <instance> || instance:<entity>;<input> || <none> || 0.00 || No
 
|}
 
|}
  
Or, alternatively, you can do this:
+
To receive an output from an entity in the instance, this output would be used on the {{ent|func_instance}}:
 +
 
 
::{| class=standard-table
 
::{| class=standard-table
 
!  || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
 
!  || My Output || Target Entity || Target Input || Parameter || Delay || Only Once
 
|-
 
|-
| [[Image:Io11.png]] || <Output> || <Instance>-<entity> || <input> || <none> || 0.00 || No
+
| [[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 ==
 
== Manifests ==
{{todo|}}
+
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}}
  
== Workaround for any Source game ==  
+
== Precompiler ==  
  
To use instances in unsupported Engine versions, [http://steamcommunity.com/id/metapyziks Metapyziks] wrote a program that merges used instances with the main VMF.
+
[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 Set up tutorial and source code]
 
* [https://github.com/Metapyziks/VMFInstanceInserter/releases VMFII releases]
 
* [https://github.com/Metapyziks/VMFInstanceInserter/releases VMFII releases]
Line 44: Line 75:
 
* [http://www.youtube.com/watch?v=YvSZ2NEX1Y0 Source SDK Tutorial - Manifest Tool (YouTube)]
 
* [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)]
 
* [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:Glossary]]

Latest revision as of 17:05, 2 October 2020

Русский

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.png 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. (To do: Is InstancePath needed as well?) Only <Left 4 Dead 2>Left 4 Dead 2 and later, along with <Team Fortress 2>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.png 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.png 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.png 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.png 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><Source> 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> 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.

Also see

External links