func_instance

func_instance is an internal point entity available in all Source games.
It inserts an instance of another VMF file into the current one. You can translate and rotate the instance without breaking anything or creating an off-grid editing nightmare (although QPhysics may subtly break, such as making angled surfaces non-surfable).
By default, instances are drawn in Hammer with an orange tint, though this can be disabled in Instancing > View Instances.
Instances allow you to edit the vmf of the instance and have every used instance on your main map be changed as well. But unfortunately many instances will lag hammer quite a lot. Hammer++ does not suffer from this lag

A picture showing a window instance used multiple times on a house.

Example uses:

• An elaborate window setup with breakable glass, window prop, clip brushes, areaportal_window and its window brush, then using it all over a house.
• A camper trailer which has brushwork and props inside, which then gets placed at weird angles that would make areaportal creating difficult.
• Vehicles with a random color assignment, sprinkled over the map.

Limitations and Caveats

Warning:Recursive instances (instances which include themselves) will crash Hammer.

Confirm:How about the compile tools?

Warning:env_cubemap (and possibly more entities (all entities that don't have origin keyvalue specified in FGD ^[confirm]) that are inside of an instance have an issue where they will retain their position in the map from the instance's internal origin, and will not be offset by the position of the func_instance when compiled.

Note:Instances are disabled by default in pre-Left 4 Dead 2 games (except Team Fortress 2). To enable them, add a GameData key to gameinfo.txt, pointing to the game's FGD file.

Note:VBSP will only transform entities in the FGD file it loads from the GameData key. If any custom entities are being misplaced, this is the most likely cause.

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)

Bug:

• In Alien Swarm, nested instances with relative file names don't work correctly, because they are handled differently in Hammer and VBSP. ^[confirm] (Maybe because of incorrectly set up gameinfo.txt)
• light_spot will behave unpredictably when part of an instance that alters the light's pitch. This is solved by collapsing the instance or using the light's target KV ("Entity to point at").
• Will not work correctly in the Source 2009. It is recommended you use a Prefab instead.
• func_viscluster does not function when placed inside of an instance.
• VBSP will crash with no error if an instance pushes it over the brush limit (i.e. a situation where hiding all instances would keep the map under the brush limit). Compiling with -verbose will reveal the specific instance causing VBSP to fail.
• Brush entities that are rotated by func_instance are rotated via the angles KV, instead of the brushwork itself being rotated (which occurs for world brushes). This results in issues on entities wherein the angles are reset to "0 0 0", such as func_illusionary.
• Rotated instances don't correctly have axial brushsides generated for them. This can result in using fewer brushsides, but will subtly break QPhysics, such as making surfing impossible (VPhysics is unaffected).

Workaround:Most of these issues can be worked around by collapsing the instance in Hammer.

  [todo tested in?]

Input through an instance

1. Define a Fix Up Name.
2. Define a value for the input or output you want to use (if there is one).
3. Send an input to the targetname "fixupname-value", e.g. MyInstance-Start. Hammer's UI won't recognise the name, but don't worry.

KeyValues

VMF Filename (file) <string>

The VMF file to insert as an instance. Relative to the current map's location.

Example:

• If map.vmf and the instance.vmf are in the same folder, the filename field would be instance.vmf
• If the instance.vmf is in a subfolder of where the map.vmf is, the filename field would be subfoldername/instance.vmf
• If the instance.vmf and your map.vmf are neither in the same folder, nor in a subfolder of eachother, (Like maps/instances/instance.vmf and maps/project/map.vmf) you can use ../ to jump up a directory, in order to enter a new one. As such: ../Instances/instance.vmf

Fix Up Name (propagate_fixup) <string>

Essentially the name of the instance. All entities within it will have this string added to them based upon the fix up style. If no name is provided, InstanceAutoX or AutoInstanceX will be used, where X is a number that is incremented with each instance.

Note:Entity names that start with the @ symbol e.g. @exit_door will not be changed by the instance name fix up.

Entity Name Fix Up (fixup_style) <choices>

How to apply the fix up name.

• 0: Prefix (Default)
• 1: Postfix
• 2: None

Replace (replace01) <instance_variable>

This is a replacement parameter. Any usage of $variable inside the instance will be replaced with value. Replace <string $variable> <string value>. Example: $color 255 0 0.

Note:There are 10 Replace key-value pairs with the keys following replace{number} for names: replace01, replace02, ..., replace10

Pitch Yaw Roll (Y Z X) (angles) <angle>

This entity's orientation in the world. Pitch is rotation around the Y axis, yaw is the rotation around the Z axis, roll is the rotation around the X axis.

See also

• func_instance_parms - Entity to control parameters within instances.
• func_instance_io_proxy - Entity that is used as a proxy for entity I/O within instances.
• func_instance_origin - Helper entity that defines the center point of an instance.
• L4D2 Level Design/VMF Instances - A tutorial on how to use this entity in Left 4 Dead 2.