settings

World-settings reader and writer for /zero/source/.world_settings. The single canonical surface for any script that needs to read or mutate engine settings (renderer culling, physics gravity, LSP strictness, startup scene, etc.). Auto-injected as the global settings by the prelude — user code never needs to require this module.

Settings live in a TOML file inside the world's manifest. Reads always re-parse the file so callers see the live state (no stale cache); writes go through vfs.write, so play mode locks settings the same as any other source file. Call wld.edit() first to unlock for mid-play writes.

Exports

• settings.get(key: string) -> any — raw value at a dotted key, or nil.
• settings.getString(key: string, default?: string) -> string — type-narrowed string accessor.
• settings.getNumber(key: string, default?: number) -> number — type-narrowed number accessor.
• settings.getBool(key: string, default?: boolean) -> boolean — type-narrowed boolean accessor.
• settings.set(key: string, value: any) — set + write.
• settings.setMany(updates: { [string]: any }) — batched set + single write.
• settings.all() -> { [string]: any } — snapshot of the full settings document.

Usage

-- Read
local mode = settings.getString("render.culling_mode", "gpu")
local gravity = settings.getNumber("physics.gravity", -9.81)
if settings.getBool("render.shadows", true) then ... end

-- Write
settings.set("render.culling_mode", "cpu")
settings.setMany({
    ["render.culling_mode"] = "cpu",
    ["physics.gravity"] = -3.7,
})

-- Inspect everything
for section, keys in pairs(settings.all()) do
    print("[" .. section .. "]")
    for k, v in pairs(keys) do print("  " .. k .. " =", v) end
end

Notes

• The typed accessors (getString / getNumber / getBool) fall back to the documented default ("" / 0 / false) on type mismatch — they never coerce.
• Modifying the snapshot returned by settings.all() does NOT propagate. Persist changes with set or setMany.
• Each get* re-reads the file. Settings access is infrequent enough that the parse cost is negligible; the trade-off is no stale-cache class of bug from foreign writes.