> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/v4/getting-started/config.md).

# Config Reference

The `config.yml` file governs the global settings for BuildSystem. When modifying options, ensure values adhere to Spigot/Paper compatibility standards.

***

## Configuration Keys

### Global Settings (`settings`)

| Key                          | Default Value  | Description                                                                                                     |
| ---------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `update-checker`             | `true`         | Checks for new plugin updates on startup and notifies OPs on join.                                              |
| `scoreboard`                 | `true`         | Enables the default sidebar scoreboard framework.                                                               |
| `world-permission-whitelist` | `[]`           | Limit permissions that can be set via `/worlds setPermission`. An empty list `[]` allows any permission string. |
| `spawn-teleport-message`     | `false`        | Sends chat feedback when a player is teleported to a spawn point.                                               |
| `join-quit-messages`         | `true`         | Enables default join and quit broadcast messages on the server.                                                 |
| `date-format`                | `"dd/MM/yyyy"` | Pattern formatting timestamps in scoreboards and UI navigators.                                                 |

#### Archive Settings (`settings.archive`)

| Key               | Default Value | Description                                                                                |
| ----------------- | ------------- | ------------------------------------------------------------------------------------------ |
| `vanish`          | `true`        | Automatically hides players and grants invisibility inside archived worlds.                |
| `change-gamemode` | `true`        | Enforces the specified gamemode upon world entry.                                          |
| `world-gamemode`  | `"ADVENTURE"` | Target gamemode enforced inside archived worlds (requires `change-gamemode` to be `true`). |

#### Void Protection (`settings.save-from-death`)

| Key                     | Default Value | Description                                                                                                     |
| ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
| `enabled`               | `true`        | Prevents players from dying due to void/hazard damage.                                                          |
| `teleport-to-map-spawn` | `true`        | Teleports void-damaged players to the world spawn. If `false`, teleports the player 200 blocks upwards instead. |

#### Build Mode (`settings.build-mode`)

| Key          | Default Value | Description                                                                    |
| ------------ | ------------- | ------------------------------------------------------------------------------ |
| `drop-items` | `true`        | Allows item drops while in build mode (`/build`).                              |
| `move-items` | `true`        | Allows moving items across inventories (e.g. into chests) while in build mode. |

#### Builder Protections (`settings.builder`)

| Key                           | Default Value | Description                                                                                                    |
| ----------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------- |
| `block-worldedit-non-builder` | `true`        | Blocks WorldEdit commands (and brush actions) for players who are not registered builders of the target world. |

#### Navigator Settings (`settings.navigator`)

| Key                 | Default Value | Description                                                                     |
| ------------------- | ------------- | ------------------------------------------------------------------------------- |
| `item`              | `"CLOCK"`     | Item ID representing the world navigator.                                       |
| `give-item-on-join` | `true`        | Places the navigator clock in the player's inventory when they join the server. |

***

### World Operations (`world`)

| Key                  | Default Value                                | Description                                                                                  |
| -------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `lock-weather`       | `true`                                       | Prevents weather changes (locks weather to clear).                                           |
| `invalid-characters` | `"^\\b$"`                                    | RegEx defining characters to filter out from world names on creation.                        |
| `import-all-delay`   | `30`                                         | Delay (in seconds) between each world imported during `/worlds importAll` to avoid tick lag. |
| `deletion-blacklist` | `["world", "world_nether", "world_the_end"]` | List of world directories that cannot be deleted by any player.                              |

#### Disabled Physics (`world.disabled-physics`)

When world physics are toggled off, these properties define blocks' behaviors.

| Key                      | Default Value | Description                                                                      |
| ------------------------ | ------------- | -------------------------------------------------------------------------------- |
| `prevent-connections`    | `true`        | Prevents redstone connections, block updates, and double stone slab connections. |
| `prevent-fluid-flow`     | `true`        | Disables water/lava spreading.                                                   |
| `prevent-falling-blocks` | `true`        | Disables gravity checks on blocks like sand and gravel.                          |

#### Creation Limits (`world.limits`)

| Key       | Default Value | Description                                                                     |
| --------- | ------------- | ------------------------------------------------------------------------------- |
| `public`  | `-1`          | Maximum number of concurrent public worlds allowed. Set to `-1` for unlimited.  |
| `private` | `-1`          | Maximum number of concurrent private worlds allowed. Set to `-1` for unlimited. |

#### Defaults for New Worlds (`world.defaults`)

Applied automatically when a new world is generated.

| Key                        | Default Value         | Description                                                                     |
| -------------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `permission.public`        | `"-"`                 | Default permission required to enter public worlds (`-` means no permission).   |
| `permission.private`       | `"worlds.%world%"`    | Default permission required to enter private worlds.                            |
| `time.sunrise`             | `0`                   | Time in ticks representing sunrise.                                             |
| `time.noon`                | `6000`                | Time in ticks representing noon.                                                |
| `time.night`               | `18000`               | Time in ticks representing night.                                               |
| `worldborder-size`         | `60000000`            | Default worldborder size in blocks.                                             |
| `difficulty`               | `"PEACEFUL"`          | Default difficulty.                                                             |
| `gamerules`                | *(List of Gamerules)* | Gamerules automatically configured on creation (e.g. `doDaylightCycle: false`). |
| `builders-enabled.public`  | `false`               | Enforce the builder whitelist for public worlds.                                |
| `builders-enabled.private` | `true`                | Enforce the builder whitelist for private worlds.                               |
| `physics`                  | `true`                | Enables physics simulation.                                                     |
| `explosions`               | `true`                | Enables explosion damage.                                                       |
| `mob-ai`                   | `true`                | Enables mob intelligence.                                                       |
| `block-breaking`           | `true`                | Allows blocks to be broken.                                                     |
| `block-placement`          | `true`                | Allows blocks to be placed.                                                     |
| `block-interactions`       | `true`                | Allows block right-click interactions.                                          |

#### Auto Unload (`world.unload`)

| Key                  | Default Value    | Description                                                                              |
| -------------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| `enabled`            | `true`           | Automatically unloads empty worlds to conserve RAM.                                      |
| `time-until-unload`  | `"01:00:00"`     | Formatted string `HH:mm:ss` defining how long a world can remain empty before unloading. |
| `blacklisted-worlds` | `["world", ...]` | Worlds that will never be automatically unloaded.                                        |

#### Backup Configurations (`world.backup`)

| Key                              | Default Value | Description                                               |
| -------------------------------- | ------------- | --------------------------------------------------------- |
| `max-backups-per-world`          | `5`           | Maximum retained backups per world (clamped to 18 max).   |
| `auto-backup.enabled`            | `true`        | Enables automatic background backup schedules.            |
| `auto-backup.interval`           | `900`         | Backup frequency in seconds.                              |
| `auto-backup.only-active-worlds` | `true`        | Only backs up worlds where players are actively building. |

#### Storage Types (`world.backup.storage`)

* `storage.type`: Can be `local`, `s3`, or `sftp`.
* **S3 configurations (`s3`)**: Includes `url` (optional, for custom endpoints), `access-key`, `secret-key`, `region`, `bucket`, and `path`.
* **SFTP configurations (`sftp`)**: Includes `host`, `port`, `username`, `password`, and `path`.

***

### Folder Settings (`folder`)

| Key                    | Default Value | Description                                                                       |
| ---------------------- | ------------- | --------------------------------------------------------------------------------- |
| `override-permissions` | `true`        | Worlds placed in a folder automatically inherit the folder's parent permission.   |
| `override-projects`    | `false`       | Worlds placed in a folder automatically inherit the folder's parent project name. |

***

## Dropped Configuration Flags (Removed in 4.0.0)

Version 4.0.0 completely removed the following toggle flags. Permissive states are now handled via a **default-allow** model through standard permission nodes:

* `settings.per-option-permissions`: Replaced by `buildsystem.setting.<option>`. All options are allowed by default; deny specific nodes to restrict players.
* `settings.restrict-template-access`: Replaced by dynamic permission nodes `buildsystem.create.template.<name>` and `buildsystem.create.generator.<name>`.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://buildsystem.eintosti.de/v4/getting-started/config.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.