Moderation (Veritesauver)¶

Veritesauver is Verité's moderation component. It holds the in-house punishment system (bans, mutes, warnings, kicks, and IP punishments), the point-and-click punishment tree, the captcha verification gate, account intelligence (alt detection and IP and name history), GeoIP country lookup, server lockdown, inventory and ender chest spectating, and chat control (broadcast, clear, mute, and slowmode).

The whole component can be turned on or off independently of the rest of Verité.

moderation:
  enabled: true

While moderation is disabled, every staff moderation command is refused.

Where to find the commands and permissions

This page explains what each feature does. For the exact command syntax, see the Commands reference. For every permission node, see the Permissions reference. Developers integrating a custom chat system should read Custom Moderation Enforcement instead.

Punishments¶

Every ban, mute, warning, and kick is one record with the same shape: who was punished, who issued it, the reason, the start and end times, whether it was silent, and whether it is still active. Records are never edited in place. Lifting a punishment writes who removed it and why, and keeps the original as history, so a player's full moderation trail is always intact.

All punishments flow through a single engine, so a punishment issued by a command, by the punishment tree, or by an integration always behaves the same way: it is enforced, announced to the right staff, and recorded consistently.

Bans and mutes¶

A ban stops a player from joining. It is enforced at the login screen, so a banned player is turned away before they ever spawn.
A mute stops a player from talking in chat. A muted player who tries to speak sees a short reminder of how long their mute has left.
Both can be permanent or timed. Timed punishments expire on their own.
Issuing a new ban or mute over an existing one of the same type replaces it cleanly. The old record is kept as history, and exactly one active punishment remains.

IP punishments¶

An IP ban or IP mute covers the address rather than a single account, so it applies to every account connecting from that address. This catches a player who tries to evade an account punishment by logging in on an alternate account from the same connection.

Kicks¶

A kick disconnects an online player immediately. It leaves a record for history but does not stop the player from rejoining.

Lifting punishments¶

Staff lift a ban or mute with the unban and unmute commands. A moderator granted only the "own" form of the unban or unmute permission may lift only punishments they issued themselves, which lets senior staff delegate a limited pardon power.

Punishment messages¶

The text a punished player sees is authored in the config, so owners can rewrite every message. Templates support placeholders that are filled in for each specific punishment:

Placeholder	Filled with
`@duration`	The human-readable length (empty for a permanent punishment).
`@enforcer`	The staff member who issued the punishment.
`@target`	The punished player.
`@reason`	The reason, or "No reason provided." when none was given.
`@punishment`	The action in verb form.
`@total.warns`	The punished player's active warning count.

Use \n in a template for a line break.

moderation:
  punish.message.templates:
    ban.template.temporary: {You have been banned for @duration.\n@reason}
    ban.template.permanent: {You have been permanently banned.\n@reason}
    mute.template.temporary: {You have been muted by @enforcer for @duration.\n@reason}
    mute.notice: {You are muted. Time remaining: @remaining}

Per-rank limits and cooldowns¶

Staff are held to a per-rank ceiling on how long a temporary ban or mute they may issue, and a per-rank cooldown on how often they may punish. A staff member is never hard-stopped by asking for too long a duration: the request is simply clamped down to their rank's cap, so the punishment still lands, just shorter. Operators and holders of the admin permission are exempt from both the caps and the cooldown.

Technical detail

The rank tiers (durations and cooldown) are currently built in rather than read from config, and cooldown tracking resets when the server restarts.

Punishment tree¶

The punishment tree is a point-and-click menu that lets staff punish a player from an escalating list of offence categories without memorising commands or durations.

Running the punish command opens a page of online players, each shown as their own head. Clicking a player moves on to the offence categories. Supplying a player name up front skips the player page and goes straight to the categories.

The category page shows an icon for every offence type the staff member's rank is allowed to act on. Clicking a category opens a confirmation that shows the exact punishment the tree has chosen for that player and that offence. The chosen penalty climbs a ladder as the same player reoffends in the same category: a first spam might be a warning, and a later one a mute or a ban, so staff never have to remember the right length.

The confirmation offers three buttons:

Cancel (red) closes the menu.
Approve (green) applies the chosen punishment and advances the escalation ladder.
Manual (light blue) lets the staff member choose the punishment themselves. On new enough servers this is a native input form; on older servers it is a clickable chat prompt. A manual choice does not advance the ladder.

Escalation is counted per player, per category, and is remembered across restarts. A staff member can only act on the categories their rank is granted in the config, and the whole menu is unavailable while the tree is turned off.

Configuring the tree¶

Each category carries an ordered ladder of steps and a Minecraft item used as its GUI icon. A step is one punishment applied at a given offence count: warn, kick, mute, mute: 10m, ban, or ban: 14d. A step with no duration is permanent.

The permissions.luckperms block maps a rank to the categories that rank may act on. Inheritance follows the listed order from least to most privileged, so a higher rank inherits the categories of the ranks above it in the list.

moderation:
  tree:
    enabled: true
    permissions:
      luckperms:
        helper: {harassment, threats, spam, advertising}
        mod: {exploiting, discrimination, impersonation}
        admin: {hacking, fraud, evading.punishment}
    categories:
      spam: {warn, mute: 10m, mute: 1h, ban: 3d, ban, minecraft:cactus}
      harassment: {kick, ban: 14d, ban, minecraft:nether_star}
  use.fields: true

Set use.fields to true to present the manual override as a native Minecraft input form on Minecraft 1.21.7 and newer, or false to always use the clickable chat prompt.

Warnings¶

Staff issue warnings, revoke the most recent one, and inspect active warnings per player or server-wide. A warning is not enforced on its own: it is a strike that decays. A warning counts as active until it lapses, after which it no longer counts toward the active total.

moderation:
  expire.warns.after: 7d

Automatic threshold actions¶

When a player's active warning count reaches a set threshold, the server acts on its own so staff do not have to track strikes by hand. Out of the box, reaching three active warnings mutes the player for a day, and reaching five temporarily bans them for a day. Each threshold fires only at its exact count, so a single warning triggers at most one action. Staff set up to receive notifications see an announcement naming the player and the count they reached.

Technical detail

The thresholds and their actions are currently built in (three warnings for a one-day mute, five for a one-day tempban) rather than configurable.

Captcha gate¶

The captcha system forces a player to complete a verification challenge, either automatically when a strong signal of automated behaviour is present, or manually when staff issue one. A player exempt through the bypass permission is never challenged.

There are two variants:

Standard is the lighter check. The player is shown a chest menu and asked to click one named item out of a grid of decoys. Clicking the wrong item counts against them, and five wrong clicks fail. The menu reopens if closed, the player is held in place, and the attempt fails after 30 seconds. It does not blind or slow the player or take over their inventory.
Detailed is the stronger check. A random five-character code is drawn onto a map item that the player holds, and they must type the code back in chat. While it is active the player is pinned in place, blinded and slowed, and cannot move, drop items, or open their inventory, so the only possible action is typing the code. Typing exit gives up, three wrong attempts fail, and the attempt times out after 60 seconds. The player's real inventory and location are saved and restored when the challenge ends.

When a challenge concludes, the result (pass, fail, or timeout) is announced to staff holding the captcha notification permission. A player who fails or times out is kicked.

Staff can force a challenge on one player or on every eligible player at once with the captcha command, choosing the standard or detailed variant.

Account intelligence¶

Every login is recorded: the player's name, their connecting IP, their client brand, and their protocol version. This builds a durable identity trail that powers the lookup commands and the automatic staff alerts.

Behind a proxy

Verité resolves the player's true client IP in a proxy-aware way, trusting a TCPShield-style handshake first and never the proxy's own socket address. This is what keeps shared-IP detection and country lookups accurate on a proxied network.

Lookups¶

Staff have a set of read-only investigation commands:

History and staff history list the punishments a player has received or a staff member has issued.
Ban list and mute list page through the currently active punishments of each type.
Duplicate IP scan lists the accounts that share an IP with a given player and flags any that are currently banned or muted, surfacing likely alt accounts. The number of accounts shown is capped.
IP history, name history, and last UUID surface a player's stored identity trail.
Staff rollback lifts a staff member's recent active punishments in bulk, and prune history deletes a player's inactive records.
Seen reports when a player was last online.
Whois builds a full account dossier: identity, past names, client and version, referrer, country, playtime, and first and last seen. If the name has never touched this server, Verité resolves it through Mojang so staff can still look up a real account. The exact last IP is gated behind its own permission.

moderation:
  shared.ip.scan.limit: 20

Alt detection policy¶

By default an alt is only caught by an IP punishment. Turning on the alt-ban policy makes a ban automatically cover other accounts sharing the banned player's IP, even without an explicit IP ban.

moderation:
  auto.ban.alts: false

Shared connections

Do not enable the alt-ban policy on a server where multiple distinct players share an IP address (for example, players behind the same household or a shared network), because it can catch innocent accounts.

Automatic join alerts¶

Staff who hold the relevant notification permission are alerted automatically when a flagged player connects:

Banned join: a banned player, IP-banned player, or banned alt is turned away at the login screen. The alert names the player and how long the ban still has to run.
Duplicate IP join: a joining player shares an IP with other accounts. The alert lists the other accounts and marks any that are banned or muted.
Non-vanilla client join: a joining player is on a modified client such as Fabric or Forge. The alert names the player and their reported client brand. A vanilla client is silent.

GeoIP¶

Verité can attach a country to an IP address, used by whois and the geoip command. Give it a player name to use their most recent stored IP, or an IP address directly.

Country lookup uses a MaxMind GeoLite2-Country database. If no database is present, Verité says so plainly rather than reporting a wrong or unknown country. Private and loopback addresses can never be resolved regardless of the database.

Using an official database

To use an official MaxMind database, drop GeoLite2-Country.mmdb into the plugin data folder. Verité only downloads a substitute database when the file is absent, so an existing file is never overwritten.

Server lockdown¶

Lockdown seals the server during an emergency such as a raid or an exploit being abused, without banning any individual player. While lockdown is on, everyone trying to join is turned away at the login screen and shown the reason staff set. Trusted staff with the lockdown bypass permission can still get in to deal with the situation.

Lockdown is a temporary emergency posture, not a lasting setting: it lasts only until the server restarts, so a reboot always clears it and the server can never be accidentally left unjoinable after coming back up. Staff start and end it with the lockdown command and can give a custom reason players will see.

Inventory and ender chest spectating¶

Spectating is a staff tool for looking inside another player's belongings. Opening the inventory spectate command on a player shows everything they are carrying: hotbar and main storage, armour, off-hand, and even the crafting or work-station slots they currently have open. The ender spectate command does the same for their ender chest.

With edit permission, a spectator can move items in and out, and the change happens to the target straight away.
With only view permission, the window is read-only.
A spectator with the no-takeout permission can put items in but never take items out, which lets lower staff rearrange or deposit without being able to steal.

Spectating works on offline players too, by reading their saved data and writing any edits back when the window is closed. Some players can be marked as protected so they cannot be spied on unless the spectator is allowed to bypass that protection.

Every session is announced to the console: a line when a staff member opens a window, a list of exactly what changed if anything was added or removed, and a line when the window is closed. A spectator who only looks and changes nothing produces just the open and close lines.

Familiar names

The commands and permission nodes mirror the original InvSee++, so existing staff habits and permission grants keep working. See the Permissions reference for the spectating nodes.

invsee:
  enable-offline-player-support: true
  enable-unknown-player-support: true
  tabcomplete-offline-players: true

enable-offline-player-support allows viewing players who are not currently online.
enable-unknown-player-support allows viewing accounts that have never joined this server.
tabcomplete-offline-players includes offline names in tab completion.

Chat control¶

Verité provides the collective chat-moderation controls. Staff with the chat bypass permission are never affected by chat mute or slowmode.

Broadcast¶

Broadcast sends a staff announcement to the whole server. The message appears in everyone's chat, set apart with the server prefix and a blank line above and below so it stands out. Use it for reminders, event notices, or rule announcements.

Chat clear¶

Chat clear pushes the recent conversation up and out of view for every player, then announces who cleared it. It is useful for wiping spam or resetting an argument. It only clears what players currently see; it does not delete any saved logs.

Chat mute¶

Chat mute toggles a server-wide chat freeze. While it is on, ordinary players cannot send messages and are told the chat is muted if they try, which is useful for calming a heated moment or holding attention during an announcement. Running the command again unmutes the chat. Staff with the bypass permission can always talk.

Slowmode¶

Slowmode sets a minimum wait between chat messages. Give it a duration such as 10s, 5m, or 2h, and each player must wait that long between messages; if they try to talk too soon they are told how much time is left. Add a player name to apply a personal slowmode to just one person instead of everyone. Use off to clear it, either globally or for a named player. A personal slowmode takes priority over the server-wide one, and the maximum slowmode is 24 hours.

Muted command blacklist¶

A muted player is stopped from routing chat through commands such as /msg or /me. When a muted player runs a blacklisted command, it is cancelled and they are re-shown their mute reason. The blacklist is configurable.

moderation:
  muted.command.blacklist:
    - "me"
    - "say"
    - "msg"
    - "tell"
    - "r"

Proxy networks

If your server is hosted on a network with proxy injection, these commands may be handled by the proxy before Verité sees them, in which case a muted player could still use them. See Custom Moderation Enforcement for wiring a custom chat or proxy setup.

Exemptions and rank protection¶

Verité checks who may not be punished before applying any punishment.

Permission exemption: a target holding the exempt permission cannot be punished unless the issuer holds the exempt-bypass permission. The exemption can be scoped to a punishment type, so a player exempt from bans can still be muteable.
Rank protection: when enabled, an issuer cannot punish a target whose LuckPerms group weight is equal to or higher than their own, so staff cannot punish peers or superiors. An operator is always treated as the highest rank, so a non-operator can never punish an operator and an operator can always punish. Console is never blocked.

moderation:
  use.rank.weights: true
  exempt:
    use.group.weights: false
    permit.same.weight: true

Technical detail

Permission and rank checks apply only to online targets, because an offline player's live permissions cannot be read. LuckPerms is optional: when it is absent, the weight comparison passes through and never blocks staff.