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
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.
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:
Whereas this comment will not be excluded from the value: