> 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/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](/v4/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)* | 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. | | `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). | | `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 over HTTP. Off by default: enabling it opens a port that hands out world data. | Key | Default Value | Description | | -------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- | | `enabled` | `false` | Runs the download server. | | `port` | `8080` | Port the server listens on. | | `url` | `"http://localhost:8080"` | Base address players are linked to. Change it when the port is reached through a proxy or a domain. | | `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. | | `max-storage-mb` | `8192` | Budget shared by all live downloads. New exports are refused while it is full. | | `max-concurrent-downloads` | `3` | Transfers served at once. Further requests get `503` with `Retry-After`. | 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 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. #### Storage Types (`world.backup.storage`) * `storage.type`: Can be `local`, `s3`, or `sftp`. * **S3 configurations (`s3`)**: Includes `url`, `access-key`, `secret-key`, `region`, `bucket`, and `path`. 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 configurations (`sftp`)**: Includes `host`, `port`, `username`, `password`, and `path`. #### Credentials from environment variables Backup 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` | `world.backup.storage.s3.access-key` | | `AWS_SECRET_ACCESS_KEY` | `world.backup.storage.s3.secret-key` | | `BUILDSYSTEM_SFTP_PASSWORD` | `world.backup.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.