> For the complete documentation index, see [llms.txt](https://docs.onelitefeather.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onelitefeather.net/background/how-settings-are-loaded.md).

# How settings are loaded

BetterGoPaint reads `config.yml` once on start and again on every `/gopaint reload`. Each read produces a complete, fixed snapshot of all values. The plugin swaps the old snapshot for the new one in one step, so a builder never paints with half-old, half-new settings.

```mermaid
flowchart TD
    start["Start: SettingsHolder constructor"] --> load["SettingsLoader.load(file)"]
    reload["/gopaint reload: GoPaintCommand.reload"] --> holder["SettingsHolder.reload()"]
    holder --> load
    load --> exists{"config.yml exists?"}
    exists -- yes --> read["Read the file"]
    exists -- no --> blank["Empty configuration:<br/>every key gets its default"]
    read --> key["Reader.read: next key"]
    blank --> key
    key --> valid{"Value present and valid?"}
    valid -- no --> warn["Warning for this key,<br/>use the default"]
    valid -- yes --> use["Use the parsed value"]
    warn --> put["Set the value and its comment"]
    use --> put
    put --> more{"More keys?"}
    more -- yes --> key
    more -- no --> save["Save the whole file"]
    save --> snapshot["New immutable Settings"]
    snapshot --> store["SettingsHolder keeps it as the<br/>current snapshot (start: constructor,<br/>reload: set)"]
    store --> readers["Every reader calls settings.get()<br/>when it needs a value"]
    store -. start only .-> check{"BetterGoPaint.onEnable:<br/>default brush is an item?"}
    check -- no --> disable["Plugin disables itself"]
```

## Invalid values

The file is read key by key. A value that cannot be used, such as text where a number belongs or a material that does not exist, does not stop the plugin. That key gets its default and the console shows one warning for each such key. Then BetterGoPaint writes the whole file back with every key, its effective value and its comment, which is how new keys appear after an update.

The brush item is the exception. If `generic.default-brush` names a material that cannot be held as an item, nobody can hold the brush. On start the plugin then disables itself; after a reload it keeps running, but painting with the default brush is impossible until the value is fixed.

## What a reload changes

A reload affects everything that is read when it is used: the brush item, disabled worlds, the prefix and every maximum. Builders who already have a brush keep their current size, mask and other choices; the new `default-*` values apply to builders who pick up a brush for the first time after the reload, for example after rejoining.

Two keys are read only on start, so changing them needs a restart:

* `generic.languages`, because translations are registered once.
* `generic.check-for-updates`, because the update check is scheduled once.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.onelitefeather.net/background/how-settings-are-loaded.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.