func_instance

Present in:
CS:S
DOD:S
HL2:DM
TF2
L4D2
ASW
Portal 2
CS:GO

func_instance is an internal point entity present in most Source games. It inserts another VMF into the current map. Similar to C++ member functions, a func_instance can be given parameters that change what it does, and the original instance VMF can be edited at any time and instantly apply to all other VMFs that use it. This saves mappers the tedious work of updating them all individually (though, maps already using the instance will have to be recompiled). Instances are used very extensively in Portal 2 for testing elements.

When the map is compiled, all instances are collapsed into the main map, effectively copied and pasted in with the correct positions and properties. In the engine, instances technically don't exist.

Warning: An instance that tries to insert itself inside it will crash Hammer.

Tip: gameinfo.txt has an InstancePath parameter that defines where instances are stored. If you try to reference files that aren't in this folder, you will have to manually type in the filename of your instance's .vmf (file path is relative to the parent .vmf).

Note: VBSP will only move entities in the FGD it loads from gameinfo.txt's GameData parameters. If your custom entities are being misplaced, this is the most likely cause.

Bug: Entities using an inverted "pitch" keyvalue will not have that adjusted when the instance is rotated in Hammer.

Bug: func_viscluster does not function when part of an instance.

Bug: In Team Fortress 2 and Source 2013, instances have are missing some functionality: instances cannot be nested and displacements within an instance may not compile properly. (To do: Displacement part needs to be reconfirmed.)

Note: Instances are available in the 2013 Multiplayer SDK, but not Singleplayer.

Keyvalues

Fix Up Name (targetname) <target_source>

String appended to the targetnames of every entity in this instance. Useful for differentiating between multiple instances in a map. Hammer assumes all entity I/O is between entities in the instance and will change the names in I/O connections to ones that are potentially wrong. See func_instance_io_proxy or the tip below.

Tip: If an entity's targetname in the actual map starts with an @ symbol, references to it inside the instance will not be altered by this keyvalue. In some games, Hammer will not recognize this syntax, but it does work. @ will also prevent the name of an entity inside the instance from changing.

Entity Name Fix Up (fixup_style) <choices>

How to append the Fix Up Name to the entities.

• 0: Prefix (fixup-name)
• 1: Postfix (name-fixup)
• 2: None (name)

VMF Filename (file) <instance_file>

Filepath to the instance VMF. It must be in the same folder as the main map or in a subfolder of it.

Replace (replace01) to (replace10) <instance_variable>

If the entities inside this instance have the text in Variable put anywhere inside them, such as an input parameter or keyvalue, that text will be replaced with whatever is in Value. Usually a $ is placed in front of the variable's name to make it more identifiable. If SmartEdit is off, just put variable value. These values do not update other references to them when the map is running.

Tip: Multiple parameters can be put in a single field. I.e. a targetname set to MyXValueMyYValue where the instance has MyXValue 1 and MyYValue 2 would compile to 12.

See Also

• func_instance_io_proxy
• func_instance_origin