Config Reference
Every key in config.yml, and what it changes.
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)
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)
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)
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)
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)
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)
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)
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.
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.<visibility>.<amount> permission node of their own. A node always overrides these values, and buildsystem.admin ignores both. See World Creation Rules.
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.
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.<category>
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)
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)
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.
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 belocal,s3, orsftp.S3 configurations (
s3): Includesurl,access-key,secret-key,region,bucket, andpath. Leaveurlempty for Amazon S3 - it is only needed to point at an S3-compatible service such as MinIO, Backblaze B2 or Cloudflare R2.regionmust match the bucket's actual region.SFTP configurations (
sftp): Includeshost,port,username,password, andpath.
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.
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:
Folder Settings (folder)
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 bybuildsystem.setting.<option>. All options are allowed by default; deny specific nodes to restrict players.settings.restrict-template-access: Replaced by dynamic permission nodesbuildsystem.create.template.<name>andbuildsystem.create.generator.<name>.
Last updated