Working with instances

From Valve Developer Community
Revision as of 14:42, 16 May 2011 by Msleeper (talk | contribs) (This is going to be a work in progress)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Using instances when creating your Portal 2 map can greatly increase your speed and efficiency between prototyping a puzzle and publishing the final product. Stock instances included with the Portal 2 Authoring Tools can be used to create nearly every element of creating a map - from the most basic things like floor buttons, to more complex setups like box spawners, and even non-gameplay elements such as observation rooms.

What are instances?

Instances are nothing more than an external VMF file that is loaded dynamically into your map. An instance VMF can contain anything as simple as a single brush, to an entire puzzle or gameplay element complete with logic entities and Input/Output triggers.

When should I use an instance?

One of the major benefits of using an instance is that any changes you make to the instance VMF is instantly translated to the rest of your maps. If you make a change to the look or operation of your floor button or your door, you do not need to go and change every usage of it in your map, like you would if you had manually created them and/or used a normal Prefab. Instead of creating several copies of the same entities, you can use an instance to build the button or door once, and then reuse it multiple times.

Instances are best used when creating game elements, geometry, complex entity or I/O setups (such as map transitions), or any other grouping of objects that is going to be repeated or reused frequently.

Building an instance from scratch

An instance requires, at minimum, a single func_instance entity placed in the source VMF. The placement of this entity will act as the origin of the instance when used in another map. For example, placing the instance file's func_instance on floor level of a button will allow the button to be easily placed flush against the floor in your map.

If your instance requires Input/Output interaction with the map it will be placed in, you will need a single func_instance_io_proxy entity with the targetname "proxy". For each Input that you want the instance to be able to receive, you need to setup a corresponding Output in the func_instance_io_proxy with the Output "OnProxyRelay".

You can have your instance have changeable parameters by placing a func_instance_parms in the instance file. Each variable must start with a $ symbol, and then must correspond to the value in another entity within the instance. For example, if you are building a custom box dropper instance, you can setup a parameter "$box_color" which then corresponds to the box entity's "color" value, and another parameter "$box_name" which corresponds to the box entity's "targetname" value. When you place this instance in your map, you will have the option to use the func_instance's "Replace" fields to change the color and the targetname of the box entity that is created.

A note about using func_instance_parms and targetname

If an entity in an instance has it's targetname set to a replaceable parameter field, any I/O in your map must target the entity's final instance collapsed name. During the VBPS process, all of your instances are gathered and collapsed into your map, and the names of any entities within those instances have their names altered. The renaming system works as follows (assuming the "Entity Name Fix Up" is set to "Prefix (default)":

  • (value of your map's func_instance "Fix Up Name")-(instance entity's targetname)

Using Input/Output with instances

An instance can accept Input from your map - assuming it has the proper func_instance_io_proxy Outputs setup - quite easily. Using a basic floor button example, you can add any Outputs that the proper func_instance_io_proxy has setup. You can also target one instance from another, for example using a floor button to turn on or turn off a gel flow. Again you will simply select the target entity and it's Input fields will be automatically filled out.

See also

External links

Original thread of this article hosted at ThinkingWithPortals.com. Example VMFs included.