Skip to content

Configuration

Jump to bottom
Tantrum90 edited this page May 10, 2026 · 1 revision

Configuration

MuseumWorld is configured through:

plugins/MuseumWorld/config.yml

A reference copy of the default configuration is also created as:

plugins/MuseumWorld/config-reference.yml

The reference file is only for reading and comparison. MuseumWorld does not load settings from config-reference.yml.

This page explains every main configuration option and what it does.

Core settings

locked-worlds

locked-worlds:
  - Lobby
  - Museum

Description:
Defines which worlds are protected by MuseumWorld.

Explanation:
MuseumWorld only applies protection in worlds listed here. If a world is not listed, MuseumWorld will not block breaking, placing, inventory movement, entity interaction or any other protected action in that world.

You can manage this list manually or through commands:

/museum add <world>
/museum remove <world>
/museum lockcurrentworld
/museum unlockcurrentworld

Use the exact world name used by the server.

notify-player

notify-player: true

Description:
Controls whether players receive chat messages when an action is blocked.

Explanation:
If enabled, players will see a message when MuseumWorld blocks an action. If disabled, the action will still be blocked, but the player will not receive a chat notification.

This is useful if you want silent protection.

language

language: en

Description:
Selects which message file MuseumWorld should use.

Explanation:
Available language files:

messages_en.yml
messages_mk.yml

Supported values:

en
mk

Example:

language: mk

If the selected message file is missing, MuseumWorld falls back to English.

debug-mode

debug-mode: false

Description:
Controls whether MuseumWorld prints detailed protection decisions to the console.

Explanation:
When enabled, MuseumWorld logs why actions are allowed or denied.

Example debug output:

[MuseumWorld] [DEBUG] DENIED block-break | player=PlayerName | world=Lobby | locked=true | bypass=false | reason=locked world protection

Use this when testing or troubleshooting protection behavior.

startup-summary-enabled

startup-summary-enabled: false

Description:
Controls whether MuseumWorld prints a startup summary when the plugin loads.

Explanation:
If enabled, the plugin prints information such as version, config counts, enabled protection options and loaded settings.

This is useful during testing, but can be disabled on production servers to keep console output cleaner.

Message settings

messages.cooldown-ms

messages:
  cooldown-ms: 2500

Description:
Controls how often the same blocked-action message can be sent to the same player.

Explanation:
Some actions can trigger many events quickly, such as repeatedly clicking a protected block. The cooldown prevents chat spam.

The value is in milliseconds.

Examples:

cooldown-ms: 2500

means 2.5 seconds.

cooldown-ms: 0

disables message cooldown.

Entity damage settings

block-entity-damage

block-entity-damage: true

Description:
Enables damage protection for entity types listed under blocked-entity-types.

Explanation:
This does not mean “block all entity damage”. It means MuseumWorld will block damage only for entity types explicitly listed in:

blocked-entity-types:

This allows hostile mobs to remain damageable if they are not listed, while selected animals, villagers or decorative entities can be protected.

blocked-entity-types

blocked-entity-types:
  - COW
  - SHEEP
  - VILLAGER

Description:
Lists entity types that cannot be damaged when block-entity-damage is enabled.

Explanation:
Use this list to protect specific mobs or entities from being damaged in locked worlds.

Example use cases:

  • protect animals
  • protect villagers
  • protect golems
  • protect decorative mobs
  • protect passive or showcase entities

If an entity is not listed here, it can be damaged unless it is protected by another rule, such as readonly-entities.

Item protection settings

block-item-drop

block-item-drop: true

Description:
Blocks players from dropping items in locked worlds.

Explanation:
Prevents players from throwing items onto the ground. This keeps museum/showcase worlds clean and prevents item clutter.

block-item-pickup

block-item-pickup: true

Description:
Blocks players from picking up dropped items in locked worlds.

Explanation:
Prevents players from collecting items from the ground. This is useful when dropped items should not be collected or moved by visitors.

Bucket, fire and TNT settings

block-bucket-use

block-bucket-use: true

Description:
Blocks bucket fill and empty actions in locked worlds.

Explanation:
Prevents players from placing or collecting liquids and bucketed entities.

This helps prevent griefing with:

  • water buckets
  • lava buckets
  • powder snow buckets
  • fish buckets
  • axolotl buckets
  • tadpole buckets

block-fire-use

block-fire-use: true

Description:
Blocks fire-related item use and fire ignition in locked worlds.

Explanation:
Prevents actions such as using flint and steel or fire charges. It also blocks fire ignition events where applicable.

This helps protect builds from fire-related griefing and visual damage.

block-tnt-ignite

block-tnt-ignite: true

Description:
Blocks TNT ignition in locked worlds.

Explanation:
Prevents players from activating TNT. Even if explosions are also blocked, this avoids noise, knockback, entity damage and visual disruption.

World state settings

block-natural-growth

block-natural-growth: false

Description:
Blocks natural growth, spread, burn, fade and decay changes when enabled.

Explanation:
This can prevent natural world changes such as plants growing, leaves decaying, fire spreading or blocks changing naturally.

It is disabled by default because it can be aggressive. Enable it only if the protected world must remain completely static.

block-bone-meal-use

block-bone-meal-use: true

Description:
Blocks bone meal use in locked worlds.

Explanation:
Prevents players from growing plants, trees, flowers or other vegetation with bone meal.

This is useful for keeping decorative builds unchanged.

block-portal-creation

block-portal-creation: true

Description:
Blocks Nether portal creation in locked worlds.

Explanation:
Prevents players from creating portals that can visually change the world or create unwanted travel points.

block-player-bed-use

block-player-bed-use: true

Description:
Blocks bed use in locked worlds.

Explanation:
Prevents players from sleeping in protected worlds. This avoids time changes, bed interactions and unwanted spawn/interaction behavior.

Item frame, armor stand and hanging entity settings

block-item-frame-rotation

block-item-frame-rotation: true

Description:
Blocks item frame rotation and item frame item removal.

Explanation:
Prevents players from rotating displayed items or removing items from item frames.

This is important for museums and showcase areas where item frames are used as displays.

block-armor-stand-manipulation

block-armor-stand-manipulation: true

Description:
Blocks armor stand manipulation in locked worlds.

Explanation:
Prevents players from changing armor stand equipment or interacting with armor stands in ways that alter their display.

block-hanging-break

block-hanging-break: true

Description:
Blocks breaking/removing hanging entities.

Explanation:
Protects entities such as paintings, item frames and leash knots from being removed.

Vehicle settings

block-vehicle-place-break

block-vehicle-place-break: true

Description:
Blocks placing and breaking vehicles in locked worlds.

Explanation:
Prevents players from placing or breaking boats, rafts, minecarts and similar vehicle entities.

This is useful when vehicles are used as decoration or when you want to prevent visual clutter.

block-vehicle-enter

block-vehicle-enter: false

Description:
Controls whether players can enter vehicles in locked worlds.

Explanation:
If set to true, players cannot enter boats, rafts, minecarts or similar vehicles.

If set to false, players can enter vehicles, but vehicle breaking can still be blocked separately through:

block-vehicle-place-break: true

This separation allows boats or minecarts to be usable while still protected from being destroyed.

Projectile, Elytra, lead and name tag settings

block-projectile-use

block-projectile-use: true

Description:
Blocks projectile-style item use in locked worlds.

Explanation:
Can block actions involving projectiles such as eggs, ender pearls, splash potions, arrows and similar projectile behavior.

allow-elytra-firework-boost

allow-elytra-firework-boost: true

Description:
Allows firework rockets for Elytra boosting while projectile blocking is enabled.

Explanation:
If projectile blocking is enabled, this option allows players who are gliding with Elytra to still use firework rockets for boosting.

This lets you block general projectile use without breaking Elytra movement.

block-lead-use

block-lead-use: true

Description:
Blocks lead use in locked worlds.

Explanation:
Prevents players from attaching or removing leads from entities and fences.

block-name-tag-use

block-name-tag-use: true

Description:
Blocks name tag use in locked worlds.

Explanation:
Prevents players from renaming entities using name tags.

Read-only interaction settings

block-readonly-interactions

block-readonly-interactions: true

Description:
Enables read-only protection for blocks and entities listed in readonly-blocks and readonly-entities.

Explanation:
If disabled, MuseumWorld will not block interactions with configured read-only blocks/entities.

Most servers should keep this enabled.

readonly-blocks

readonly-blocks:
  - CHEST
  - BARREL
  - LECTERN

Description:
Lists blocks that should be protected from right-click/use/state-changing interactions.

Explanation:
This list is not for basic block breaking. Block breaking is already blocked globally in locked worlds.

Use this list for blocks that players can interact with, modify, open, toggle or change.

Examples:

  • chests
  • barrels
  • hoppers
  • furnaces
  • lecterns
  • bells
  • composters
  • candles
  • cauldrons
  • potted plants
  • redstone-related interactive blocks
  • workstations

Doors, trapdoors and fence gates are not enabled by default because they are often used for navigation. Add them manually only if you want to lock them.

readonly-entities

readonly-entities:
  - ITEM_FRAME
  - ARMOR_STAND
  - TEXT_DISPLAY

Description:
Lists entities that should be protected from interaction and damage/removal.

Explanation:
Use this list for entities that are part of the museum/showcase display.

Examples:

  • item frames
  • glow item frames
  • armor stands
  • display entities
  • interaction entities
  • paintings
  • leash knots
  • decorative vehicles

Entities listed here are protected as museum objects.

View-only container settings

view-only-containers

view-only-containers:
  - CHEST
  - BARREL
  - SHULKER_BOX

Description:
Lists containers that players can open and view, but cannot modify.

Explanation:
Players can look inside these containers, but cannot:

  • take items
  • place items
  • shift-click items
  • drag items
  • hotbar swap items
  • move items using hoppers

If a block is in readonly-blocks but not in view-only-containers, right-click interaction with that block is fully blocked instead of view-only.

Config update settings

protected-config-keys

protected-config-keys:
  - locked-worlds
  - language

Description:
Lists config keys that should not be overwritten during automatic config updates.

Explanation:
This protects important server-specific values such as protected worlds and language selection.

Normally, keep:

locked-worlds
language

in this list.

create-config-reference

create-config-reference: true

Description:
Controls whether MuseumWorld creates or updates config-reference.yml.

Explanation:
The reference file contains the default commented configuration. It is useful for comparison and documentation.

MuseumWorld does not load settings from config-reference.yml.

max-config-backups

max-config-backups: 5

Description:
Controls how many automatic config backups are kept.

Explanation:
When automatic config updates or cleanup happen, backups are stored under:

plugins/MuseumWorld/backups/

If the number of backups exceeds this limit, older backups are removed.

Set to 0 or a negative number to disable automatic cleanup of old backups.

backup-config-before-auto-update

backup-config-before-auto-update: true

Description:
Controls whether MuseumWorld creates a backup before automatic config updates.

Explanation:
Recommended to keep enabled. This allows you to restore your previous config if something goes wrong.

update-lists-on-next-reload

update-lists-on-next-reload: false

Description:
If enabled, MuseumWorld adds missing default values to existing config lists during the next reload/startup.

Explanation:
Existing values are preserved. Nothing is removed.

After the update is completed, this option automatically returns to:

update-lists-on-next-reload: false

Protected lists such as locked-worlds are not auto-updated.

auto-clean-invalid-config-values

auto-clean-invalid-config-values: true

Description:
Controls whether invalid Material or EntityType names are removed from selected config lists.

Explanation:
MuseumWorld validates:

readonly-blocks
view-only-containers
readonly-entities
blocked-entity-types

If invalid values are found and this option is enabled, they are removed after a backup/report is created.

This is useful when config contains entries not supported by the current Paper version.

Update checker settings

update-checker-enabled

update-checker-enabled: true

Description:
Controls whether MuseumWorld checks GitHub Releases for newer stable versions.

Explanation:
The update checker only notifies. It does not download, install or modify plugin files.

notify-admins-about-updates

notify-admins-about-updates: true

Description:
Controls whether admins are notified when a newer version is available.

Explanation:
If a new stable release is detected, admins can be notified when they join the server.

bStats

MuseumWorld uses bStats for anonymous usage statistics.

There is no plugin-specific bStats toggle in config.yml.

Server owners can disable bStats globally through:

plugins/bStats/config.yml

bStats does not collect private player data, chat, world names or config values.

Config version

config-version

config-version: 7

Description:
Internal config version marker.

Explanation:
MuseumWorld keeps this key at the bottom of config.yml.

It is used internally for config update handling. Server owners normally do not need to edit it manually.

Clone this wiki locally