KeyValues3

KeyValues ▶ KeyValues2 ▶ KeyValues3

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.)

Games

^[Todo]

1. Counter-Strike: Global Offensive - for Bot Behavior Trees, prop_ammo_box_generic

File format

^[Todo]

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 systems. Currently the available flags are:

	resource
	resourcename
	panorama
	soundevent
	subclass