ValveKeyValue

KV1 files require a single named root object.

• When reading: The name is stored in KVDocument.Name.
• When writing: Pass a KVDocument (which contains the name) or pass a bare KVObject along with a string representing the root name.

var root = KVObject.ListCollection();
root.Add("Developer", "Valve Software");
root.Add("Name", "Dota 2");

var kv = KVSerializer.Create(KVSerializationFormat.KeyValues1Text);
using var stream = File.OpenWrite("file.vdf");

// Option 1: Serialize bare object with a root name
kv.Serialize(stream, root, "root object name");

// Option 2: Wrap in a KVDocument
var doc = new KVDocument(null, "root object name", root);
kv.Serialize(stream, doc);

KV3 (Source 2) text files start with a header comment containing encoding and format identifiers.

Key differences from KV1:

• KVDocument.Name is always null (no root key name).
• KVDocument.Root can be any value (scalar, array, collection, etc.).
• Collections are dictionary-backed; duplicate keys are not preserved.
• KVDocument.Header contains the KVHeader (Encoding and Format).

var kv = KVSerializer.Create(KVSerializationFormat.KeyValues3Text);
using var stream = File.OpenRead("file.kv3");
KVDocument data = kv.Deserialize(stream);

if (data.Header is { } header)
{
    Console.WriteLine(header.Encoding);
    Console.WriteLine(header.Format.Name);

    bool isGeneric = header.Format.Id == ValveKeyValue.KeyValues3.Format.Generic;
}

The library is built around two primary types:

• KVObject: A single value node. It can be a scalar (string, int, float, bool, etc.), a binary blob, an array, or a named collection of children. It implements IReadOnlyDictionary<string, KVObject> and IConvertible. Keys are stored in the parent container.
• KVDocument: The result of deserialization. It contains the Root (KVObject), the root key Name (null for KV3), and a Header (only for KV3). The KVDocument indexer is read-only and delegates to Root.

Collection Types:

• Use KVObject.Collection() for general use and KV3 output (dictionary-backed, O(1) lookup, no duplicate keys).
• Use KVObject.ListCollection() for KV1 files or when you need duplicate keys (list-backed, preserves insertion order).

To use ValveKeyValue, create a KVSerializer with the desired KVSerializationFormat, then use Deserialize to read from a stream and Serialize to write to a stream. The library supports KeyValues1Text, KeyValues1Binary, and KeyValues3Text.

using ValveKeyValue;

var kv = KVSerializer.Create(KVSerializationFormat.KeyValues1Text);

// Read
using var input = File.OpenRead("gameinfo.txt");
KVDocument data = kv.Deserialize(input);

string game = (string)data["game"];
int appId = (int)data["FileSystem"]["SteamAppId"];

// Modify
data.Root["game"] = "My Mod";

// Write
using var output = File.OpenWrite("gameinfo_modified.txt");
kv.Serialize(output, data);

Common exceptions thrown by the library:

• KeyValueException: Thrown when input is malformed.
• NotSupportedException: Thrown when converting a value to an incompatible type (e.g., casting a collection to an int).
• InvalidOperationException: Thrown when calling collection or array methods on a scalar value, or when calling source map methods on binary formats.

For text formats (KV1/KV3), you can use DeserializeWithSourceMap or SerializeWithSourceMap to obtain a collection of KvSourceSpan objects. Each span provides the Start offset, End offset, and TokenType (e.g., key, string, brace, comment, flag) for syntax highlighting or editor integration.

var kv = KVSerializer.Create(KVSerializationFormat.KeyValues3Text);

// Parsing with source map
string text = File.ReadAllText("file.kv3");
var (document, spans) = kv.DeserializeWithSourceMap(text);

foreach (var span in spans)
{
    var token = text.AsSpan(span.Start, span.End - span.Start);
    Console.WriteLine($"{span.TokenType}: {token}");
}

// Serializing with source map
var (output, outputSpans) = kv.SerializeWithSourceMap(document);

KV1 text files can use #include (appends keys) and #base (recursively merges keys) directives. The library does not access the file system directly; you must provide an IIncludedFileLoader via KVSerializerOptions.FileLoader to resolve these paths into Stream objects.

class DirectoryFileLoader(string directory) : IIncludedFileLoader
{
    public Stream OpenFile(string filePath)
    {
        return File.OpenRead(Path.Combine(directory, filePath));
    }
}

var options = new KVSerializerOptions
{
    FileLoader = new DirectoryFileLoader("C:/game/cfg"),
};

var kv = KVSerializer.Create(KVSerializationFormat.KeyValues1Text);
using var stream = File.OpenRead("C:/game/cfg/file.vdf");
var data = kv.Deserialize(stream, options);