KeyValues3

From Valve Developer Community
(Redirected from Kv3)
Jump to navigation Jump to search
English (en)Translate (Translate)

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] The following games and projects are known to use KV3:

  1. Counter-Strike: Global Offensive Counter-Strike: Global Offensive - Used for Bot Behavior Trees and prop_ammo_box_generic.
  2. Portal 2: Community Edition Portal 2: Community Edition - Used for addon metadata (addon.kv3).

Text Header

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

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

KV3 Encodings

The ways that KV3 data can be serialized

UUID Name Description
{E21C7F3C-8A33-41C5-9977-A76D3A32AA0D} text Basic text encoding
{1B860500-F7D8-40C1-AD82-75A48267E714} binary Uncompressed binary encoding
{95791A46-95BC-4F6C-A70B-05BCA1B7DFD2} binary_bc Compressed binary encoding

KV3 Formats

How to interpet loaded KV3 data

UUID Name Description
{7412167C-06E9-4698-AFF2-E63EB59037E7} generic The default format for arbitrary data - expresses no assumption about how the data will be used


Text Without a Header

Games that use KV3 library also support loading and saving raw KV3 text without a UUID header.

Such data is interpreted as text encoding with the generic format.

File format

A KV3 file contains an unnamed root value. Unlike KeyValues, a KV3 value does not have an associated key. Keys are introduced only by table members.

A text KV3 file normally consists of a text header followed by the root value. The header identifies the encoding and format using UUIDs.

Basic Rules

  • The root of a KV3 file is an unnamed value. It is not required to be a table, although tables are conventionally used as the root value of text KV3 files.
  • A table is enclosed in { and }.
  • An array is enclosed in [ and ].
  • Table members consist of a member name, followed by = and a value.
  • Array elements are separated by commas.
  • A trailing comma is permitted after the last element of an array.
  • KV3 supports single-line and multi-line comments.
  • String literals are enclosed in double quotes.
  • Multi-line string literals are enclosed in three consecutive double quotes.
  • KV3 does not support the #include, #base, or conditional-value features of KeyValues.
  • Values may have additional type annotations represented internally as flags.

Values

KV3 represents values using the following public types:

Type Description Example
null No value null
bool Boolean value true
int64 Signed 64-bit integer 128
uint64 Unsigned 64-bit integer 128
double Double-precision floating-point value 64.000000
string UTF-8 string "hello world"
binary blob Raw binary data encoding-dependent
array Ordered list of KV3 values [ 1, 2, 3 ]
table Ordered list of named KV3 members { key = value }


KeyValues3Type_t enumeration: 

// Public-facing types that a KV3 can store.
enum KeyValues3Type_t: uint8
{
	KEYVALUES3_TYPE_INVALID,

	KEYVALUES3_TYPE_NULL,			// no value

	KEYVALUES3_TYPE_BOOL,
	KEYVALUES3_TYPE_INT64,
	KEYVALUES3_TYPE_UINT64,
	KEYVALUES3_TYPE_DOUBLE,

	KEYVALUES3_TYPE_STRING,			// utf8
	KEYVALUES3_TYPE_BINARY_BLOB,	// raw bytes

	KEYVALUES3_TYPE_ARRAY,			// Ordered list of KV3 values
	KEYVALUES3_TYPE_TABLE,			// Ordered list of (string,KV3) members

	KEYVALUES3_TYPE_MAX,
};

Root Value

Unlike KeyValues, KV3 does not have a root key. A KeyValues3 instance represents a single unnamed value.

For example, the following KV1 structure: 

"root"
{
	"first"
	{
		"attr1" "0.5"
		"attr2" "potato"
	}
}

can be represented in KV3 without the artificial "root" key: 

{
	list =
	[
		{
			name = "first"
			attr1 = 0.5
			attr2 = "potato"
		},
	]
}

The root value may itself be any KV3 value type. A table is conventional for files containing named members.

Tables

A table is an ordered collection of named KV3 values enclosed in { and }.

Each table member consists of a member name, followed by = and its value. 

{
	boolValue = false
	intValue = 128
	stringValue = "hello world"
}

Tables may contain other tables and arrays: 

{
	objectValue =
	{
		n = 5
		s = "foo"
	}

```
arrayValue =
[
	1,
	2,
	3,
]
```

}

Table members are ordered. The order of members is retained by the KV3 runtime representation.

Arrays

An array is an ordered list of KV3 values enclosed in [ and ].

Array elements are separated by commas. A trailing comma is permitted. 

[
	1,
	2,
	3,
]

Arrays may contain values of different types: 

[
	1,
	"two",
	false,
	{
		value = 4
	},
]

Binary Blobs

KV3 has a first-class binary blob type for storing raw binary data.

Binary blobs are supported by the KV3 runtime representation and binary encodings. Their textual representation, if any, is encoding-specific.

Resource References

Resource references are represented internally by the KEYVALUES3_FLAG_RESOURCE_REFERENCE flag.

The text representation used by the KV3 text serializer is: 

resource:"particles/items3_fx/star_emblem.vpcf"

Comments

KV3 supports both single-line and multi-line comments.

Single-line comments begin with // and continue until the end of the line. 

// single-line comment
value = 42

Multi-line comments are enclosed by /* and */. 

/*
	multi-line
	comment
*/
value = 42

Multiline String Literals

KV3 supports multi-line string literals using three consecutive double quotes.

A multi-line string begins with three unescaped double quotes followed immediately by a newline.

The string ends with a newline followed by three unescaped double quotes.

All characters between these two newlines are taken literally. 

message = """
First line of a multi-line string literal.
Second line of a multi-line string literal.
"""

The KV3 runtime represents this using KEYVALUES3_FLAG_MULTILINE_STRING. This flag indicates that the text serializer should use the multi-line """ syntax when serializing the value.

Flags

KV3 values can have additional flags which act as type annotations. Flags are part of the KV3 data and are serialized and copied along with the value.

KeyValues3Flag_t enumeration currently defines:

Flag Friendly Name Description
KEYVALUES3_FLAG_RESOURCE_REFERENCE resource Indicates that a string value is a resource reference.
KEYVALUES3_FLAG_MULTILINE_STRING <none> Indicates that a string should be serialized using the multi-line """ syntax.
KEYVALUES3_FLAG_RESOURCE_NAME resourcename undocumented.
KEYVALUES3_FLAG_PANORAMA panorama undocumented.
KEYVALUES3_FLAG_SOUND_EVENT soundevent undocumented.
KEYVALUES3_FLAG_SUBCLASS subclass undocumented.

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 =
	[
        false,
		1,
		2.000,
        "three",
        {
            res = resource:"models/error.mdl"
        }
	]
	objectValue =
	{
		n = 5
		s = "foo"
	}

	// single line comment

	/* multi
	line
	comment */
}
Retrieved from "https://developer.valvesoftware.com/w/index.php?title=KeyValues3&oldid=518265"