config

Voxel engine configuration. Single source of truth for every VFS path the voxel system touches (shapes, worlds, templates, baked records, captures) plus the small set of default knobs (chunkSize, defaultBlockSize, defaultMesher, cpuFallback, allowPlayWrites).

Three-layer resolution (highest precedence first): runtime overrides set via Config.set → [voxel] section of /WORLD_SETTINGS (TOML) → built-in DEFAULTS. The DEFAULTS table is the only place those paths and knobs are defined; every other module reads them via Config.get.

When issue #1256 lands a proper per-world / library-scoped config system, the internals swap to that API. The public surface — get / set / reset / all — is stable and must not change.

Exports

• M.get(key: string) -> any — read a config value by dotted key. Raises if key is unknown.
• M.set(key: string, value: any) — install a runtime override. Raises if key is unknown.
• M.reset(key: string?) — clear runtime overrides. With no arg, clears every override. Raises if key is a string but unknown.
• M.all() -> table — deep copy of the fully-merged config. Mutating the result is safe; it doesn't touch live state.

Usage

local Config = require("@builtin::systems.voxelEngine.voxelEngine.config")

local shapesDir = Config.get("paths.shapes")  -- "/source/voxel/shapes"
local chunk     = Config.get("chunkSize")      -- 32

Config.set("chunkSize", 16)
Config.reset("chunkSize")  -- back to DEFAULTS / WORLD_SETTINGS

Notes

• Dotted keys descend the DEFAULTS tree segment by segment. "paths.shapes" walks DEFAULTS.paths.shapes; any segment missing yields an unknown-key error.
• set does not validate the value's shape — pass mistyped data and get will return it verbatim. Validation lives at the caller / consumer site.
• all runs the same resolution chain get does, just in bulk, and returns a deep copy so callers can mutate freely.
• Do not inline /source/voxel/... literals elsewhere — every consumer reads paths through Config.get so a single override repoints them all.