Configuration

General
Commands
Prefix System
Economy
Auction House
Ban System
Mute System
Kick System
Warn System
Team Claims
Container Protection (ChestLock)
Random Teleport (RTP)
Home System
Warp System
Scoreboard
TabList
Server List MOTD
Starter Kit
Join Message
Custom Kick Messages
Maintenance Mode
Client Detection
Auto-Updater
Modules
Data Storage
Migration

All settings are in plugins/MuteEssentials/config.yml. Changes can be applied live with /mues reload unless noted otherwise. New config keys from plugin updates are merged into your existing file automatically; your values are never overwritten.

General

General:
  Language: "auto"
  Prefix: "&c&lMuteEssentials &8>&r "
  DiscordURL: "https://discord.gg/yourserver"

Key	Description
`Language`	`"auto"` detects each player's Minecraft client language automatically. German clients see German, everything else sees English. Set to `"de"` or `"en"` to force one language for everyone.
`Prefix`	The prefix shown before all plugin messages in chat. Supports color codes with `&`.
`DiscordURL`	Your Discord invite link. Used in ban, kick and maintenance screens as `%DISCORD%`.

Commands

Every single command in MuteEssentials can be individually enabled or disabled. You can also define custom aliases.

Commands:
  heal:
    enabled: true
    aliases: []
  gamemode:
    enabled: true
    aliases: ["gm"]
  vanish:
    enabled: true
    aliases: ["v"]
  msg:
    enabled: true
    aliases: ["tell", "w"]

Key	Description
`enabled`	Set to `false` to completely disable a command. It will not be registered on the server, so it won't conflict with other plugins that use the same command name.
`aliases`	A list of alternative names for the command. For example, `aliases: ["gm"]` lets players type `/gm` instead of `/gamemode`.

Requires a server restart to take effect because commands are registered during plugin startup.

Prefix System

Controls how players appear in chat, tablist and above their head. All three use the same prefix, so the look is consistent everywhere.

PrefixSystem:
  Enabled: true
  ChatFormat: "%PREFIX%%PLAYER%%SUFFIX%&8: &f%MESSAGE%"
  Ranks:
    owner:
      permission: "muteessentials.rank.owner"
      prefix: "&c&lOWNER &8» &c"
      suffix: ""
      priority: 1000
    admin:
      permission: "muteessentials.rank.admin"
      prefix: "&6&lADMIN &8» &6"
      suffix: ""
      priority: 900
    default:
      permission: ""
      prefix: "&7&lPLAYER &8» &7"
      suffix: ""
      priority: 100

Default rank colors map 1:1 to Minecraft dye colors so they read well next to wool blocks. The admin GUI provides a 16-color picker (one wool block per dye color) for both creating and recoloring ranks at runtime.

Key	Description
`ChatFormat`	How chat messages are formatted. `%PREFIX%` is replaced with the rank prefix, `%PLAYER%` with the player name, `%SUFFIX%` with the suffix, and `%MESSAGE%` with the chat message.
`permission`	The permission node that determines which rank a player has. Players with multiple rank permissions get the one with the highest priority. OP players can be overridden with `/rank set`. Leave empty for the default rank.
`prefix`	Shown before the player name. The last color code in the prefix determines the player's name color.
`priority`	Higher priority ranks take precedence. If a player has both `admin` (900) and `vip` (500), they show as admin.

Economy

A built-in economy system. No Vault or external economy plugin needed.

Economy:
  StartBalance: 100.0
  Symbol: "$"

Key	Description
`StartBalance`	The amount of money new players start with. Set to `0` if you want players to earn everything.
`Symbol`	The currency symbol shown before amounts. Appears in `/money`, `/baltop`, scoreboard and PlaceholderAPI.

Auction House

Player-run marketplace. Items are stored in a SQLite database per module folder.

Auction:
  Enabled: true
  MinPrice: 1.0
  MaxPrice: 1000000.0
  MaxListingsPerPlayer: 5
  DurationHours: 48
  ListFee: 10.0

Key	Description
`MinPrice` / `MaxPrice`	Price bounds for listings. Prevents both joke pricing and economy exploits.
`MaxListingsPerPlayer`	How many active listings each player can have at once.
`DurationHours`	How long a listing stays live before it expires and moves to the seller's auction mailbox.
`ListFee`	Money deducted from the seller when creating a listing. Set to `0` to disable the fee entirely (no balance check, no deduction). Non-refundable otherwise.

Expired listings are returned to the seller via in-game mail (/ah mail). Buyers pay into the seller's balance automatically on purchase.

Admin tools: Any player with muteessentials.auction.admin can run /auction <player> to open a view of that player's active listings. Right-click a listing to remove it; the item is returned to the seller via auction mail. In the owner's own /ah my view, cancel is also right-click.

Ban System

BanSystem:
  Enabled: true
  Permission: "muteessentials.ban"
  Templates:
    1:
      reason: "Hacking/Cheating"
      duration: -1
      display: "&c[1] &eHacking/Cheating &7(Permanent)"

Key	Description
`Enabled`	Set to `false` to disable the entire ban system.
`Templates`	Predefined ban reasons with duration. Staff can ban by template ID instead of typing a reason. Duration is in seconds, `-1` means permanent. The `display` text is what staff sees in the GUI and template list.

Time unit: seconds. The kick screen text lives in messages-de.yml / messages-en.yml under BanSystem.KickMessage (same placeholders: %REASON%, %DURATION%, %BANNER%, %DISCORD%).

The admin GUI paginates templates (28 per page, prev/next arrows in the bottom row) and has a ✎ Custom... button that prompts in chat for reason | duration (e.g. Hacking | 7d, Trolling | permanent). Duration parser accepts 1d, 12h, 30m, 15s, combinations like 1d12h, plain seconds, and permanent/perm/-1. Add as many templates as you want - there is no upper limit.

Mute System

MuteSystem:
  Enabled: true
  Permission: "muteessentials.mute"
  Templates:
    1:
      reason: "Spam"
      duration: 3600
      display: "&c[1] &eSpam &7(1 hour)"

Same schema as the ban system. Time unit for mutes is seconds in the template; the plugin stores expiry in milliseconds internally.

/mute <player> <reason words> [seconds] accepts an optional numeric last argument as the duration in seconds, mirroring /customban. Templates and the GUI custom button (reason | duration) work the same way as bans.

Kick System

KickSystem:
  Permission: "muteessentials.kick"
  Templates:
    1:
      reason: "AFK"
      display: "&e[1] &6AFK"

Template-based, no duration. The GUI flow is the same as bans/mutes: paginated list, plus a ✎ Custom... button for free-form reasons (no duration prompt for kicks).

Warn System

WarnSystem:
  Enabled: true
  AutoBanThreshold: 3
  Templates:
    1:
      reason: "Spam"
      display: "&d[1] &fSpam"
    2:
      reason: "Beleidigung"
      display: "&d[2] &fBeleidigung"

Key	Description
`Enabled`	Master toggle for the warn system.
`AutoBanThreshold`	After this many warnings, the player is automatically banned. Set to a very high number to effectively disable auto-banning while still tracking warnings.
`Templates`	Predefined warn reasons. Each entry has a `reason` (used as the warning text) and a `display` (label in the GUI). Unlike bans/mutes there is no duration.

Team Claims

Teams can claim areas to protect them. Inspired by the Lands plugin.

ClanSystem:
  Enabled: true
  MaxNameLength: 4
  MinNameLength: 2
  ClanSuffix: " &8[%COLOR%%CLAN%&8]"
  MaxClaimWidth: 100
  MaxClaimDepth: 100
  MaxClaimHeight: 256
  MaxClaimVolume: 200000
  MaxClaims: 3
  ClaimCost:
    Enabled: true
    CostPerBlock: 0.1
    FreeBlocks: 0

Key	Description
`MaxNameLength` / `MinNameLength`	Team names must be between these lengths. Only A-Z and 0-9 are allowed.
`ClanSuffix`	Shown after the player name in the tablist. `%CLAN%` is the team name, `%COLOR%` is the color set with `/team color`.
`MaxClaimWidth` / `MaxClaimDepth`	Maximum size of a single claim in blocks on the X and Z axis.
`MaxClaimHeight`	Maximum vertical height of a claim. Set to `256` for full world height.
`MaxClaimVolume`	Total-volume cap. Acts as an additional hard limit.
`MaxClaims`	How many separate claims each team can have.
`ClaimCost.Enabled`	Set to `false` to make claims free.
`ClaimCost.CostPerBlock`	Money charged per block (ground area, X*Z).
`ClaimCost.FreeBlocks`	How many blocks are free before `CostPerBlock` kicks in. Set to `0` to charge from the first block.

Claims protect against: block breaking, block placing, interactions (doors, chests, buttons), liquid flow from outside, bucket usage, piston pushing and pulling from outside. Each claim has toggleable flags (PvP, mob spawning, explosions, fire spread, leaf decay, animal protection, ender pearls, pistons) in the team GUI.

Container Protection (ChestLock)

Automatic locks on every InventoryHolder block (chests, barrels, furnaces, hoppers, droppers, shulker boxes, brewing stands, and more). Ender chests and lecterns are intentionally excluded.

ChestLock:
  AutoLockOnPlace: true
  TeamMembersHaveAccess: true
  BlockHopperSteal: true
  ProtectFromExplosions: true
  ShowOwnerActionBar: true

Key	Description
`AutoLockOnPlace`	Locks every container to the player who placed it. Disable if you want fully manual locking via `/lock`.
`TeamMembersHaveAccess`	Members of the same clan can access each other's locked containers automatically. Leave `true` for social SMPs.
`BlockHopperSteal`	Foreign hoppers cannot pull items from locked containers. Hoppers owned by the same player or same team still work.
`ProtectFromExplosions`	Locked containers survive TNT and creeper explosions.
`ShowOwnerActionBar`	Players see a short "Container of X" in the action bar when they open a container they have access to.

Double chests are synchronized: a single lock, trust or break applies to both halves. Locks are stored in modules/ChestLock/chestlock.db.

Random Teleport (RTP)

RTP:
  Permission: "muteessentials.rtp"
  World: "world"
  MinRadius: 500
  MaxRadius: 5000
  CenterX: 0
  CenterZ: 0
  Cooldown: 60
  MaxTries: 20

Key	Description
`World`	Target world name. Leave blank to use the player's current world.
`MinRadius` / `MaxRadius`	Distance from `CenterX`/`CenterZ` that the teleport may land in. `MinRadius` prevents landing right next to spawn.
`CenterX` / `CenterZ`	Center of the teleport ring. Usually world spawn.
`Cooldown`	Seconds between `/rtp` calls. Bypassable with `muteessentials.rtp.ignoreCooldown`.
`MaxTries`	How many random candidate locations are tested before giving up and telling the player to try again.

Chunks are loaded asynchronously, so /rtp does not stall the main thread. Unsafe spots (lava, water, cacti, void drops, claimed land) are skipped automatically.

Home System

Home:
  Permission: "muteessentials.home"
  TeleportCountdown: 3
  TeleportCooldown: 3
  MaxHomes: 5

Key	Description
`TeleportCountdown`	Seconds the player must stand still before teleporting. Set to `0` for instant teleport.
`TeleportCooldown`	Seconds between teleports. Prevents spam.
`MaxHomes`	Maximum number of homes per player. Can be bypassed with `muteessentials.home.ignoreMaxHomes`.

Home names are case-insensitive and limited to a-z0-9_, up to 16 characters.

Warp System

Warp:
  Permission: "muteessentials.warp"
  SetPermission: "muteessentials.warp.set"
  TeleportCountdown: 3

Same countdown behavior as homes. Warp names follow the same naming rules.

Scoreboard

A sidebar scoreboard shown to all players. Updates every 2 seconds.

Scoreboard:
  Enabled: true
  Title: "&c&lMyServer"
  ServerName: "play.example.com"
  Lines:
    - "&8"
    - "&7\u2604 &f%DATE%"
    - "&8 "
    - "&f%PLAYER%:"
    - "&c\u2605 &7Rank: %RANK%"
    - "&a\u2714 &7Online: &a%ONLINE%"
    - "&e\u2666 &7Money: &e%BALANCE%"
    - "&c\u2601 &7Ping: &c%PING%&7ms"
    - "&8\u00a7r"
    - "&7\u27a1 &8%SERVER%"

Key	Description
`Enabled`	Set to `false` to disable the scoreboard entirely.
`Title`	The title shown at the top of the sidebar.
`ServerName`	Replaces `%SERVER%` in the lines. Typically your server domain.
`Lines`	Each line is one row on the scoreboard. You can add, remove or reorder them freely.

Available Placeholders

Placeholder	Value
`%PLAYER%`	Player name
`%RANK%`	Formatted rank prefix
`%ONLINE%`	Players online
`%MAXPLAYERS%`	Max player slots
`%PING%`	Ping in ms
`%BALANCE%`	Money balance with currency symbol
`%KILLS%`	PvP kills
`%DEATHS%`	Deaths
`%PLAYTIME%`	Total playtime
`%DATE%`	Current date (dd.MM.yyyy)
`%TIME%`	Current time (HH:mm)
`%TEAM%`	Team name or fallback
`%SERVER%`	Server name from config
`%X%` `%Y%` `%Z%`	Player coordinates
`%WORLD%`	World name

If PlaceholderAPI is installed, you can also use any external placeholder like %vault_eco_balance% directly in the scoreboard lines.

TabList

Custom header and footer in the player list (Tab key). Uses the same placeholders as the scoreboard.

TabList:
  Enabled: true
  Header:
    - ""
    - "&c&lMyServer"
    - "&8&m                              "
    - ""
  Footer:
    - ""
    - "&8&m                              "
    - "&7Online: &c%ONLINE%&8/&c%MAXPLAYERS% &8| &7Ping: &c%PING%ms"
    - "&8%SERVER%"
    - ""

Each entry in the list is one line. Empty strings ("") create blank lines for spacing.

Server List MOTD

Replaces the default server description shown in the Minecraft server list. This is what players see before they even join.

ServerListMOTD:
  Enabled: false
  Line1: "&c&l\u2726 &f&lMyServer &c&l\u2726"
  Line2: "&7Your server description here"

Set Enabled to true to activate. Supports two lines with color codes. The next time a client pings the server list, the new MOTD is shown; /mues reload applies it immediately to the running server.

Renamed in 1.0.10: the section was previously called ServerMOTD. The migrator copies your customisations to ServerListMOTD on first start and leaves the old keys in place. The runtime falls back to the legacy section if migration is skipped, so existing setups keep working without intervention.

Starter Kit

Items automatically given to players the first time they join the server.

StarterKit:
  Enabled: true
  Items:
    - material: WOODEN_SWORD
      amount: 1
      name: "&cStarter Sword"
    - material: WOODEN_PICKAXE
      amount: 1
    - material: BREAD
      amount: 16
    - material: LEATHER_HELMET
      amount: 1

Key	Description
`material`	The Minecraft material name. See the Material list.
`amount`	Stack size.
`name`	Optional custom display name with color codes. If not set, the default item name is used.

Join Message

A welcome message shown in chat when a player joins for the first time. Not shown on subsequent logins.

JoinMessage:
  Enabled: true
  Lines:
    - "&8&m                                        "
    - "&c&lWelcome to the server!"
    - "&8&m                                        "
    - ""
    - "&7Hello &c%PLAYER%&7!"
    - "&7Have fun playing."
    - ""
    - "&8&m                                        "

%PLAYER% is replaced with the player's name. Each entry is one line in chat.

Renamed in 1.0.10: previously MOTD. Migration is automatic and the legacy MOTD section is preserved as a fallback (see Migration).

Custom Kick Messages

By default, Minecraft shows generic English messages when a player gets disconnected for version mismatch, server full or connection throttling. This feature replaces them with your own styled and translated messages.

CustomKickMessages:
  Enabled: true

The actual message text can be customized in messages-de.yml / messages-en.yml under KickMessages.OutdatedClient, KickMessages.ServerFull, KickMessages.Whitelist and KickMessages.Throttled.

Requires ProtocolLib to be installed on the server. Version mismatch kicks happen at the network protocol level, before any Bukkit event fires. Without ProtocolLib, only server full and whitelist messages can be customized.

Maintenance Mode

Maintenance:
  Enabled: false
  KickMessage: |
    &c&lMAINTENANCE
    &7The server is currently under maintenance.
    &7Please try again later.
    &b%DISCORD%

When enabled, all players without the bypass permission are kicked and cannot rejoin. The kick message supports %DISCORD% to show your Discord link. Toggle with /maintenance on and /maintenance off.

Client Detection

Identifies the player's client (Lunar / Vanilla / Fabric / NeoForge / Forge / LabyMod / Badlion / Feather / Quilt) from the minecraft:brand channel and any registered plugin channels. Result is shown in /check and announced to staff.

ClientDetection:
  Enabled: true
  NotifyPermission: "muteessentials.clientdetection"
  HackDetection:
    Enabled: true
    Action: "kick"
    AlertPermission: "muteessentials.clientdetection.hack"
    KickMessage: "&cUnauthorized client detected."
    BrandPatterns: []
    ChannelPatterns: []
    BypassUuids: []
    BypassNames: []

Key	Description
`Enabled`	Master toggle for both detection and notifications. Off → no client detection at all.
`NotifyPermission`	Players with this permission get a chat alert when a player joins, showing the detected client.
`HackDetection.Enabled`	Toggle the hack-client check independently of detection.
`HackDetection.Action`	`kick` (default) drops the connection on match; `alert` only notifies staff.
`HackDetection.AlertPermission`	Permission needed to receive the in-game alert.
`HackDetection.KickMessage`	Shown in the disconnect screen when `Action` is `kick`.
`HackDetection.BrandPatterns`	Substring patterns matched (case-insensitive) against the player's reported brand. Empty list = built-in defaults.
`HackDetection.ChannelPatterns`	Substring patterns matched against any plugin channel the client registers. Empty list = built-in defaults.
`HackDetection.BypassUuids` / `BypassNames`	Static allow-list. Permission `muteessentials.bypass.clientdetection.hack` also bypasses.

Built-in default patterns include: wurst, meteor, liquidbounce, sigma, impact, aristois, future, vape, rusherhack, inertia, kami, wolfram, salhack, seedcracker, seedcrackerx, xray, and a number of others. Override the lists in config to extend or replace them.

Pure client-side mods that don't register a plugin channel and don't customise their minecraft:brand (e.g. an unmodified SeedcrackerX build) are not reliably detectable from the server side. For stricter enforcement use a Fabric mod-list whitelisting tool on top.

Auto-Updater

Update:
  Permission: "muteessentials.update"
  UpdateUrl: "https://repo.mutebefehl.de/update.json"
  CheckIntervalHours: 24

Key	Description
`UpdateUrl`	JSON descriptor with `version`, `downloadUrl` and optional `sha256`. Defaults to the official MuteEssentials release feed.
`CheckIntervalHours`	How often the plugin re-checks for a new version after startup. Set to `0` to disable the recurring check and only run the startup check.

On startup the plugin async-checks for updates. A recurring check runs every CheckIntervalHours on top. Players with muteessentials.update see a two-line notification on login when a newer version is available: the version number and how to install. /mues update re-triggers the check manually. /mues update download pulls the JAR, verifies SHA-256 and swaps the file in. A server restart is required to activate the new version.

Modules

Opt-in subsystems loaded by the module manager. Each module stores its own data in plugins/MuteEssentials/modules/<Name>/.

Modules:
  BlockLog:
    Enabled: true
  ChestLock:
    Enabled: true
  Auction:
    Enabled: true
  AntiVPN:
    Enabled: false
    ApiUrl: "https://netsight.mutebefehl.de/api/fraud-check"
    Token: ""
    RiskScoreThreshold: 50
    BlockProxy: true
    BlockHosting: false
    KickMessage: "&cVPN/Proxy detected. Connection refused."
    BypassUuids: []
    BypassNames: []
    CacheTtlMinutes: 60
    LogChecks: true

BlockLog

Logs block breaks, placements, interactions, bucket actions, fire spread, explosions and player deaths. Supports chunked rollback and restore with full block state (container inventories, sign text, orientation, beds, doors, crops). Natural block spread, form, fade and leaf decay are intentionally not logged. Data: modules/BlockLog/blocklog.db (SQLite).

BlockLog:
  LoggingActive: true
  NearDefaultRadius: 10
  NearMaxRadius: 100
  NearSinceMs: 604800000

Key	Description
`LoggingActive`	Runtime toggle for event logging. When `false`, `logAction()` short-circuits before writing. Also toggleable via AdminGUI > Settings.
`NearDefaultRadius` / `NearMaxRadius`	Radius for `/bl near` when called without argument and cap on user-supplied radius.
`NearSinceMs`	Time window for `/bl near` in milliseconds (default 7 days).

ChestLock

Automatic container locks with trust, team access, public mode and hopper protection. See Container Protection for tunables. Data: modules/ChestLock/chestlock.db (SQLite).

Auction

Player-run marketplace with listings, mailbox and GUI browser. See Auction House for tunables. Data: modules/Auction/auction.db (SQLite).

AntiVPN

Pre-login check that rejects players coming from known VPN, proxy or hosting IPs. Uses the /api/fraud-check endpoint of NetSight. Operators run their own NetSight instance and provision an X-MC-Token shared secret on the worker side; the same token goes into Modules.AntiVPN.Token.

Key	Description
`ApiUrl`	Endpoint that returns `{ riskScore, isProxy, isHosting }` JSON.
`Token`	Shared secret sent as `X-MC-Token` header. Empty token disables the module.
`RiskScoreThreshold`	Minimum score to reject. `0` rejects everything flagged at all, `100` only the most extreme.
`BlockProxy`	Reject connections where `isProxy` is true (independent of score).
`BlockHosting`	Reject connections where `isHosting` (datacenter/VPS) is true. Off by default - many legit players use hosting providers.
`KickMessage`	Shown in the disconnect screen on rejection.
`BypassUuids` / `BypassNames`	Allow-list. Permission-based bypass is not available at the pre-login phase because the `Player` object does not exist yet.
`CacheTtlMinutes`	How long fraud-check responses are cached per IP. Reduces API calls during reconnect bursts.
`LogChecks`	When `true`, every check is written to the server log with `score`, `proxy`, `hosting` and the resulting decision.

The module runs at AsyncPlayerPreLoginEvent, before the world is loaded, so a rejected player never enters the server. Local IPs (127.x, 10.x, 192.168.x, 172.16-31.x) are skipped automatically.

Migration

ConfigMigrator runs at plugin enable, before the merger. It moves your customisations from old key names to new ones without touching the original keys.

Legacy key	New key (since 1.0.10)
`ServerMOTD.*`	`ServerListMOTD.*`
`MOTD.*`	`JoinMessage.*`
`Modules.AntiHack.*`	`ClientDetection.HackDetection.*`

Behaviour:

If a legacy key is set and the new key is unset, the value is copied across.
Legacy keys are never deleted. Your customisations stay in the file as a record so you can compare old and new.
The runtime falls back to the legacy section at every check if the new section is missing, so existing setups keep working even when migration is skipped (e.g. read-only configs, custom mounts).

Migration messages are logged at startup, e.g. Migrated 5 legacy key(s) in config.yml (originals kept). Same logic applies to messages-en.yml and messages-de.yml.

Data Storage

All MuteEssentials data stays on your server under plugins/MuteEssentials/. Nothing is sent to remote servers, there is no telemetry.

File	Contains
`config.yml`	All settings described on this page.
`data.yml`	Homes, warps, spawn, economy balances, clans and claims, bans, mutes, warns, reports, stats, player-rank overrides.
`messages-de.yml` / `messages-en.yml`	All player-facing text. Customize to change wording.
`modules/BlockLog/blocklog.db`	Block-change history (SQLite).
`modules/ChestLock/chestlock.db`	Container locks and trust lists (SQLite).
`modules/Auction/auction.db`	Auction listings and mailbox (SQLite).

Backups

Everything is flat-file or SQLite. A standard filesystem backup of the plugins/MuteEssentials/ folder (while the server is stopped or via SQLite .backup) is sufficient. No external database is required.

Export

YAML files can be edited and copied as-is.
SQLite files can be dumped with sqlite3 blocklog.db .dump > export.sql for analysis or migration.
To move to a new server: copy the whole plugins/MuteEssentials/ directory over; no re-initialization needed.

Removal

Delete plugins/MuteEssentials/ to reset the plugin completely. Deleting only data.yml resets homes/economy/clans while keeping config and messages.

On this page