KeyValues3

From Valve Developer Community
Jump to: navigation, search

KeyValues3 is a Valve developed data format. It is similar in structure to JSON, but supports binary encodings, versioning, and data annotations. The text syntax also has some minor ergonomic improvements (support for single- and multi-line comments, trailing commas, and multi-line strings.)

Text Header

The header of a text KV3 file specifies the encoding and format of the file. These are specified as GUIDs rather than integers to prevent unintentional collision if two people change format or encoding simultaneously in separate projects.

For the average user, GUIDs at the top of a KV3 file should always be the same.

Example

<!-- kv3 encoding:text:version{e21c7f3c-8a33-41c5-9977-a76d3a32aa0d} format:generic:version{7412167c-06e9-4698-aff2-e63eb59037e7} -->
{
	boolValue = false
	intValue = 128
	doubleValue = 64.000000
	stringValue = "hello world"
	stringThatIsAResourceReference = resource:"particles/items3_fx/star_emblem.vpcf"
	multiLineStringValue = """
First line of a multi-line string literal.
Second line of a multi-line string literal.
"""
	arrayValue =
	[
		1,
		2,
	]
	objectValue =
	{
		n = 5
		s = "foo"
	}
	// single line comment
	/* multi
	line
	comment */
}

Multiline String Literals

Multiline string format is:

  • Begin string with three unescaped quotes followed by an immediate newline (eg. the buffer looks like "\"\"\"\n")
  • End string with a newline followed by three unescaped quotes (eg. the buffer looks like "\n\"\"\"")
  • All characters between the two newlines (non-inclusive) are taken literally, with no normal escape characters.

Flags

  • KV3 keys can have flags to annotate their value as having special importance to some system. Currently the only flags are "resource" and "deferred_resource" to indicate that the flagged string is a resource reference. (ie. used for models and textures referenced by a particle system.)