> 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/reference/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. | #### Void Block (`world.void-block`) The block placed at the spawn of newly generated void worlds so players do not fall on first join. It is placed only on initial generation, never on later loads, imports, or renames, and only if the position is still empty. | Key | Default Value | Description | | ---------- | ------------- | -------------------------------------------------------------------------- | | `enabled` | `true` | Whether to place the block at all. | | `material` | `GOLD_BLOCK` | The block material. Invalid or non-block values fall back to `GOLD_BLOCK`. | #### Creation Limits (`world.limits`) How many worlds **one player** may create, applied only to players holding no `buildsystem.create..` permission node of their own. A node always overrides these values, and `buildsystem.admin` ignores both. See [World Creation Rules](/permissions-and-access/creating-worlds.md). | Key | Default Value | Description | | --------- | ------------- | -------------------------------------------------------------- | | `public` | `-1` | Default maximum public worlds per player. `-1` for unlimited. | | `private` | `-1` | Default maximum private worlds per player. `-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` | `6000000` | Default worldborder size in blocks. | | `difficulty` | `"PEACEFUL"` | Default difficulty. | | `gamerules` | *(List of Gamerules)* | Game rules applied on creation, keyed by rule name (defaults: `advance_time`, `spawn_mobs`, `fire_damage`, all `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. | | `physics-exceptions.` | `false` | Behaviors that still run while a world's physics are disabled. Categories: `block-updates`, `connections`, `falling-blocks`, `fluid-flow`, `leaf-decay`, `growth`, `spreading`, `block-forming`, `block-fading`. Seeds new worlds and worlds without stored values; manage per world via the physics menu (right-click the physics toggle in `/worlds edit`). Replaces the old `world.disabled-physics` section. Existing configs migrate automatically (`prevent-x: false` becomes `x: true`). | | `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). | | `storage` | `local` | Which backend backups are written to: `local`, `s3` or `sftp`. Credentials come from the root [`storage`](#external-storage-storage) section. | | `path` | `backups/worlds/` | Where backups live within that backend. Ignored by `local`. | | `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. | #### World Downloads (`world.download`) Serves `/worlds download` archives. Off by default: enabling it hands out world data. | Key | Default Value | Description | | -------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | `false` | Turns downloads on. | | `storage` | `local` | `local` serves archives from the built-in HTTP server. `s3` uploads them to the bucket in the root [`storage`](#external-storage-storage) section and hands out pre-signed links. | | `port` | `8080` | Port the built-in server listens on. Unused on `s3`. | | `url` | `"http://localhost:8080"` | Base address players are linked to. Change it when the port is reached through a proxy or a domain. Unused on `s3`. | | `behind-proxy` | `false` | Take the client's address from `X-Forwarded-For` instead of the socket. Enable only when the port is reachable solely through a reverse proxy. Unused on `s3`. | | `expiration-minutes` | `30` | How long a link stays valid. The archive is deleted when it expires. | | `max-size-mb` | `2048` | Largest single export. A world that grows past it is aborted rather than written. `local` only. | | `max-storage-mb` | `8192` | Budget shared by all live downloads. New exports are refused while it is full. `local` only. | | `max-concurrent-downloads` | `3` | Transfers served at once. Further requests get `503` with `Retry-After`. `local` only. | On `local`, each export is reachable only through a random 256-bit token that forms the whole URL path, so no request can name a file or reach anything outside `plugins/BuildSystem/downloads`. A link is pinned to the first client that uses it, requests are rate limited to 30 per minute per address, and archives are deleted on expiry, reload and shutdown. The built-in server speaks plain HTTP - put it behind a reverse proxy and point `url` at the HTTPS address. BuildSystem logs a warning on startup while `url` is not `https://`, because a token in a plaintext URL can be reused by anything that observes the traffic. Behind such a proxy, every request arrives from the proxy's own address, which would pin all links to one identity and pool every player into a single rate limit. Set `behind-proxy: true` to key both on the last `X-Forwarded-For` entry instead - the last is the one your proxy appended, so a client cannot forge it. Leave it `false` whenever the port is reachable directly, or anyone could send that header and claim any address. `storage: s3` reads the root `storage.s3` section. Backups do **not** have to be on S3 for it to work - the two features pick their backend independently. Archives upload in parts under the `downloads/` prefix, so no size limit applies and nothing has to be reachable from outside. The link is https and signed by S3, but unlike a local link it is a plain bearer token - it cannot be pinned or rate limited, and works for anyone it is forwarded to until it expires. Uploads are deleted when their link expires, and leftovers from a crash are cleared at the next startup. ### External Storage (`storage`) Credentials for the services BuildSystem can talk to, defined once at the root and selected by name wherever a feature needs one (`world.backup.storage`, `world.download.storage`). A section only matters once something selects it, and one definition serves every feature that does - the same bucket for backups and downloads, configured once. ```yaml storage: s3: url: null access-key: YOUR_ACCESS_KEY secret-key: YOUR_SECRET_KEY region: eu-central-1 bucket: buildsystem-backups sftp: host: YOUR_SFTP_HOST port: 22 username: YOUR_SFTP_USERNAME password: YOUR_SFTP_PASSWORD ``` * **`s3`**: `url`, `access-key`, `secret-key`, `region`, `bucket`. Leave `url` empty for Amazon S3 - it is only needed to point at an S3-compatible service such as MinIO, Backblaze B2 or Cloudflare R2. `region` must match the bucket's actual region. * **`sftp`**: `host`, `port`, `username`, `password`. Where files land *within* a backend is the selecting feature's own setting, since two features sharing a bucket must not share a prefix: backups use `world.backup.path`, downloads use `downloads/`. A backend whose required settings are missing is not selected. BuildSystem logs exactly which key is absent and falls back to local storage, rather than accepting the choice and failing later at connection time. {% hint style="info" %} Before v4.0.0 these lived under `world.backup.storage.`. Existing configs are migrated automatically on first start: the credentials move to `storage`, `world.backup.storage.type` becomes `world.backup.storage`, and the path of whichever backend was in use becomes `world.backup.path`. {% endhint %} #### Credentials from environment variables Storage credentials can be supplied through environment variables instead of `config.yml`, keeping secrets out of a file that is easy to share or commit. When set, the environment variable **takes precedence** over the config value. | Variable | Replaces | | --------------------------- | ----------------------- | | `AWS_ACCESS_KEY_ID` | `storage.s3.access-key` | | `AWS_SECRET_ACCESS_KEY` | `storage.s3.secret-key` | | `BUILDSYSTEM_SFTP_PASSWORD` | `storage.sftp.password` | The remaining settings (`region`, `bucket`, `host`, `username`) are always read from `config.yml`. If a required one is missing, BuildSystem logs which key it was and falls back to local storage rather than starting with a backend that cannot work. On startup BuildSystem logs where backups are going, so you can confirm the intended backend actually loaded: ``` [BuildSystem] Storing backups on Amazon S3 in bucket 'buildsystem-backups' [BuildSystem] Storing backups locally in plugins/BuildSystem/backups (configured backend failed) ``` *** ### 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.