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

# settings

The `settings` namespace — 14 functions.

## globals/settings/all {#globals-settings-all}

```lua
settings.all() -> { [string]: any }
```

Snapshot of the entire settings document (parsed). Modifying
the returned table does NOT propagate — call `set` or `setMany`
to persist. Useful for editors/inspectors that render every
section.

**Returns** `{ [string]: any }` — A nested table mirroring the TOML document.

```lua
for section, keys in pairs(settings.all()) do
```

## globals/settings/get {#globals-settings-get}

```lua
settings.get(key: string) -> any
```

Look up a value by dotted key. Returns whatever the file
holds at that path — string / number / boolean / array / table —
or nil if missing.

**Parameters**

- `key` `string` — Dotted-path key, e.g. `"render.culling_mode"`.

**Returns** `any` — The raw value at that key, or nil.

```lua
local mode = settings.get("render.culling_mode")
```

## globals/settings/getBool {#globals-settings-getbool}

```lua
settings.getBool(key: string, default: boolean?) -> boolean
```

Boolean-typed accessor. Returns the value when present and
boolean-typed; falls back to `default` (or false) on missing key
or type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `boolean` _(optional)_ — Optional fallback boolean.

**Returns** `boolean` — The boolean value or the fallback.

```lua
if settings.getBool("render.shadows", true) then ... end
```

## globals/settings/getNumber {#globals-settings-getnumber}

```lua
settings.getNumber(key: string, default: number?) -> number
```

Number-typed accessor. Returns the value when present and
number-typed; falls back to `default` (or 0) on missing key or
type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `number` _(optional)_ — Optional fallback number.

**Returns** `number` — The number value or the fallback.

```lua
local g = settings.getNumber("physics.gravity", -9.81)
```

## globals/settings/getString {#globals-settings-getstring}

```lua
settings.getString(key: string, default: string?) -> string
```

String-typed accessor. Returns the value when present and
string-typed; falls back to `default` (or "" if omitted) on
missing key or type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `string` _(optional)_ — Optional fallback string.

**Returns** `string` — The string value or the fallback.

```lua
local mode = settings.getString("render.culling_mode", "gpu")
```

## globals/settings/set {#globals-settings-set}

```lua
settings.set(key: string, value: any?)
```

Set a value by dotted key, then serialize and write the
file. In play mode the write fails like any other source-file
write — call `wld.edit()` first to unlock.

**Parameters**

- `key` `string` — Dotted-path key.
- `value` `any` _(optional)_ — Replacement value (string / number / boolean / table).

```lua
settings.set("render.culling_mode", "cpu")
```

## globals/settings/setMany {#globals-settings-setmany}

```lua
settings.setMany(updates: { [string]: any })
```

Apply many key/value updates in one batched write — fewer
serialize+write round-trips than calling `set` per-key. Same
lock semantics as `set`.

**Parameters**

- `updates` `{ [string]: any }` — A table of dotted-key → value pairs.

```lua
settings.setMany({
```

## typed/builtin//modules/settings/settings/all {#typed-builtin-modules-settings-settings-all}

```lua
settings.all() -> { [string]: any }
```

Snapshot of the entire settings document (parsed). Modifying
the returned table does NOT propagate — call `set` or `setMany`
to persist. Useful for editors/inspectors that render every
section.

**Returns** `{ [string]: any }` — A nested table mirroring the TOML document.

```lua
for section, keys in pairs(settings.all()) do
```

## typed/builtin//modules/settings/settings/get {#typed-builtin-modules-settings-settings-get}

```lua
settings.get(key: string) -> any
```

Look up a value by dotted key. Returns whatever the file
holds at that path — string / number / boolean / array / table —
or nil if missing.

## typed/builtin//modules/settings/settings/getBool {#typed-builtin-modules-settings-settings-getbool}

```lua
settings.getBool(key: string, default: boolean?) -> boolean
```

Boolean-typed accessor. Returns the value when present and
boolean-typed; falls back to `default` (or false) on missing key
or type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `boolean` _(optional)_ — Optional fallback boolean.

**Returns** `boolean` — The boolean value or the fallback.

```lua
if settings.getBool("render.shadows", true) then ... end
```

## typed/builtin//modules/settings/settings/getNumber {#typed-builtin-modules-settings-settings-getnumber}

```lua
settings.getNumber(key: string, default: number?) -> number
```

Number-typed accessor. Returns the value when present and
number-typed; falls back to `default` (or 0) on missing key or
type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `number` _(optional)_ — Optional fallback number.

**Returns** `number` — The number value or the fallback.

```lua
local g = settings.getNumber("physics.gravity", -9.81)
```

## typed/builtin//modules/settings/settings/getString {#typed-builtin-modules-settings-settings-getstring}

```lua
settings.getString(key: string, default: string?) -> string
```

String-typed accessor. Returns the value when present and
string-typed; falls back to `default` (or "" if omitted) on
missing key or type mismatch.

**Parameters**

- `key` `string` — Dotted-path key.
- `default` `string` _(optional)_ — Optional fallback string.

**Returns** `string` — The string value or the fallback.

```lua
local mode = settings.getString("render.culling_mode", "gpu")
```

## typed/builtin//modules/settings/settings/set {#typed-builtin-modules-settings-settings-set}

```lua
settings.set(key: string, value: any?)
```

Set a value by dotted key, then serialize and write the
file. In play mode the write fails like any other source-file
write — call `wld.edit()` first to unlock.

## typed/builtin//modules/settings/settings/setMany {#typed-builtin-modules-settings-settings-setmany}

```lua
settings.setMany(updates: { [string]: any })
```

Apply many key/value updates in one batched write — fewer
serialize+write round-trips than calling `set` per-key. Same
lock semantics as `set`.

**Parameters**

- `updates` `{ [string]: any }` — A table of dotted-key → value pairs.

```lua
settings.setMany({
```