What is func_instance?

WarmHandSanitizer

L1: Registered
Sep 15, 2012
26
0
You guys have been raving about it, but I didn't get why it was so useful, or even how it worked.

The wiki didn't provide much help.
 

tyler

aa
Sep 11, 2013
5,102
4,621
I don't really think I can explain it better than the wiki does.

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. By default, instances are drawn in Hammer with an orange tint.

So... it puts a vmf in your vmf.

Useful for things you repeat a lot, things you need to change all of at once (lights), or angled detail geometry.

To use it, place a func_instance entity and type the relative vmf filename. If the thing you want to instance is in the same directory, that's just filename.vmf.
 

Fruity Snacks

Creator of blackholes & memes. Destroyer of forums
aa
Sep 5, 2010
6,394
5,571
You can build a solitary building in a seperate .vmf, and then use func_instance to place that building into another .vmf. (If you want a reallly specific/simple answer) And, as yyler said, it's great for repeating things, weird angle brushwork, or lighting.

I used it for stairs a couple times.
 

Freyja

aa
Jul 31, 2009
2,994
5,813
I used func_instance for the bridges in escarpment. It means I could build them on-grid, then rotate them to a weird angle in the main vmf and still be able to go back and edit it later, still on grid.
 

Pocket

Half a Lambert is better than one.
aa
Nov 14, 2009
4,694
2,579
What happens to them when you compile, anyway? Does it hard-code all of the vertices as exact XYZ coordinates (which technically involves snapping everything to a grid, just a much smaller one)? Or does it store it as if it were on grid and then say "rotate it so many degrees"?
 

Idolon

they/them
aa
Feb 7, 2008
2,105
6,106
No. Prefabs are no different than any other brush/entity data you stick into the map, while instances are only entities that reference other map files. Prefabs also do not have the rotation or repetition features mentioned previously.
 

Trader

L1: Registered
Oct 18, 2011
13
0
Valve Wiki: They provide a more dynamic alternative to prefabs, as any changes to the instanced map will be reflected in all instances of it.
So if I have 2 separate maps, one map has a really complex solid structure, if I inserted a func_instance into the other map, and change it about a bit, it will change that same structure in the other map as well?
 

tyler

aa
Sep 11, 2013
5,102
4,621
It's not like linking files. It puts one file in another.

If you change the vmf you use as an instance, it updates in every map you've used it in. You can't edit whatever you've instanced unless you open the file itself. Does that make sense?

Edit: Here's a picture of one of my instances.

1xi5E


I use this in Hella, and rotate it about 30 degrees. If it wasn't an instance, it'd be off grid after doing that pretty significantly. But since it is, I can open this file and edit it whenever without any problems.

In Hella it appears like this:

1xi81
 
Last edited by a moderator:

Arne

L3: Member
Nov 22, 2012
114
55
This is intresting. I never heard of this trick.
Something that can help me with some maps which I'm working on!

Thanks for telling me (or us who never heard of this)!
 
Last edited:

A Boojum Snark

Toraipoddodezain Mazahabado
aa
Nov 2, 2007
4,775
7,669
What happens to them when you compile, anyway? Does it hard-code all of the vertices as exact XYZ coordinates (which technically involves snapping everything to a grid, just a much smaller one)? Or does it store it as if it were on grid and then say "rotate it so many degrees"?

The tools can handle floating point verts, and store/use/remember them, it just becomes impossible to work with.
 
Sep 7, 2012
638
500
Do the brushes, displacements, entities and such go towards the total entity count, etc of the map you put the instance in?
 

A Boojum Snark

Toraipoddodezain Mazahabado
aa
Nov 2, 2007
4,775
7,669
Yes. The initial processing of the map by VBSP includes collapsing all instances into the map. The instance "entity" doesn't actually exist, it just tells VBSP to include the data from vmf X with such and such settings.
 
Jan 8, 2011
397
393
That's brilliant. That seems like a much better method of dealing with rotated things. How do content packers handle it?
 
Sep 7, 2012
638
500
I'm guessing there's no way to get a "preview" of what it will look like in hammer with the instances collapsed - you have to compile and find out, right?
 

A Boojum Snark

Toraipoddodezain Mazahabado
aa
Nov 2, 2007
4,775
7,669
Err, hammer automatically displays whatever is inside the instance (even to the point of displaying selections WITHIN the instance, if you have both files open in hammer). That's almost the entire point of it, since it would be impossibly difficult to use otherwise.
 
Sep 7, 2012
638
500
I can't be doing it right, then. Are there any other fields I need to be filling out other than the name of the vmf to include?
 

tyler

aa
Sep 11, 2013
5,102
4,621
The instance "collapsed" is not an instance. It's part of your main vmf. "Collapsing" means "merging".

Collapsed into a single vmf.