toml

Pure-Luau TOML parser and emitter. Use whenever a script needs to read or write a TOML file — settings, importer rules, tool configs, or any other authored config the user touches by hand. Auto-injected as the global toml by the prelude — no require in user code.

vfs.read returns bytes. JSON has built-in parsing via json, but TOML — the format used for .world_settings, pyproject-style configs, and any human-friendly key=value file — needs a parser. toml provides one with no native dependency, so it works the same on native and WASM.

Exports

• toml.parse(src: string) -> { [string]: any } — TOML bytes to nested Luau table. Throws with the line number on syntax errors.
• toml.encode(root: { [string]: any }) -> string — Luau table to canonical TOML bytes (alphabetical section/key order; deterministic output).
• toml.replaceArrayTables(src: string, name: string, rows: { { [string]: any } }) -> string — replace every [[name]] block of a document with rows (appended at the end, one block each) and keep every other byte.

Usage

-- Parse
local body = vfs.read("/zero/source/myconfig.toml")
local config = toml.parse(body)
print(config.render.culling_mode)

-- Mutate + write back
config.render.culling_mode = "cpu"
vfs.write("/zero/source/myconfig.toml", toml.encode(config))

Supported TOML

• Sections, including dotted ([a.b.c])
• Arrays of tables ([[name]], [[a.b]]), with sub-tables of a row ([name.sub] after [[name]]); read as a sequence of tables and written back as one block per element
• Key/value pairs with dotted keys (a.b.c = 1)
• Strings: "..." (escaped) and '...' (literal); triple-quoted variants for multi-line bodies
• Integers (with _ digit separators) and floats (incl. inf, -inf, nan, exponents)
• Booleans (true / false)
• Inline arrays ([1, 2, 3])
• Inline tables ({ a = 1, b = 2 })
• # comments

Not implemented

These are rare in settings/config files; add when a real call site needs them rather than carrying dead code.

• Hex / octal / binary integer literals (0xff, 0o77, 0b1010)
• Date / time literals

Notes

• --!global toml directive promotes the module's typed functions onto the runtime universe's globals bucket, so toml.parse / toml.encode are available without any per-source require.
• The encoder is fully deterministic: sections and keys are sorted alphabetically, integer-shaped numbers are emitted without a decimal point (2 not 2.0), and nested tables become dotted section headers ([a.b]).
• Parser errors carry the line number for fast diagnosis.