Data File Format

This article describes the syntax of Unturned’s .dat and .asset files.

Each line is a key-value pair separated by a space. The key and/or value can optionally be in quotes. For example:

Key1 First value
"Key2 in quotes" Second value
Key3 "Third value"

Will be parsed as:

"Key1" = "First value"
"Key2 in quotes" = "Second value"
"Key3" = "Third value"

The only reason to quote a value is to enable comments on the same line. Quotation marks within a quoted key/value can be escaped with a \ backslash. For example "a \"b\" c" is parsed with quotation marks around b. Keys support quotes in case a space is required, but no keys in the vanilla game use spaces.

Note

Keys are case-insensitive. i.e., Use_Cool_Option true and UsE_cOoL_oPtIoN true are identical. Keys should be unique within their dictionary.

Acceptable values for a key will depend on their data type. Most—but not all—properties will use one of the C# built-in types.

Objects / Dictionaries

Each series of key-value pairs is a dictionary (sometimes called an object). The top level of the file is treated as a dictionary, and child dictionaries can be added with { } curly braces. Adding { on the line after a key opens a dictionary, and the matching } closes it.

In this example object1 is a child dictionary in the root dictionary, and object2 is a grand-child:

object1
{
        object2
        {
                key value
        }
}

Arrays / Lists

Lists (sometimes called an array) can be added with [ ] square brackets. Adding [ on the line after a key opens a list, and the matching ] closes it.

In this example values is a list of strings:

values
[
        first value
        second value
        third value
]

Lists can also contain dictionaries as seen in this example:

List_Of_Objects
[
        {
                x 1
                y 2
        }
        {
                x 3
                y 4
        }
]

Note

Many older asset properties predate the addition of lists. In these cases arrays/lists are typically handled by a key specifying the number of items, and then appending the index number to each element’s key. For example:

// Total number of elements in old-style list
Elements 2

// First element has an index of 0
Element_0 A

// Second element has an index of 1
Element_1 B

Comments

Lines starting with // are comments, which means they are excluded from parsing. Comments can be useful for adding helpful, explanatory notes inside an asset. Comments can also be added to the end of a line if the value is quoted.

For example these comments are valid:

// a comment
key1 value1
key2 "value2" // in-line comment

Whereas this comment will not be excluded from the value:

key value // this is not treated as a comment because the value is not in quotes

FAQ (Frequently Asked Questions)

Q. How do I write a multi-line value?

The \n escape sequence starts a new line. For example:

Text First line\nSecond line

Will set the value of Text to:

First line
Second line

Q. How do I write an in-line comment after a value containing quotation marks?

In-line comments require the value to enclosed in quotation marks, so quotation marks in the value must be escaped with \":

// The parser will read the comment as part of the value because it doesn't know where the value ends.
Text Why use so-called "scare quotes" instead of /s? // Comment here

// The parser will exclude the comment from the value and replace the \" with quotation marks.
Text "Why use so-called \"scare quotes\" instead of /s?" // Comment here

Q. Why can’t I start a list or dictionary on the same line as a key?

This is—unfortunately—not supported because it would break backwards compatibility with the oldest .dat files. Older files may have [ or { as the first letter of a value.

As an example of the problem:

SomeDictionary {
        SomeList [
        ]
}

Instead, the opening [ or { must be placed on the next line:

SomeDictionary
{
        SomeList
        [
        ]
}

History

Prior to the 3.23.6.0 update there were two sets of custom Unturned syntax: “v1” for .dat files, and “v2” for .asset files. Assets using v1 syntax only supported key-value pairs, whereas v2 introduced dictionaries, lists, and required keys/values to be quoted.

This is why { and [ must be on a new line, as existing v1 assets may have { or [ as the first character of a value.