Config Binary Format
This page describes the binary format used for serializing and deserializing the config.toml file.
The binary format is designed to be compact and efficient for storing and loading configuration settings.
Format Overview
The binary format consists of a header followed by a series of key-value pairs representing the configuration settings.
All numbers are stored as little endian.
Header
The header is a single byte containing version and key size information.
| Bits | Description |
|---|---|
| 0-2 | Version number, 0-7. Currently 0, 1 and 2 are used. |
| 3-5 | Reserved |
| 6-7 | Key size in bytes. 1, 2, 4, or 8 |
The higher bits of the version number may be repurposed some day.
Currently 2 versions exist:
Version 0: (Basic Types only)Version 1: (Extended Types)Version 2: (Hardware Types)
Version 0 allows for twice amount of items if the config only uses basic primitives. That is the case for most mods at least.
Key-Value Pairs
Following the header, the file contains a sequence of key-value pairs.
The size of the key depends on the header, so if the key size is set to
2, the Index for Version 0 will have 13 bits available
(instead of 5 bits).
Key (Version 0)
| Index (0-3) | ValueType (4-7) |
|---|---|
{XXXX} |
{YYYY} |
| Data Type | Name | Label | Description |
|---|---|---|---|
u5 |
Index | X | (0-31) Corresponds to Index |
u3 |
ValueType | Y | (0-7) Type of Value (V0) stored. |
Key (Version 1)
| Index (0-4) | ValueType (5-7) |
|---|---|
{XXXXX} |
{YYY} |
| Data Type | Name | Label | Description |
|---|---|---|---|
u4 |
Index | X | (0-15) Corresponds to Index |
u4 |
ValueType | Y | (0-15) Type of Value (V1) stored. |
Key (Version 2)
| Index (0-4) | ValueType (5-7) |
|---|---|
{XXXXX} |
{YYY} |
| Data Type | Name | Label | Description |
|---|---|---|---|
u3 |
Index | X | (0-7) Corresponds to Index |
u5 |
ValueType | Y | (0-31) Type of Value (V2) stored. |
Value
Version 0 (Table)
| Type | Name | Size (bytes) |
|---|---|---|
| 00 | Bool (ON) | 0 |
| 01 | Bool (OFF) | 0 |
| 02 | i8 | 1 |
| 03 | i16 | 2 |
| 04 | i32 | 4 |
| 05 | i64 | 8 |
| 06 | f32 | 4 |
| 07 | String | Variable |
Version 1 (Table)
This is an extension of Version 0 table
This table has additional entries for more rarely seen types
| Type | Name | Size (bytes) |
|---|---|---|
| 00 | Bool (ON) | 0 |
| 01 | Bool (OFF) | 0 |
| 02 | i8 | 1 |
| 03 | i16 | 2 |
| 04 | i32 | 4 |
| 05 | i64 | 8 |
| 06 | f32 | 4 |
| 07 | String | Variable |
| 08 | u8 | 1 |
| 09 | u16 | 2 |
| 0A | u32 | 4 |
| 0B | u64 | 8 |
| 0C | f64 | 8 |
| 0D | StringList | Variable |
| 0E | i24 | 3 |
| 0F | Reserved | N/A |
Version 2 (Table)
This is an extension of Version 1 table
This table has additional entries for Hardware
| Type | Name | Size (bytes) |
|---|---|---|
| 00 | Bool (ON) | 0 |
| 01 | Bool (OFF) | 0 |
| 02 | i8 | 1 |
| 03 | i16 | 2 |
| 04 | i32 | 4 |
| 05 | i64 | 8 |
| 06 | f32 | 4 |
| 07 | String | Variable |
| 08 | u8 | 1 |
| 09 | u16 | 2 |
| 0A | u32 | 4 |
| 0B | u64 | 8 |
| 0C | f64 | 8 |
| 0D | StringList | Variable |
| 0E | i24 | 3 |
| 0F | Reserved | N/A |
| 10 | Resolution | 4 |
| 11 | Resolution+RefreshRate | 6 |
| 12 | Controller Config | Variable |
Value Mapping
The schema's settings map in the following way:
| Type | Value Type |
|---|---|
| Boolean | Bool ON/OFF |
| Enum | u8/16/32/64 |
| Integer & Int Range | (i/u)(8/16/32/64) |
| Float & Float Range | (f32/f64) |
| File, Folder, URL | (string) |
| Color | (i24) or (i32/u32) |
Color Setting
A color setting is serialized as 4 bytes in RGBA order.
| Byte | Channel |
|---|---|
| 0 | Red |
| 1 | Green |
| 2 | Blue |
| 3 | Alpha |
If the alpha channel is not present, the value serialized as an 03 (i24), otherwise it's stored
as an 07 i32.
String List Setting
A string list setting is serialized as a series of null-terminated UTF-8 strings.
Followed by an additional null byte to indicate the end of the list. i.e. an empty string.
Hardware Types
Resolution
This corresponds to Resolution Dropdown
This is stored as a 4 byte value.
It is u16 width and u16 height.
Resolution and Refresh Rate
This corresponds to Resolution & Refresh Rate Dropdown
This is stored as u16 width and u16 height.
Then u16 refresh rate.
I am aware that DirectX supports fractional refresh rates with rationals.
However, no other APIs do, and modern displays don't use these refresh rates.
Controller Config
This is an entire embedded file within the config format.
Format of the data is described in Controller Binary Format
Extra Reading:
Parsing the File
Read the key-value pairs until you reach the end of file.
It's that simple.
Optimizing Compression Efficiency
To maximize compression efficiency, we use a couple of tricks.
SOLID Compression
To optimize for SOLID compression, we write the values in the index order.
This increases the amount of repeating bytes between two given settings files in the same block.
For example, when packed as part of Loadout.