Reference

Configuration

config.yml section by section, the messages file and its languages, the menu files, and where the database is set.

Everything is generated in plugins/ExyliaProtections/ on first start, with comments. Edit the files there, never the copies in the jar, and restart the server to apply them: the plugin has no reload command.

The protections themselves are not in any file. They live in the database and are edited from the menus.

File	What it holds
`config.yml`	Every setting below.
`database.yml`	ExyliaLib's database connection.
`lang/<language>/messages.yml`	Every line the plugin sends.
`lang/<language>/menus/user/*.yml`	The players' screens.
`lang/<language>/menus/admin/*.yml`	The staff screens.

Coming from ExyliaSurvivalCore

When plugins/ExyliaSurvivalCore/ exists on the first start, its modules/protections/config.yml, each language's modules/protections/messages.yml and its database.yml are copied here wherever this plugin has no file of its own yet, so nothing has to be set up again. See Migration.

config.yml

Each feature has a section of its own, then come the starting roles and the tiers. The config-version key is the plugin's own; leave it alone. The file is at version 5, and older files are updated on start.

settings

settings:
  backend: INTERNAL
  worldguard-priority: 10
  default-limit: 3
  world-limits: {}
  min-distance: 8
  disabled-worlds:
  - world_the_end
  allowed-world-guard-regions: []
  move-price: 1000.0
  move-currency: ''
  home-warmup-seconds: 3
  deny-message-cooldown-millis: 1500

Key	Default	What it does
`backend`	`INTERNAL`	`INTERNAL`: the plugin enforces everything itself. `WORLDGUARD`: each protection is also a WorldGuard region with native flags. Change it with `/protections admin migrate`, not here. See Backends.
`worldguard-priority`	`10`	Priority of the WorldGuard regions the plugin creates.
`default-limit`	`3`	Protections a player may own without any `exyliaprotections.limit.<n>`.
`world-limits`	`{}`	Protections a player may own per world, as `world: number`. A world left out has no limit of its own.
`min-distance`	`8`	Blocks that must separate protections of different owners.
`disabled-worlds`	`[world_the_end]`	Worlds where land cannot be protected.
`allowed-world-guard-regions`	`[]`	WorldGuard regions a protection may overlap. Every other region blocks it.
`move-price`	`1000.0`	What moving a core costs.
`move-currency`	`''`	Its currency; blank is the default one.
`home-warmup-seconds`	`3`	Seconds standing still before teleporting home.
`deny-message-cooldown-millis`	`1500`	Milliseconds between two "this land is protected" messages to the same player.

The comment above default-limit still names exyliasurvivalcore.protections.limit.<n>; both prefixes are read. See Permissions.

submodules

Turns whole features off. A feature that is off hides its buttons, refuses its commands and stops acting.

Key	Default	Feature
`bans`	`true`	Owners ban players from their protections.
`lock`	`true`	Owners lock a protection to members. Locking turns `visitor-entry` off.
`enter-leave`	`true`	Titles and sounds walking in and out, and owners' greetings and farewells.
`logs`	`true`	Audit logs of blocks, containers and every change.
`raids`	`false`	Lives, core health, siege windows, offline shields. See Raids.
`upkeep`	`false`	Protections pay every period, and are abandoned and deleted when they stop.
`bank`	`false`	A shared bank per protection.
`market`	`false`	Selling protections and giving them away.
`subregions`	`false`	Plots inside protections with their own members and flags.
`rent`	`false`	Renting plots and protections to other players.
`upgrades`	`false`	Levels a protection is upgraded through.
`warps`	`false`	Protections published as public warps with visits and ratings.
`visualization`	`true`	Drawing borders, and markers on BlueMap and Dynmap.
`effects`	`false`	Perks for members inside their protection.
`environment`	`false`	A time of day and weather of its own inside a protection.
`merge`	`false`	Merging two protections that touch into one.

selection

selection:
  enabled: true
  tier: medium
  height: FULL
  price-per-block: 5.0
  currency: ''
  min-side: 9
  max-area: 10000
  full-height-tool: GOLDEN_HOE
  normal-height-tool: GOLDEN_AXE

Key	Default	What it does
`enabled`	`true`	Whether players may protect land by selecting two corners. Needs `exyliaprotections.select` too.
`tier`	`medium`	The tier a selected protection counts as, for its limit and starting flags.
`height`	`FULL`	`FULL`: the corners protect their whole column. `NORMAL`: only the blocks between both corners' heights.
`price-per-block`	`5.0`	Price per block of protected area.
`currency`	`''`	Its currency; blank is the default one.
`min-side`	`9`	The shortest side a selection may have.
`max-area`	`10000`	The largest area a selection may cover.
`full-height-tool`	`GOLDEN_HOE`	The selector for full-height selections and plots.
`normal-height-tool`	`GOLDEN_AXE`	The selector otherwise.

The selector is an item only the player's client sees, through PacketEvents, so it cannot be dropped, stored or sold. A tool name that is not an item falls back to the default. See Creating protections.

bans and enter-leave

bans:
  reason-max-length: 64
enter-leave:
  enter-sound: BLOCK_AMETHYST_BLOCK_CHIME|0.6|1.4
  leave-sound: ''
  message-max-length: 64
  cooldown-millis: 1500
  show-to-members: true

Key	Default	What it does
`bans.reason-max-length`	`64`	The longest reason a ban may carry.
`enter-leave.enter-sound`	`BLOCK_AMETHYST_BLOCK_CHIME\|0.6\|1.4`	Played walking in, as `NAME\|volume\|pitch`. Empty plays nothing.
`enter-leave.leave-sound`	`''`	Played walking out.
`enter-leave.message-max-length`	`64`	The longest greeting or farewell an owner may write.
`enter-leave.cooldown-millis`	`1500`	Milliseconds before crossing a border again shows anything, so walking along one stays quiet.
`enter-leave.show-to-members`	`true`	Whether members see the titles too, or only visitors.

The titles and action bars themselves are enter-leave in messages.yml.

logs

logs:
  retention-days: 14
  flush-seconds: 10
  skip-actions: []
  owner-blocks: false
  menu-rows: 500

Key	Default	What it does
`retention-days`	`14`	Days an entry is kept. `0` keeps them forever.
`flush-seconds`	`10`	Seconds between two writes of the entries waiting to be saved.
`skip-actions`	`[]`	Actions not logged; everything else is, including actions added later. Actions: `break`, `place`, `container`, `member`, `role`, `flag`, `ban`, `lock`, `core`, `settings`, `raid`, `bank`, `upkeep`, `market`, `subregion`, `rent`, `upgrade`, `warp`, `merge`.
`owner-blocks`	`false`	Whether the owner's own blocks and containers are logged too.
`menu-rows`	`500`	The most recent entries the logs menu reads.

raids

Only read while submodules.raids is on. See Raids for how they play.

raids:
  tier-lives:
    small: 3
    medium: 4
    large: 5
  default-lives: 3
  core-health: 150
  tool-damage:
    NETHERITE_PICKAXE: 4
    DIAMOND_PICKAXE: 3
    IRON_PICKAXE: 2
  default-damage: 1
  hit-cooldown-millis: 500
  core-heal-seconds: 30
  hit-sound: BLOCK_ANVIL_LAND|0.4|1.6
  lives-per-kill: 1
  kill-cooldown-minutes: 10
  allies-are-friends: true
  raidable-minutes: 30
  lives-after-raid: 1
  cooldown-minutes: 120
  raidable-permissions:
  - break
  - place
  - containers
  - doors
  - redstone
  - buckets
  explosions-while-raidable: false
  regen-minutes: 60
  restore-price: 5000.0
  restore-currency: ''
  allow-hidden-core: false
  siege-windows:
    enabled: false
    timezone: ''
    windows:
    - SATURDAY 18:00-22:00
    - SUNDAY 18:00-22:00
  offline-shield:
    enabled: true
    grace-minutes: 10
    clan-members-count: false

Key	Default	What it does
`tier-lives`	small 3, medium 4, large 5	Lives a protection of each tier has.
`default-lives`	`3`	Lives of a tier left out of `tier-lives`.
`core-health`	`150`	Health of the core per life.
`tool-damage`	three pickaxes	Damage one hit deals holding each item.
`default-damage`	`1`	Damage of anything else.
`hit-cooldown-millis`	`500`	Milliseconds a player waits between two hits on a core.
`core-heal-seconds`	`30`	Seconds without a hit before a damaged core heals to full.
`hit-sound`	`BLOCK_ANVIL_LAND\|0.4\|1.6`	Played on a hit.
`lives-per-kill`	`1`	Lives an enemy takes by killing a member inside. `0` turns it off.
`kill-cooldown-minutes`	`10`	Minutes before killing the same member there costs a life again.
`allies-are-friends`	`true`	Whether clan allies of the owner count as friends.
`raidable-minutes`	`30`	Minutes a protection stays raidable after losing its last life.
`lives-after-raid`	`1`	Lives it has once the raid ends.
`cooldown-minutes`	`120`	Minutes after a raid during which it cannot lose lives.
`raidable-permissions`	`break`, `place`, `containers`, `doors`, `redstone`, `buckets`	What enemies may do while it is raidable. Also what everybody may do in an abandoned protection.
`explosions-while-raidable`	`false`	Whether explosions break blocks in a raidable protection even with its `explosions` flag off.
`regen-minutes`	`60`	Minutes for one life to grow back. `0` turns it off.
`restore-price`	`5000.0`	What buying one life back from the menu costs. `0` turns it off.
`restore-currency`	`''`	Its currency; blank is the default one.
`allow-hidden-core`	`false`	Whether cores may be hidden while raids are on. A hidden core cannot be attacked.
`siege-windows.enabled`	`false`	Whether lives can only be lost inside the windows. Off: any time.
`siege-windows.timezone`	`''`	The time zone the windows are read in, like `Europe/Madrid`. Blank: the server's.
`siege-windows.windows`	Saturday and Sunday 18:00-22:00	`DAY HH:MM-HH:MM`, or `DAILY` for every day. A window ending before it starts runs past midnight.
`offline-shield.enabled`	`true`	Whether a protection cannot lose lives while every owner and member is offline.
`offline-shield.grace-minutes`	`10`	Minutes the shield waits after the last of them logs off on this server.
`offline-shield.clan-members-count`	`false`	Whether members of an added clan count as defenders too.

The hit action bar and the raidable boss bar are raids in messages.yml.

bank, upkeep and market

bank:
  currency: ''
  max-balance: 0.0
upkeep:
  period-hours: 24
  tier-costs:
    small: 15.0
    medium: 40.0
    large: 100.0
  default-cost: 15.0
  cost-per-block: 0.0
  charge-owner: true
  grace-periods: 3
  inactive-days: 30
  abandoned-days: 3
  warn-hours: 12
  check-minutes: 10
  announce: false
market:
  currency: ''
  tax-percent: 5.0
  max-price: 500000.0
  keep-members: false

Key	Default	What it does
`bank.currency`	`''`	The currency banks hold and upkeep is paid in. Blank: the default one.
`bank.max-balance`	`0.0`	The most one bank may hold. `0` for no limit.
`upkeep.period-hours`	`24`	Hours between two payments.
`upkeep.tier-costs`	small 15, medium 40, large 100	What one period costs per tier.
`upkeep.default-cost`	`15.0`	The cost of a tier left out.
`upkeep.cost-per-block`	`0.0`	Added to every period per block of protected area.
`upkeep.charge-owner`	`true`	Whether an owner online on the protection's server pays what its bank cannot.
`upkeep.grace-periods`	`3`	Unpaid periods that abandon a protection.
`upkeep.inactive-days`	`30`	Days without the owner or a member playing that abandon it. `0` turns it off.
`upkeep.abandoned-days`	`3`	Days an abandoned protection stays open to everyone before it is deleted.
`upkeep.warn-hours`	`12`	Hours before a payment the bank cannot cover when members are warned.
`upkeep.check-minutes`	`10`	Minutes between two checks of this server's protections.
`upkeep.announce`	`false`	Whether abandoning a protection is announced to everyone with raid announcements on.
`market.currency`	`''`	The currency protections are sold in.
`market.tax-percent`	`5.0`	Percent of the price taken as tax; the seller gets the rest.
`market.max-price`	`500000.0`	The highest price a protection may be listed for. `0` for no limit.
`market.keep-members`	`false`	Whether members, clans and overrides stay when a protection changes owner.

See Economy.

subregions, rent and upgrades

subregions:
  max-per-protection: 3
  min-side: 3
  full-height: true
rent:
  whole-protection: false
  currency: ''
  max-price: 50000.0
  min-period-minutes: 60
  max-periods: 4
  tenant-role: tenant
  tenant-permissions:
  - break
  - place
  - containers
  - doors
  - redstone
  - buckets
  - animals
  - ride
  - decorations
  - trade
  - leash
  pay-to-bank: true
  owner-can-evict: false
  relist: true
upgrades:
  pay-from-bank: false
  currency: ''
  base-max-members: 8
  base-max-subregions: 2
  tiers:
    small:
      levels:
        '1':
          cost: 3000.0
          radius-bonus: 5
          max-members: 12
          max-subregions: 3
          bonus-lives: 1
          permission: ''
        '2':
          cost: 6000.0
          radius-bonus: 10
          max-members: 16
          max-subregions: 4
          bonus-lives: 2
          permission: ''
    medium: ...
    large: ...

Key	Default	What it does
`subregions.max-per-protection`	`3`	Plots one protection may hold while upgrades are off. `0` for no limit.
`subregions.min-side`	`3`	The shortest side a plot may have.
`subregions.full-height`	`true`	Whether a plot spans the protection's whole height, or only the height selected.
`rent.whole-protection`	`false`	Whether whole protections may be rented, not only their plots.
`rent.currency`	`''`	The currency rent is paid in.
`rent.max-price`	`50000.0`	The highest rent per period. `0` for no limit.
`rent.min-period-minutes`	`60`	The shortest period an offer may have.
`rent.max-periods`	`4`	The most periods a tenant may pay for at once, renewals included.
`rent.tenant-role`	`tenant`	The role tenants hold. A protection without it gets it, with `tenant-permissions`.
`rent.tenant-permissions`	building and using	What that role starts with.
`rent.pay-to-bank`	`true`	Whether rent goes into the protection's bank when banks are on and the currency matches. Otherwise it goes to the owner.
`rent.owner-can-evict`	`false`	Whether a tenant can be evicted early; whoever evicts pays back the time left.
`rent.relist`	`true`	Whether a plot is offered again, on the same terms, when its rent ends.
`upgrades.pay-from-bank`	`false`	Whether the bank pays upgrades when banks are on and the currency matches. Otherwise the owner pays.
`upgrades.currency`	`''`	The currency upgrades cost.
`upgrades.base-max-members`	`8`	Members (players and clans) a protection holds before any upgrade. `0` for no limit.
`upgrades.base-max-subregions`	`2`	Plots it holds before any upgrade. `0` for no limit.
`upgrades.tiers.<tier>.levels.<n>`	two levels per tier	Each level from `1`: its `cost`, the `radius-bonus` and `bonus-lives` totals at that level, its `max-members` and `max-subregions` (`0` for no limit), and a `permission` needed to reach it (blank for none).

Shipped levels: small 3000 / 6000, medium 8000 / 16000, large 20000 / 40000, each adding 5 then 10 blocks of radius and 1 then 2 lives. See Land tools.

warps, visualization and effects

warps:
  name-max-length: 24
  description-max-length: 64
  hide-unavailable: true
  default-icon: LODESTONE
visualization:
  seconds: 10
  particle: END_ROD
  plot-particle: WAX_OFF
  show-on-create: true
  bluemap: true
  dynmap: true
  map-refresh-minutes: 5
  map-colors:
    normal: '#8a51c4'
    for-sale: '#8fffc1'
    for-rent: '#59a4ff'
    raidable: '#a33b53'
    abandoned: '#6c757d'
effects:
  tenants: false
  fall-protection-seconds: 5
  no-flight-during-siege: true
  potions:
    night-vision: NIGHT_VISION 0
    haste: HASTE 0
    speed: SPEED 0
    jump-boost: JUMP_BOOST 0
  tiers:
    small:
      levels:
        '0':
          perks:
          - night-vision
        '1':
          perks:
          - haste
          - no-hunger
        '2':
          perks:
          - speed
          - fly
    medium: ...
    large: ...

Key	Default	What it does
`warps.name-max-length`	`24`	The longest name a warp may have.
`warps.description-max-length`	`64`	The longest description.
`warps.hide-unavailable`	`true`	Whether warps a player cannot enter right now (locked, banned, raidable, abandoned) are hidden from them. Off: listed, and the visit is refused.
`warps.default-icon`	`LODESTONE`	The icon a new warp starts with.
`visualization.seconds`	`10`	Seconds a border stays drawn.
`visualization.particle`	`END_ROD`	The particle drawing a protection's border.
`visualization.plot-particle`	`WAX_OFF`	The particle drawing a plot's border.
`visualization.show-on-create`	`true`	Whether the border is drawn to whoever protects new land.
`visualization.bluemap`	`true`	Whether protections are drawn on BlueMap, when it is installed.
`visualization.dynmap`	`true`	The same for Dynmap.
`visualization.map-refresh-minutes`	`5`	Minutes between two redraws of every marker, which picks up sales, rents and raids.
`visualization.map-colors`	five states	Marker colours by state, in hex: web maps cannot read colour tokens. A state left out or mistyped uses `normal`.
`effects.tenants`	`false`	Whether tenants get the perks of what they rent, not only members.
`effects.fall-protection-seconds`	`5`	Seconds a player who stops flying takes no fall damage.
`effects.no-flight-during-siege`	`true`	Whether flight stops while a protection is under siege or raidable.
`effects.potions`	four potions	Potion perks: a key of your choice to `EFFECT amplifier`, the amplifier counting from 0.
`effects.tiers.<tier>.levels.<n>.perks`	per tier	The perks each level unlocks, from level `0`. A level has every perk of the levels below it. Perks: `fly`, `no-hunger`, `keep-inventory` and the keys of `potions`.

See Warps and Land tools.

import and cleanup

import:
  tier-map: {}
  default-tier: small
  owner-role: trusted
  member-role: member
  remove-source-regions: false
cleanup:
  default-days: 30
  skip-with-tenants: true
  skip-with-bank: false
  batch-size: 20

Key	Default	What it does
`import.tier-map`	`{}`	ProtectionStones block (its `ps-block-material`, like `EMERALD_ORE`) to the tier it becomes. A block left out becomes the tier placed with the same block, else `default-tier`.
`import.default-tier`	`small`	The tier for blocks nothing matches. Blank skips those regions.
`import.owner-role`	`trusted`	The role owners other than the first get.
`import.member-role`	`member`	The role members get.
`import.remove-source-regions`	`false`	Whether each imported region is removed from WorldGuard, so it stops enforcing its old owners and members. Run the import with `--dry-run` first.
`cleanup.default-days`	`30`	Days the cleanup button asks about first.
`cleanup.skip-with-tenants`	`true`	Whether protections with a tenant right now are kept.
`cleanup.skip-with-bank`	`false`	Whether protections whose bank holds money are kept. Off: the money is paid to the owner.
`cleanup.batch-size`	`20`	Protections removed per tick while a cleanup runs.

See Migration and Administration.

roles

The roles a new protection starts with. Each protection then keeps its own copy, edited from its menu; changing this section does not touch existing protections.

roles:
  member:
    permissions: [break, place, containers, doors, redstone, buckets, animals, ride, decorations, trade, leash, bank-deposit]
  trusted:
    permissions: [break, place, containers, doors, redstone, buckets, animals, ride, decorations, trade, leash, manage-members, set-home, bank-deposit]
  visitor:
    permissions: []

visitor is everybody who is not a member. Permissions: break, place, containers, doors, redstone, buckets, animals, ride, decorations, trade, leash, manage-members, manage-roles, edit-flags, rename, set-home, manage-core, manage-bans, toggle-lock, view-logs, bank-deposit, bank-withdraw, manage-subregions, manage-rent, manage-warp, edit-environment. An unknown key is skipped. See People and access.

tiers

The protection cores sold and given, keyed by tier id. Three ship: small (AMETHYST_BLOCK, radius 10, 2500), medium (PURPUR_BLOCK, radius 20, 10000) and large (CRYING_OBSIDIAN, radius 35, 40000).

tiers:
  small:
    material: AMETHYST_BLOCK
    name: '{primary}&lPROTECTION CORE &8[{info}SMALL&8]'
    lore: [...]
    radius: 10
    height: FULL
    y-radius: 10
    price: 2500.0
    currency: ''
    permission: ''
    limit: 0
    flags: [mob-spawning, crop-growth, leaf-decay, liquid-flow, visitor-entry]

Key	What it does
`material`	The core block.
`name`, `lore`	The core item's name and lore.
`radius`	Blocks protected around the core on each side.
`height`	`FULL` protects the whole column; `CUBOID` only `y-radius` blocks above and below the core.
`y-radius`	The height used by `CUBOID`.
`price`	Its price in the shop. `0` keeps it out of the shop.
`currency`	Its currency; blank is the default one.
`permission`	Needed to place it, buy it or receive one; blank for none.
`limit`	How many of this tier a player may own. `0` for no limit of its own.
`flags`	The flags that start on. Flags: `pvp`, `mob-spawning`, `explosions`, `fire-spread`, `liquid-flow`, `crop-growth`, `leaf-decay`, `visitor-entry`.

Tiers are also edited in game from the admin menu's tier editor, which writes this section along with the tier's lives and upkeep cost. See Administration.

messages.yml

lang/<language>/messages.yml holds every line the plugin sends. The language is the one set in ExyliaLib's config.yml: unlike most Exylia plugins, ExyliaProtections' config.yml has no language key of its own. es, pt and fr ship translated; English is written from the plugin's built-in defaults, and a line a translation leaves out arrives in English.

The top-level keys are chat lines, prompts and the words menus show, such as the raid and rent states. Then come the sections:

Section	What it holds
`utility`	Warps, borders, perks, time and weather, merging.
`utility.admin`	The admin menu, the tier editor, cleanup and the ProtectionStones import.
`utility.notices`	Refusals and confirmations, the `/protections help` lines, and `labels`: the names and descriptions of every role permission and flag, of log actions and of perks.
`raids`	The core-hit action bar and the raidable boss bar.
`enter-leave`	The titles and action bars of walking in and out. `%message%` is the owner's greeting or farewell, or the default one.
`visualization`	The marker label and layer name on BlueMap and Dynmap. Plain text: web maps read no colour tokens.
`general`	Lines shared by every part of the plugin.

Colours use palette tokens such as {primary}, {error} or {highlight}, so recolouring the server never means editing this file. %prefix% is replaced by the prefix value at the top. A line may open with an effect tag that never reaches the screen: [sound:NAME|volume|pitch] plays a sound to whoever receives it. The values each line may use are written in the comment above it.

general.reloaded is never sent: there is no reload command.

Menus

Folder	What it holds
`lang/<language>/menus/user/`	The players' screens: the hub, the list, the protection overview and its seven sections, members, roles, permissions, shop, bans, logs, market, plots, rent, warps, perks, merge. Yours to restyle; an update only adds files that are missing.
`lang/<language>/menus/admin/`	The staff screens: admin search, one protection, tiers, one tier, cleanup. Rewritten from the jar on every start; edits there are lost.

A menu file that does not parse is named in the console and left out, rather than opening empty. See Menus for every file and the actions their buttons run.

Database

database.yml is ExyliaLib's: H2 by default, or mysql, mariadb, postgresql and mongodb. See the library's database page for every key. Servers sharing one database share their protections.

The plugin's tables are protections, protections_accounts, protections_listings, protections_rent_offers, protections_logs, protections_seen, protections_warps, protections_warp_ratings, protections_warp_visits and protections_warp_totals, plus ExyliaLib's table of items waiting to be handed over.

Something missing on this page? Tell us on Discord