WebAPI/VDF

From Team Fortress Wiki
Jump to: navigation, search

VDF is an ad-hoc file format designed by Valve to support storage of hierarchical data.

Basic layout

A basic VDF file will usually consist of a single root node containing the rest of the nodes within.

"someresource" [$WIN]
{
	"foo" "bar" // Some comment
	"odd" "record" [$ODD]
	"someotherresource"
	{
		"baz" "tar"
	}
}

Basic structure

In this example someresource will be the root node. Most of the time a given record will and can be indented by any whitespace including ' ' and '\t'. Most key names in a VDF file will be double quoted. However this is not always the case as seen in TF2's own files such as hudlayout.res.

Bracketed tokens

In some cases there will be a token that is surrounded by brackets ([]). The specific uses and meaning of this are still being looked at but lexers should consider skipping it entirely or in extreme cases skipping the entire line after the second token is passed. This can also appear in nodes before the opening brace as seen in the example's [$WIN] token. A more common case can be seen with the [$ODD] token.

Commenting style

C++-style commenting is supported as seen in the above example. Comments can appear at the end of the line or on a line by itself. All content between the opening forward slashes (//) and the line terminator should be ignored.

Macros

Macros are supported by the format and are implemented as a string directly after an opening pound symbol (#) as the first non-whitespace character in a line and one operand separated by whitespace. Contrary to Valve's documentation there are key names with an unescaped macro symbol in them. This may mean that internally they are replaced by a value (similarly to how the C preprocessor replaces values), the macro is ignored entirely if there is no matching definition, or a macro use is only valid if it is on a single line with the opening symbol as the first non-whitespace character.

Notes

Valve's own documentation

It has 3 control characters '{', '}' and '"'. Names and values may be quoted or
not. The quote '"' charater must not be used within name or values, only for
quoting whole tokens. You may use escape sequences wile parsing and add within a
quoted token a \" to add quotes within your name or token. When using Escape
Sequence the parser must now that by setting KeyValues::UsesEscapeSequences( true ),
which it's off by default. Non-quoted tokens ends with a whitespace, '{', '}' and '"'.
So you may use '{' and '}' within quoted tokens, but not for non-quoted tokens.
An open bracket '{' after a key name indicates a list of subkeys which is finished
with a closing bracket '}'. Subkeys use the same definitions recursively.
Whitespaces are space, return, newline and tabulator. Allowed Escape sequences
are \n, \t, \\, \n and \". The number character '#' is used for macro purposes 
(eg #include), don't use it as first charater in key names.