Tutorials

Understanding .VMF Files



Once in a time, you may end up with a fubarred map. for instance, when getting the "out of memory loading solids, error 7" error or hammer keeps freezing on loading your map. Its times like that when you need to go back to basic and enter the stone age of Microsoft.

Its times like that when you can really use knowledge about how a .vmf-file looks like, and how you can manipulate (e.g. repair it)

TOOLS:
we need a simple text-editor, e.g. notepad or wordpad. I prefer notepad because of its increased simplicity, but there are many text-editors you can use. It really doesn't matter, a .vmf-file is nothing more than a text-file in disguise! as long as the text-editor stores bare text (no layout whatsoever) it should be okay. remember to backup before you fuckup!
If you use notepad on windows XP, be sure to familiar yourself with a nice feature it has: it can show you line-numbers. To do that, simply check the "statusbar" option under the "view"-menu (you may need to disable word-warp for that). a bar will appear at the bottom with the line number your cursor is at. This may help you when hammer reports the line-number it encountered an error.
If your notepad doesn't have this function but you need it, I suggest you google for alternative notepads (there's literally tons on them)
If you need to save the map and it asks you to give up a file name, make sure it doesn’t save your map as "mapname.vmf.txt". if it does, simply add quotes around the filename.vmf to stop it from adding .txt

THE FORMAT:
a .vmf file is divided into parts, using brackets. each part starts with a name, and then two brackets enclose its properties

name of part
{
"valuename" "value"
"valuename" "value"
}


they can even be nested into each other

name of part
{
"valuename" "value"
"valuename" "value"
name of part
	{
	"valuename" "value"
	"valuename" "value"
	}
}


Mind a few things:
-You can add spaces and tabs before any line, and it doesn't matter. It’s simply for making things orderly
-as you can see, quotes and brackets are used to denote endings and beginnings of bits of information. Therefore, it is not allowed to put these kind of symbols in entity names, targets or other values you can specify in hammer. If you do, YOU can do the cleanup in your .vmf MANUALLY.
-sometimes hammer accidentally forgets to place them, and it can't figure out your map (huh, a new entity, but I haven’t closed the old one yet??). Although the parser doesn't recognise these errors (it doesn't know entities can't be a part of entities) it will see your last entity doesn't end, and it will throw an error.
Again, its up to you to find the one bracket hammer forgot. If your map is big, it will take a long time



THE FILE

The vmf file consists of a few parts:

    versioninfo
    visgroups
    world
    entity
    entity
    entity
    ...
    cameras
    cordon



versioninfo
{
	"editorversion"  "400"
	"editorbuild" "3057"
	"mapversion" "11"
	"formatversion" "100"
	"prefab" "0"
}


"editorversion is the version of hammer, in this case 4.0.0.
editorbuild is a sub-version
mapversion counts how many times your map has been saved over this one
formatversion and prefabversion always seem to have these numbers"

as you can see, this part shows nothing useful apart from versionstuff.
In fact, you can delete it entirely and hammer will create a new one, so if you think your error is in here, just delete the entire part.

visgroups
{
	visgroup
	{
		"name" "Auto"
		"visgroupid" "1"
		"color" "234 227 128"
		visgroup
		{
			"name" "Entities"
			"visgroupid" "3"
			"color" "136 105 94"
		}
		visgroup
		{
			"name" "Brush Entities"
			"visgroupid" "4"
			"color" "109 114 107"
		}
		visgroup
		{
			"name" "Detail Brushes"
			"visgroupid" "2"
			"color" "225 86 143"
		}
	}
}
viewsettings
{
	"bSnapToGrid" "1"
	"bShowGrid" "1"
	"nGridSpacing" "1"
	"bShow3DGrid" "0"
}

"if you didn't already guess, these two parts hold settings for hammer. of course they are obsolete, and if you delete them completely, hammer will just fetch its default settings for this map. As you can see in the visgroups, this map has one visgroup, named "auto" (I'm sure you've seen it before) and auto has three sub-visgroups, named Entities, Brush entities and Detail Brushes. Each visgroup has it's own id-number, and it's own colour (this options is still not used in hammer). As you can see, each visgroup is nested in it's "master"-visgroup. Thanks to the layout that’s easy to see the viewsettings hold a few settings, nothing important. I'm sure you can guess what each of the four values displayed here resemble
"

The next part is going to be complicated, that’s why I’ve made a small lay-out as to how you should read it:

entity
{
	"entityvalue" "value"
	"entityvalue" "value"
	connections
	{
		"OnTrigger" "do this" "when that"
		"OnTrigger" "do this" "when that"
	}
	solid
	{
		"lots of names & values"
	}
	editor
	{
		"value" "value"
	}
}


"here we see one entity. starting at the top line:
-first the word "entity" marks the next portion inside the brackets is an entity
-then a few lines of properties (you will find targetnames, entity-type (classname), flags, models angles etc. here. e.g.

"classname" "func_detail"
"targetname" "terrorist_compound_door"

point-based entities also have a value called origin, which specifies their exact location x-y-z wise. some brush-based entities have them too!

under a special part are three things:
connections: these are the outputs of the entity: "my output" "target entity, action, parameter, delay, how often"
solid: here are the brushes specified (there can be more than one if there are more than one brushes for the entity)
editor: here is specified which colours the entity has in the editor and to which visgroup it belongs (corresponds to their visgroupid)
you may wonder how the flags are specified, since you can only see one number. well, that’s the splendour of binary digits. the number specified as "flags" is actually a binary number (consisting of 1's and 0's)e.g. 1111111 corresponds to all flags on, 1110000 only has the first three on. the rest is off etc. this number is transformed into a decimal and put into the vmf"

world
{
	"entityvalue" "value"
	"entityvalue" "value"
	solid
	{
		"lots of names & values"
	}
}


"the "world" entity is the biggest entity in your map. all brushes that do not belong to an entity, belong to the world-entity (hence the "to-world"-button to de-entity a brush). Its properties contain all properties you can specify under "map properties" in hammer, e.g. skybox name and that sort of things. It doesn't have an editor part, because you can't hide an entity that is never visible in your map.(would be pointless... <!-- s;) --><img src="https://www.interlopers.net/forum/images/smilies/icon_wink.gif" alt=";)" title="Wink" /><!-- s;) --> )"

a solid looks like this:

solid
	{
		"id" "45"
		side
		{
			"id" "69"
			"plane" "(136 100 192) (-108 100 192) (-108 100 96)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[1 0 0 2.53967] 0.266949"
			"vaxis" "[0 0 -1 312.889] 0.28125"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		side
		{
			"id" "70"
			"plane" "(136 100 192) (100 64 192) (-108 64 192)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[1 0 0 0] 0.25"
			"vaxis" "[0 -1 0 0] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		side
		{
			"id" "71"
			"plane" "(-108 92 96) (128 92 96) (136 100 96)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[1 0 0 0] 0.25"
			"vaxis" "[0 -1 0 0] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		side
		{
			"id" "72"
			"plane" "(-108 64 192) (-108 64 144) (-108 92 96)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[0 1 0 0] 0.25"
			"vaxis" "[0 0 -1 384] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		side
		{
			"id" "73"
			"plane" "(100 64 144) (100 64 192) (136 100 192)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[0 1 0 0] 0.25"
			"vaxis" "[0 0 -1 384] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		side
		{
			"id" "74"
			"plane" "(100 64 192) (100 64 144) (-108 64 144)"
			"material" "METAL/CITADEL_METALWALL072B"
			"uaxis" "[1 0 0 0] 0.25"
			"vaxis" "[0 0 -1 384] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
		}
		editor
		{
			"color" "220 220 220"
			"visgroupshown" "1"
		}
	}


"this solid has one id, (for the "go to brush number") and consists of 6 sides, each side has:
-An id
-Three coordinates specifying a plane (what happened to the fourth? I guess it guesses that one)
-The texture name
-Alignments x and y-wise
-Rest is pretty clear
lastly, the standard brush has an "editor"-part to specify its colour and to which visgroup it belongs
"


any side can also be a displacement:

side
{
			"id" "2696"
			"plane" "(-1320 -936 0) (-1410 -936 0) (-1410 -936 19)"
			"material" "CONCRETE/CONCRETEWALL043A"
			"uaxis" "[1 0 0 -300] 0.25"
			"vaxis" "[0 0 -1 76] 0.25"
			"rotation" "0"
			"lightmapscale" "16"
			"smoothing_groups" "0"
			dispinfo
			{
				"power" "3"
				"startposition" "[-1410 -936 0]"
				"elevation" "0"
				"subdiv" "0"
				normals
				{
					"row0" "0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0"
			
				}
				distances
				{
					"row0" "2.48932 2.99426 2.521 1.9306 1.13086 2.38812 1.57935 2.78241 0.740356"
	
				}
				offsets
				{
					"row0" "0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"

				}
				offset_normals
				{
					"row0" "0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0 0 -1 0"

				}
				alphas
				{
					"row0" "0 0 0 0 0 0 0 0 0"

				}
				triangle_tags
				{
					"row0" "0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0"

				}
				allowed_verts
				{
					"10" "-1 -1 -1 -1 -1 -1 -1 -1 -1 -1"
				}
			}
		}


"the only thing different from a normal side is de dispinfo{} part. a lot of numbers, each corresponding to a point on your displacement and its altitude, alpha, offset and whatever is put here (usually more rows than just one, i edited the rest away).
Its a lot of work to repair these, so if you suspect an error here its best to just delete the entire dispinfo{} part."


The last bits are just sad, as small as they are

cameras
{
	"activecamera" "0"
	camera
	{
		"position" "[442.285 552.537 316.251]"
		"look" "[440.549 551.6 315.232]"
	}
}
cordon
{
	"mins" "(99999 99999 99999)"
	"maxs" "(-99999 -99999 -99999)"
	"active" "0"
}


"just two bits specifying camera's position and direction, and the settings of the cordon tools (as you can see: cordon tools are always there, but when you don't use them their size is bigger than your map. both of these parts are completely unnecessary."

I think that's enough to know for now, and I wish you all the luck if you read this because your map is broken or you want to try to make maps in notepad because you think hammer sucks balls.


zombie@computer

View comments ( 10 )

Back to top