MuseumWorld

MuseumWorld by Tantrum90

MuseumWorld is a lightweight Paper plugin that turns selected worlds into read-only “museum / showcase” worlds.

Players can explore freely, while destructive actions, inventory modification, entity damage, and common interaction exploits are blocked.

It is designed for:

• lobby / spawn / hub worlds
• showcase maps
• museum builds
• read-only adventure areas
• worlds where visitors should explore, but not edit

    

---

Key Features

✅ Read-only worlds

You choose which worlds are protected through config.yml.

In protected worlds, MuseumWorld can block:

• block breaking
• block placing
• inventory modification
• entity damage
• armor stand manipulation
• item frame / painting interaction
• protected container modification
• hopper/item transfer involving protected inventories
• explosions damaging blocks
• item dropping
• item pickup
• bucket fill/empty actions
• flint and steel / fire charge use
• fire ignition
• TNT ignition
• bed use
• bone meal use
• Nether portal creation
• natural growth, spread and decay changes
• projectile use, with optional Elytra firework boost exception
• lead use
• name tag use
• vehicle placement and breaking
• hanging entity breaking/removal

---

✅ View-only containers

MuseumWorld allows players to open selected containers and look inside, while blocking item movement.

For example, players can open:

• chests
• barrels
• shulker boxes
• furnaces
• hoppers
• dispensers
• droppers
• brewing stands
• lecterns
• beacons

But they cannot:

• take items
• place items
• shift-click items
• drag items into the container
• move items using hopper transfers

---

✅ Strictly config-driven protection

MuseumWorld is designed to be predictable and controlled through config.yml.

Read-only blocks and read-only entities are protected only if they are explicitly listed in:

readonly-blocks:
readonly-entities:

There is no automatic read-only block/entity detection.

This means navigation blocks such as doors, trapdoors and fence gates are not blocked unless the server owner explicitly adds them to readonly-blocks.

For example, if players should be able to open doors in a museum world, simply do not add those doors to readonly-blocks.

If a specific door should be locked, add it manually:

readonly-blocks:
  - OAK_DOOR
  - IRON_DOOR

This keeps the plugin fully configurable and avoids unexpected protection behavior.

---

✅ Extended protection toggles

MuseumWorld includes additional protection options for common grief-prevention and museum-world use cases.

Example:

block-item-drop: true
block-item-pickup: true
block-bucket-use: true
block-fire-use: true
block-natural-growth: false
block-bone-meal-use: true
block-portal-creation: true
block-item-frame-rotation: true
block-armor-stand-manipulation: true
block-tnt-ignite: true
block-player-bed-use: true
block-hanging-break: true
block-vehicle-place-break: true
block-projectile-use: true
block-lead-use: true
block-name-tag-use: true

These options allow server owners to decide exactly how strict each protected world should be.

---

✅ Elytra support

Projectile blocking can be enabled while still allowing Elytra firework boosting.

block-projectile-use: true
allow-elytra-firework-boost: true

When enabled, players can still use firework rockets while gliding with Elytra.

This allows Elytra flight in protected worlds while still blocking other projectile-style interactions such as eggs, ender pearls, splash potions and similar actions.

---

✅ Config validation and safe cleanup

MuseumWorld can validate selected config lists on startup.

The validator checks:

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

If invalid Material or EntityType names are found, MuseumWorld can automatically remove them when enabled:

auto-clean-invalid-config-values: true

Before cleanup, the plugin can create a backup of config.yml.

Validation reports are saved under:

plugins/MuseumWorld/logs/

Config backups are saved under:

plugins/MuseumWorld/backups/

The validator does not modify:

locked-worlds
language

---

✅ Automatic config updates

MuseumWorld can automatically add missing config keys when a new plugin version introduces new options.

Existing values are preserved.

Protected config keys, such as:

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

are not overwritten during config updates.

MuseumWorld can also update missing list values when this option is enabled:

update-lists-on-next-reload: true

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

update-lists-on-next-reload: false

Before automatic config updates, the plugin can create a backup if enabled:

backup-config-before-auto-update: true

Backups are stored in:

plugins/MuseumWorld/backups/

---

✅ Template-based config rewrite

MuseumWorld rewrites config.yml using the bundled default configuration as a template.

This means automatic config updates preserve:

• official comments
• key order
• newly added explanations
• existing user-defined values
• custom list entries
• a clean and predictable config layout

The bundled default config.yml acts as the reference layout.

The active server config.yml keeps user values, while missing keys and comments are restored from the default template.