---
title: "toml"
description: "The toml namespace — the engine's Luau API reference for toml."
section: "API Reference"
slug: "api-toml"
canonical: "https://origozero.ai/docs/api-toml"
updated: "2026-09-05T23:13:47.355617470+00:00"
tags: ["api", "reference"]
---

# toml

The `toml` namespace — 4 functions.

## globals/toml/encode {#globals-toml-encode}

```lua
toml.encode(root: { [string]: any }) -> string
```

Encode a Luau table as canonical TOML bytes. Top-level
string-keyed sub-tables become section headers ([name]); deeper
string-keyed tables become dotted sections ([a.b]). Sequence
tables are emitted as inline arrays, and string-keyed tables in
value position (e.g. array elements) as inline tables ({ k = v }).
Section + key order is alphabetical so the same input always
produces the same bytes.

**Parameters**

- `root` `{ [string]: any }` — The table to encode. Must be string-keyed at the root.

**Returns** `string` — A TOML-formatted string suitable for `vfs.write`.

```lua
local body = toml.encode({ render = { culling_mode = "gpu" } })
```

## globals/toml/parse {#globals-toml-parse}

```lua
toml.parse(src: string) -> { [string]: any }
```

Parse a TOML document into a nested Luau table. Sections
([a.b]) become nested tables; key/value pairs become entries
on the current section (or root if before any section header).
Throws with the line number on syntax errors.

**Parameters**

- `src` `string` — TOML source bytes as a string.

**Returns** `{ [string]: any }` — The parsed root table. Sub-tables are plain Luau tables; arrays are 1-indexed sequence tables.

```lua
local t = toml.parse('[a]\nx = 1\ny = "hi"\n')
```

## typed/builtin//modules/toml/toml/encode {#typed-builtin-modules-toml-toml-encode}

```lua
toml.encode(root: { [string]: any }) -> string
```

Encode a Luau table as canonical TOML bytes. Top-level
string-keyed sub-tables become section headers ([name]); deeper
string-keyed tables become dotted sections ([a.b]). Sequence
tables are emitted as inline arrays, and string-keyed tables in
value position (e.g. array elements) as inline tables ({ k = v }).
Section + key order is alphabetical so the same input always
produces the same bytes.

**Parameters**

- `root` `{ [string]: any }` — The table to encode. Must be string-keyed at the root.

**Returns** `string` — A TOML-formatted string suitable for `vfs.write`.

```lua
local body = toml.encode({ render = { culling_mode = "gpu" } })
```

## typed/builtin//modules/toml/toml/parse {#typed-builtin-modules-toml-toml-parse}

```lua
toml.parse(src: string) -> { [string]: any }
```

Parse a TOML document into a nested Luau table. Sections
([a.b]) become nested tables; key/value pairs become entries
on the current section (or root if before any section header).
Throws with the line number on syntax errors.

**Parameters**

- `src` `string` — TOML source bytes as a string.

**Returns** `{ [string]: any }` — The parsed root table. Sub-tables are plain Luau tables; arrays are 1-indexed sequence tables.

```lua
local t = toml.parse('[a]\nx = 1\ny = "hi"\n')
```