> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lootroute.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> volvox.Config — the per-character JSON persistence layer.

`volvox.Config` (defined in `Util/Config.lua`) reads and writes JSON settings files under `scripts/LootRoute/`, keyed by character and realm, with in-memory caching.

## Storage

* **Path template:** `scripts/LootRoute/DemonGUISettings<CharacterName><RealmName>.json` (relative to `C:/WGG/`; realm whitespace stripped; either piece falls back to `"Unknown"` during early login). The directory is created on load if missing.
* **Key format:** flat dotted-namespace strings — e.g. `gatherer.enabled`, `general.tickrate`, `modules.gatherer`. Keys are top-level entries in the JSON object, not nested tables.
* File I/O and JSON resolve through [`volvox.ResolveApiFunction`](/framework/utilities), so the layer works across WGG API naming variants. Profile decoding accepts both direct table returns and WGG's Lua-source string return form. If a profile exists only at the legacy `scripts/Gatherer/` or `configs/Demon/` path, it is read once and migrated to `scripts/LootRoute/`.

## Read fallback chain

`Config:Read` resolves a value in this order:

1. **Stored value** in the cached per-character profile
2. **Registered default** (set via `SetDefault`)
3. **Caller-supplied `default`** argument

## API

### Read

```lua theme={null}
---@param key string
---@param default? any
---@return any value
Config:Read(key, default)
```

Reads a config value using the fallback chain. Refreshes the cache first, so character switches are picked up automatically.

### Write

```lua theme={null}
---@param key string
---@param value any
---@return boolean saved
Config:Write(key, value)
```

Sets the key in the in-memory cache and persists the **entire profile** to disk immediately (JSON-encoded). Returns `true` only when WGG accepts the file write.

### SetDefault

```lua theme={null}
---@param key string
---@param value any
Config:SetDefault(key, value)
```

Registers an in-memory fallback default. `SetDefault` does not write unset defaults to disk; a key appears in the profile JSON only after `Config:Write` persists it. [GUI builder](/framework/gui-builder) widgets call this automatically for every keyed widget.

### GetAll

```lua theme={null}
---@return table settings
Config:GetAll()
```

Returns a shallow copy of all stored settings for the active profile (excluding `function`/`userdata` values). Empty table when no profile exists.

### ClearCache

```lua theme={null}
Config:ClearCache()
```

Resets the profile cache so the next access reloads from disk.

## Example

```lua theme={null}
volvox.Config:SetDefault("myfeature.threshold", 25)

local threshold = volvox.Config:Read("myfeature.threshold")      -- 25
volvox.Config:Write("myfeature.threshold", 40)                   -- persisted immediately
local all = volvox.Config:GetAll()                               -- stored settings only
```

<Note>
  The status toggle frame ([`volvox:AddGlobalToggle`](/framework/interface#global-status-toggles)) uses its **own** persistence file, `scripts/LootRoute/DemonStatusFrame.json`, independent of `volvox.Config`, with legacy read fallbacks from `scripts/Gatherer/DemonStatusFrame.json` and `configs/Demon/DemonStatusFrame.json`.
</Note>