Protections

The protections module lets players protect land. A protection is a box of blocks with an owner, members, roles and flags, made by placing a core block or by selecting two corners. The module enforces it itself, whichever backend is chosen.

Every protection on the network is one database row, and every server keeps all of them in memory. A player's list and their limits count every server; only the server a protection belongs to enforces it, draws it and mirrors it to WorldGuard. A change made on one server is announced and re-read by the others.

Raids, lives and siege windows are on Protection raids. Banks, upkeep, the market, rent and level upgrades are on Protection economy. The admin menu, the tier editor, the ProtectionStones import and the inactive cleanup are on Administering protections.

Settings live in modules/protections/config.yml, messages in the protections section of messages.yml, and the screens in modules/protections/menus/.

Features

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

Tiers and the core

A tier is a kind of core: its block, its item, the land it protects and the flags a new protection starts with. tiers in the config holds them, keyed by tier id. Three ship:

The area is the radius on every side of the core, so a side is radius × 2 + 1 blocks.

The shipped tiers start with mob-spawning, crop-growth, leaf-decay, liquid-flow and visitor-entry on, and pvp, explosions and fire-spread off.

Cores come from the protection shop button of /protections, which lists every tier with a price above 0, or from /protections admin give. Tiers can be edited in game from the tier editor.

Placing a core

Placing a core item protects the land around it. The placement is refused, and the block stays in the hand, when any of these fails:

1. The tier's permission, if it has one.
2. The world is not in settings.disabled-worlds — world_the_end by default.
3. The player owns fewer protections than their limit. The limit is the highest exyliasurvivalcore.protections.limit.<n> they hold, or settings.default-limit (3) without one. It counts every server.
4. The player owns fewer of this tier than the tier's limit.
5. The player owns fewer protections in this world, on this server, than settings.world-limits sets for it. A world left out has no limit of its own.
6. The land overlaps no other protection, whoever owns it.
7. The land is at least settings.min-distance (8) blocks, horizontally, from any protection of another owner. A player's own protections may touch.
8. With WorldGuard enabled, the land overlaps no WorldGuard region other than this module's own, the global region, and the ones listed in settings.allowed-world-guard-regions. This is checked in both backends.

Placing a core is also placing a block, so it cannot be done inside somebody else's protection without place there. The protection's home starts where the player stands, and its name is %player%'s land #%number% until renamed.

Protecting by selection

With selection.enabled and the node exyliasurvivalcore.protections.select, the select land button of /protections hands the player a selector. They mark two corners, confirm with shift + left-click, and are asked to pay.

A 20x20 selection costs 2000. With a FULL tier the whole column is protected; with a CUBOID tier only the heights selected. The same placement checks apply, and are asked again after the player confirms. A selected protection has no core block: it cannot be picked up or hidden, only moved or deleted.

Picking up, hiding, moving, deleting

Picking up. The owner breaking their own core is asked to confirm, and gets an item back that rebuilds the same protection wherever it is placed: its name, roles, members, clans, flags, bans, plots, level, perks and the exact box it covered. What the bank held is paid to the owner, a public warp is taken down, and a sale ends. Anybody else breaking a core is refused — or, with raids on and the player an enemy, hits it.

Hiding removes the core block and keeps the land protected. It needs manage-core, standing on the protection's server and world. While raids are on, a core can only be hidden with raids.allow-hidden-core.

Moving puts the core on top of the block the player looks at, within five blocks, in the same world, and the whole protection moves with it, same shape and size. It needs manage-core, passes every placement check except the limits, costs settings.move-price (1000) in settings.move-currency, and moves the home to where the player stands.

Deleting, from the manage screen, is the owner's alone. The core block is removed and the bank paid to the owner.

A protection under attack, raidable, abandoned or with tenants cannot be picked up, moved or deleted by its owner.

Backends

settings.backend picks how protections reach other plugins.

Change it with /protections admin migrate <INTERNAL|WORLDGUARD>, which writes the key and moves every region over: WORLDGUARD creates the regions, INTERNAL removes every region this module made from every loaded world. A reload applies the key as the file holds it. Asking for WORLDGUARD on a server without WorldGuard runs INTERNAL and logs a warning; the details are on Administering protections.

What a mirrored region holds:

With plots on, each plot is a child region <region>_<plot>, one priority above, with its own members and flags.

Roles and member permissions

A protection has roles, each a set of permissions. A player's rights resolve in this order:

1. The owner may do everything.
2. An override set for that player alone, allow or deny, wins.
3. Otherwise the player's own role.
4. Otherwise the role given to their clan.
5. Anybody left is a visitor, and has what the visitor role grants — nothing by default.

New protections start with three roles:

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: []

Hostile mobs are never protected. The role screens only offer permissions whose feature is on.

Members. The members screen adds a player who has played on the network, or a clan by its tag when a clan plugin is present, and asks which role they get. Role names use up to 16 of a-z, 0-9, - and _, and cannot be owner. The visitor role cannot be renamed or deleted. Deleting a role removes everybody who held it, in the protection and in its plots.

Some things no role grants. Nobody but the owner edits the role they hold themselves, or their own overrides. Opening the manage screen and teleporting home need membership; deleting, picking up the core, selling, giving away, upgrading, merging and turning perks on are the owner's alone.

Flags

A flag is the land's own switch. It applies to everybody inside, members or not.

Two rules hold whatever the flags say: liquids never flow into a protection from outside it, and pistons never move a block into, out of or across a protection other than their own. A player lighting a fire needs place.

settings.deny-message-cooldown-millis (1500) is how long a player waits between two "this land is protected" messages.

Bans

With submodules.bans, manage-bans bans a player from the protection: they are pushed out and cannot walk or teleport in — ender pearls, chorus fruit, commands, plugins and spectating are all stopped. Logging in or respawning inside pushes them just past the nearest border.

/protections ban <player> [duration] [reason] or the bans screen. The duration is 30m, 2h, 7d or permanent (also perm, forever); nothing at all is permanent. A reason needs a duration before it. bans.reason-max-length is 64, and a reason is stored as plain text. The owner, members, tenants, and online players with the admin or bypass node cannot be banned.

A ban applies even while the protection is open to visitors. A raid running, or an abandonment, opens the land to everybody whatever its bans or lock say.

Lock

With submodules.lock, toggle-lock locks a protection so only the owner, members and plot members may enter. Locking is turning visitor-entry off; /protections lock toggles it.

Enter and leave messages

With submodules.enter-leave, walking into a protection shows a title and walking out an action bar. rename lets a member write the protection's own greeting and farewell, up to enter-leave.message-max-length (64) characters of plain text; clearing them brings back the defaults.

Placeholders: %name%, %owner% and %message%, which is the owner's greeting or farewell, or protections.enter-default / protections.leave-default from messages.yml ("Owned by %owner%", "« You left %name%"). Stepping straight from one protection into another only greets. Stepping into a plot shows the plot's name in the action bar. Players can mute all of it with the protection-messages switch of player settings.

Audit logs

With submodules.logs, every protection keeps a history. view-logs opens it from the manage screen or /protections logs, filtered by action and by player.

Logged actions: break, place, container, member, role, flag, ban, lock, core, settings, raid, bank, upkeep, market, subregion, rent, upgrade, warp, merge. Blocks broken and placed and containers opened (chests, barrels, shulkers, furnaces, blast furnaces, smokers, hoppers, dispensers, droppers, brewing stands) are only what actually happened; everything else is a change made through a screen or a command. Each entry keeps who, what, where, which server and when.

Plots

With submodules.subregions, manage-subregions splits a protection into plots: boxes inside it with members, overrides and flags of their own. /protections subregion create or the plots screen hands out a selector, standing on the protection's server and world, then asks the plot's name — up to 16 of a-z, 0-9, - and _.

A plot must lie fully inside the protection and overlap no other plot.

• Plot members hold one of the protection's roles inside that plot only, with overrides of their own there. A plot member may walk into a locked protection.
• Plot flags follow the protection, or are set on or off for the plot. visitor-entry is the protection's alone.
• A private plot lets only its members, and those with manage-subregions, act inside it. A shared plot lets everybody else fall back to their rights in the protection.

Plots are kept as offsets from the core, so they move and travel with it. A rented plot cannot be deleted. /protections subregion info describes the plot a player stands in, and /protections subregion delete <name> removes one.

Member perks

With submodules.effects, members standing in their protection get perks: fly, no-hunger, keep-inventory, and the potion effects of effects.potions. A tier unlocks perks level by level, each level keeping every perk of the ones below; the owner turns on the unlocked ones from the perks & atmosphere screen.

effects:
  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:
      levels:
        '0': { perks: [night-vision, haste] }
        '1': { perks: [no-hunger, speed] }
        '2': { perks: [fly, keep-inventory] }
    large:
      levels:
        '0': { perks: [night-vision, haste, no-hunger] }
        '1': { perks: [speed, fly] }
        '2': { perks: [keep-inventory, jump-boost] }

A potion is EFFECT amplifier, the amplifier counting from 0. Levels come from upgrades; a protection never upgraded is level 0.

Who gets them: the owner, members and clan members — not while the protection is raidable or abandoned. Perks are worked out again when a player changes protection and every five seconds. Flight is only given to a player who could not already fly, and only that flight is taken back. keep-inventory keeps the inventory and the experience of a member dying in the protection that gave it.

Time and weather

With submodules.environment, edit-environment sets what everybody standing inside sees — members or not. Each click moves to the next value.

The time is fixed while they stay; walking out gives them the world's back.

Public warps

With submodules.warps, manage-warp publishes a protection as a warp anybody may visit and rate. It needs a home, and lands there; land here moves it to where the player stands inside. The warp has a name, an icon and a description, stored as plain text.

/protections warps lists them, sorted by visits, rating or newest. /protections warp <name> goes to one; when names clash, the most visited wins. Visiting uses the home warmup.

A visit counts once per player per day, whichever server they arrive from; members' visits do not count. Ratings are one to five stars, one per player, rated again to change; nobody rates their own warp. Unpublishing a warp, or deleting its protection, deletes its visits and ratings.

Borders and web maps

With submodules.visualization, members see a protection's border with the show border button or /protections show: particles along its edges and its plots', in a band around the player's eyes.

On the web maps every protection is a box in a marker set called Protections, redrawn whenever it changes and all of them every few minutes, which picks up sales, rents and raids. Each server draws its own protections. The colour is the most urgent state:

Merging

With submodules.merge, the owner joins two of their protections that touch into one, from the merge button or /protections merge, standing in the one that stays. The screen lists the owner's protections on this server that touch it.

The box holding both becomes the land. The merge is refused when that box would reach any other protection, come closer than settings.min-distance to another owner's, or overlap a foreign WorldGuard region, and while either protection is for sale, for rent, under attack, raidable, abandoned or rented.

What the merged protection keeps:

• Its own name, home, core, tier, flags, greeting, farewell, perks, time, weather and rents.
• The roles, members, clans, overrides and bans of both; where both say something about the same key, the one kept wins.
• Every plot of both; a plot whose name is taken gets -2, -3… added.
• The higher level of the two, and the raid state of whichever has fewer lives left.
• The other one's bank, moved over before the land is joined.

The other protection's core is removed and not given back, and its warp is taken down.

Screens

/protections opens the list of every protection the player owns or belongs to, on any server, with buttons for selecting land, the protection shop, the market, rent and warps. A protection opens its manage screen, where each button appears only while its feature is on: teleport home, set home, rename, logs, members, roles, flags, greeting & farewell, lock, bans, lives, hide core, move, delete, bank, upkeep, sell or give away, plots, upgrade, rent out, show border, public warp, perks & atmosphere, and merge.

Every click is checked again against the protection as it is when the click arrives.

Commands

Every command below needs exyliasurvivalcore.protections. /ps and /claims are aliases. Commands that act on "the protection here" use the one the player stands in.

The bank, upkeep, market, sell, transfer, rent and upgrade commands are on Protection economy; the admin commands on Administering protections.

Placeholders

The lives, raid, bank, upkeep, sale, level and rent placeholders are on the raids and economy pages. All of them are on Placeholders.

Settings

The keys of settings not already covered above: