TOML syntax

NPC files are written in TOML, a plain text format made of key = value lines and [tables]. This page lists what NPC Helper 2 reads. NPC files themselves only need a small part of it.

The parts you will use#

# A comment starts with a hash.
Name = "Rei"                 # text goes in double quotes
Day = 12                     # numbers have no quotes
Datable = true               # booleans are true or false
Love = ["Diamond", "Coffee"] # lists use square brackets

[Birthday]                   # a table groups related keys
Season = "Summer"

• Text is written in double quotes. Use \" for a quote inside a quoted text, or write the text in single quotes ('literal text') or in triple quotes ("""multi-line text""") when it contains many quotes.
• Tables such as [Personality] start a group. Every key after it belongs to that table until the next [table].
• Lists hold several values of one kind, and can span several lines.
• Comments start with # and are ignored.

Everything NPC Helper 2 reads#

NPC Helper 2 reads TOML 1.0 and also accepts the \e and \xHH escapes from TOML 1.1. That includes:

• comments, nested and dotted tables, arrays of tables ([[name]]), and inline tables
• all four string forms
• decimal, hexadecimal, octal, and binary integers, and floats including inf and nan
• booleans, and offset and local date-times, dates, and times

NPC files only use tables, text, numbers, booleans, and lists.

Dotted keys#

An unquoted key that contains a dot (a.b = 1) is a dotted key and creates a table named a. Quote the key ("a.b" = 1) to keep the dot as part of the name.

Lenient and strict reading#

By default NPC files are read leniently, so older packs keep loading:

• Unquoted text values (Gender = female) are accepted with a warning.
• Numbers such as 0600 are accepted with a warning.
• Repeated keys or tables and unusual key characters are accepted with a warning.
• True is read as a boolean.
• Key and table names are not case-sensitive.

Quote your text values and fix the warnings.

Strict reading turns these into errors and makes names case-sensitive. To read a whole pack strictly, set StrictToml = true in mod.toml (see Pack structure). That setting keeps NPC Helper 2's own case-insensitive names and only tightens the TOML grammar. In C#, the same mode is available through TomlParseOptions.Strict.

Error messages#

Syntax problems are reported with their file and line number. Parsing continues after a problem, so one run shows all of them. Unknown keys and tables are reported separately as possible typos.

Limits#

A TOML file may be at most 4 MB, and lists may be nested at most 16 levels deep. A larger file is rejected with a message.