Wards

MachinaWards

Protect your builds with configurable land claim wards — no grief, no drama.

MachinaWards lets players place physical ward blocks to claim and protect an area. Members can be added by the owner, events are logged, and outsiders are stopped cold. Three tiers of wards scale from starter bases to high-value infrastructure.

---

How It Works

Craft a ward item and place it like any block. The block marks the center of your protected zone. Break it, or sneak+right-click it twice, to pick it back up — the ward item is returned to your inventory so you can relocate it any time.

Right-click the ward block to open the management menu.

---

Ward Tiers

All tiers, recipes, radii, prices, and member limits are fully configurable in config.yml. Server operators can add or rename tiers freely.

---

Protection

Inside a ward the following are blocked for non-members (all individually toggleable in config.yml):

The ward owner and all added members bypass all restrictions. Players with wards.admin bypass everything.

Wards cannot overlap — placement is blocked if the new ward's radius intersects an existing one, keeping protection zones unambiguous.

---

Trust Levels

When adding a member to a ward, they receive a trust level that controls what they can do inside:

Trust levels are assigned and changed per-member from the Manage Members screen in the ward GUI. Click a member's skull to open their trust sub-menu and select a level. The change takes effect immediately.

Trust level enforcement can be disabled server-wide in config.yml (trust_levels.enabled: false), which makes Visitors behave identically to Members.

---

Ward Menu

Right-clicking the ward block opens a management menu titled with the ward's name. A Nether Star header at the top shows the ward's tier, radius, member count, location, and ID. Every button describes what it does, shows its current state where it has one, and tells you what a click will do. The menu adapts based on who is clicking:

Owner / Admin view — full management access:

Member view — read-only access:

Chat prompts — Rename, Entry Message, and Add Member ask you to type in chat. Type cancel to back out; a prompt you ignore expires after 60 seconds. If what you typed is rejected, the prompt stays open so you can try again.

Ward names — Click Rename in the ward menu and type a name in chat, or run /ward rename <name> and right-click the ward block you own within 60 seconds. Use /ward rename cancel to abandon a pending selection. Names must have 1 to 32 visible characters, no spaces, and be unique across the server. & color codes and &#RRGGBB hex colors are kept for display; commands like /ward tp <name> match the name without its colors. Renaming keeps the ward's permanent ID.

---

Member Management

From the Members screen, each current member is shown as a player skull. Click Add Member and type a player name in chat to add someone (or use /ward addmember <player>). The ward's member limit is enforced at time of addition, and the button grays out when the ward is full. Players who are already members, and the ward owner, can't be added again.

Click a skull to open the Trust sub-menu. Each level lists what it can and cannot do, and the current one glows:

• Visitor — can interact but not build or break
• Member — full access (default)
• Remove Member — click it twice within the confirm window (pickup.confirm_ms, default 5 seconds). No shift-click needed, so it works for Bedrock players too

---

Super Ward — Ward Intelligence

Super wards include a Ward Intelligence menu with five independently toggleable tracking features:

Each feature has its own sub-menu where you can toggle it on/off (it glows while on), view recent logs (last 20 entries, shown in chat), or clear the log history. Clear Logs sits apart from View Logs and takes two clicks within the confirm window, so a stray click can't wipe your history. All data is persisted to the database and wiped automatically when the ward is destroyed.

---

Economy Shop

If Vault is installed with an economy provider (e.g. EssentialsX), players can purchase ward items directly using /ward shop. Each ward shows its price, member limit, and number of Ward Intelligence features, with a red line if you can't afford it. Each click buys one ward, and bought wards stack with crafted ones of the same tier. Prices are set per tier in config.yml. If a player's inventory is full, purchased items drop at their feet so they are never lost.

---

Commands

---

Permissions

---

Visual & Sound Effects

Particles

• Ambient — a subtle END_ROD effect floats above each ward block so you always know where your wards are (configurable type and interval)
• Placement burst — confirms a new ward was created
• Deletion burst — fires when a ward is broken or picked up
• Radius preview — purple particle square shows your claim boundary for 10 seconds via the Show Radius button

Sounds (all configurable in config.yml → sounds:, set to "" to disable individually)

---

Entry Warnings

When a non-member enters a ward they see an action bar notification showing the ward name and owner. The ward owner can set a fully custom entry message from the ward menu with & color codes and &#RRGGBB hex colors. Supported placeholders: %ward%, %owner%, %tier%, %radius%. The visitor warning can be toggled globally in config.yml.

---

Ward Compass

/ward compass sets your compass to point at your nearest ward in the current world. Specify an ID or name to target a specific ward. No special item required — any compass in your inventory works.

---

Ownership Transfer

/ward transfer <player> while standing in a ward offers ownership to another player. Use /ward transfer <id> <player> to offer from anywhere. The recipient must be online and accept within 60 seconds (configurable via transfer.request_timeout_seconds) using the clickable [ACCEPT] / [DECLINE] chat buttons — or /ward accept / /ward decline. The recipient's ward limit is checked before the transfer completes. Admins transfer instantly, including to offline players.

---

Nearby Wards

/ward nearby [radius] lists all wards within the given radius (default 100 blocks, max 500), sorted by distance. Shows each ward's name, tier, owner, and distance.

---

Anti-Abuse

• Ward items cannot be used as crafting ingredients
• Ward items cannot be inserted into beacon payment slots
• Wards cannot be placed overlapping an existing ward
• Picking up a ward block requires a second sneak+right-click confirmation within a configurable window (default 5 seconds) to prevent accidents
• Breaking the ward block directly also returns the ward item instead of dropping the raw material
• Removing a member or clearing Ward Intelligence logs takes two clicks within the same window
• Ward menus only respond to clicks on the menu's own slots; items in your own inventory can't be dragged into or bought through a menu
• MachinaWards recognizes its own menus directly rather than by title, so another plugin's menu with the same name is never affected

---

Database

MachinaWards stores all ward data in a database. Two backends are supported:

SQLite (default — no setup required)

database:
  type: sqlite

Data is stored in plugins/MachinaWards/MachinaWards.db.

MySQL / MariaDB

database:
  type: mysql
  mysql:
    host: localhost
    port: 3306
    database: machinawards
    username: root
    password: ""

The MySQL driver must be available on the classpath. Use /ward admin migrate mysql to copy existing SQLite data to MySQL before switching.

---

Configuration Reference

Everything is configurable in config.yml:

Color support: all text fields accept & color codes and &#RRGGBB hex colors.

---

Dependencies

• Paper / Purpur 1.21 through 26.x — one jar covers all versions (Java 21+ for 1.21.x servers, Java 25+ for 26.1+ servers)
• Plain Spigot is supported only by legacy v1.9.1 — v2.x uses the Adventure API bundled with Paper/Purpur
• Vault (optional) — required only for the economy shop
• MySQL/MariaDB (optional) — only if using the MySQL database backend