AnziUtils Documentation

Getting Started

AnziUtils runs on a single server out of the box and scales up to a full BungeeCord/Velocity network once you add MySQL and Redis.

Requirements

• Java 21 or higher
• Paper (or a Paper fork) running Minecraft 1.21+ — the plugin targets api-version: '1.21'
• A valid AnziUtils license key (issued in the Discord — see /claim)
• Outbound internet access for GeoIP, VPN lookups, and license verification

Optional Integrations (softdepend)

Everything else is bundled. MySQL and Redis are optional external services used only for network setups.

Installation & License

Step 1: Download

Download the latest AnziUtils JAR file from the BuiltByBit release page.

Step 2: Install

1. Stop your Minecraft server
2. Navigate to your server's plugins/ directory
3. Place the AnziUtils JAR file in this directory
4. Start your server once to generate the configuration files

Step 3: AnziLock License Setup

AnziUtils is protected by AnziLock, a signed license client that verifies your key against license.ajdnikov-dev.com on startup and then keeps a low-frequency heartbeat running in the background. Insert the key you received via Discord (see the /claim command in the Discord server) into plugins/AnziUtils/config.yml:

license:
  key: "YOUR_LICENSE_KEY_HERE"

AnziLock caches the last signed verification, so a brief outage of the license server will not take your server down — the plugin keeps running on the cached result for the duration of the offline grace period. If the key is missing or invalid, the plugin applies the configured failure action and logs the reason to the console.

Step 4: Configuration

Edit the generated files in plugins/AnziUtils/:

• config.yml — every module, database, Redis, and staff setting
• messages.yml — every player-facing message
• discord.yml — the webhook URL and per-event notification toggles
• rules.yml — the contents of the automatic rule book

Apply changes without a restart using /anziutilsreload or /anziutils reload.

Database

AnziUtils stores IP history, geolocation results, alt links, staff profiles, and staff sessions in a database. Two backends are supported.

SQLite (default)

Zero setup. Keep database.type: sqlite for a single standalone server.

MySQL (networks)

On a BungeeCord/Velocity network, point every backend server at one shared MySQL database so IP history, alt limits, and staff profiles are tracked network-wide.

database:
  type: mysql
  mysql:
    host: mysql.example.com
    port: 3306
    database: anziutils
    username: anziutils
    password: "CHANGE_THIS_PASSWORD"
    use-ssl: false
    fallback-to-sqlite: false
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout-ms: 10000
      idle-timeout-ms: 600000
      max-lifetime-ms: 1800000

Create the database and user first:

CREATE DATABASE anziutils CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'anziutils'@'%' IDENTIFIED BY 'CHANGE_THIS_PASSWORD';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, INDEX, ALTER ON anziutils.* TO 'anziutils'@'%';
FLUSH PRIVILEGES;

Keep fallback-to-sqlite: false on networks. If MySQL goes down, a silent fallback would let one backend start writing to a local SQLite file and split your network state. With the fallback disabled the plugin disables itself safely instead.

Backend servers must also receive the real player IP from the proxy — set ip_forward: true on BungeeCord or configure player-info-forwarding-mode on Velocity.

Redis Network Synchronization

Redis is optional on a single server and recommended on a network. It synchronizes:

• Network-wide panic mode
• Shared smart-mutes
• A live online-player registry used by /anziutilsgui and /staffgui
• Cross-server staff action routing (freeze, bring, back, announce, cleardrops, spectate)
• Cached GeoIP and VPN lookup results
• Cross-server security alerts

Every backend must share the same Redis host, database, and key prefix — but each needs a unique server-id.

redis:
  enabled: true
  host: redis.example.com
  port: 6379
  username: ""
  password: "CHANGE_THIS_PASSWORD"
  database: 0
  use-ssl: false
  timeout-ms: 5000
  key-prefix: "anziutils"
  server-id: "survival-1"         # unique on every backend
  heartbeat-seconds: 10
  registry-ttl-seconds: 30
  session-grace-seconds: 20
  action-timeout-seconds: 30
  spectate-lock-seconds: 45
  proxy-server-name: "survival-1" # name registered on the proxy
  cache:
    geo-ttl-seconds: 86400
    vpn-ttl-seconds: 3600

For Velocity, also enable BungeeCord-compatible plugin messaging in velocity.toml so the Connect messages used by network transfers work:

bungee-plugin-message-channel = true

Security: never expose Redis to the public internet. Keep it on a private network, require a password or ACL user, and enable TLS when Redis traffic leaves a trusted network.

Backend Switches vs. Network Leaves

With Redis enabled, moving between backends is recognized as a backend switch rather than a fresh join: rule books, VPN/GeoIP checks, database join rows, and join notifications are not repeated. Staff see a notification for the initial network join, and again only after the player has been gone for the full session-grace-seconds window.

World-local systems — combat loggers, graves, redstone limiting, and automatic item-clear cycles — always stay on the backend they belong to.

Local Fallbacks

Every Redis-backed feature has a local fallback. If Redis is disabled or offline, the plugin keeps working on a per-server basis.

Security & Access Control

VPN / Proxy Detection

Connecting IPs are checked against proxycheck.io. Results are cached in Redis when it is enabled.

vpn-detection:
  enabled: true
  # true = kick the player, false = warn staff but let them join
  kick-on-vpn: true
  kick-message: "&cVPN/Proxy connections are not allowed on this server."

When kick-on-vpn is false, the player is allowed in but staff with anziutils.notify are warned — and, if smart-mute.mute-on-vpn-warn is enabled, the player is silently muted for the configured duration.

Alt Account Limiter

Restricts how many distinct accounts may connect from a single IP address, blocking botnets and ban evaders.

alt-limit:
  enabled: true
  max-accounts-per-ip: 3
  kick-message: "&cToo many accounts have connected from your IP address."

Country Filter (GeoIP)

Geolocation is resolved through ipwho.is. Use full country names exactly as that service returns them (for example "Slovenia" or "Germany") — not two-letter codes.

country-filter:
  # 'disabled', 'whitelist' (only these may join), or 'blacklist' (these are blocked)
  mode: disabled
  kick-message: "&cYou are not allowed to join from your country."
  countries:
    - "Slovenia"
    - "Croatia"
    - "Austria"

IP Exemptions

Two independent exemption paths bypass VPN detection and alt-limit checks entirely. The first is an IP list:

exempt-ips:
  - "127.0.0.1"

The second is the anziutils.exempt permission, which exempts the player wherever they connect from.

Panic Mode & Smart Mute

Panic Mode

Toggle an emergency lockdown with /anziutils panic when the server is hit by a bot raid. While panic mode is active the plugin applies a stricter ruleset:

panic-mode:
  # Only these countries may join while panic mode is on
  allowed-countries:
    - "Slovenia"
  # The alt limit is tightened to this number
  max-accounts-per-ip: 1
  # Players who joined less than this many minutes ago are muted
  mute-new-players-minutes: 5

Toggling panic mode notifies every online player with anziutils.notify or anziutils.admin, writes a console warning, and fires a Discord webhook. With Redis enabled the state is published network-wide, so one toggle locks down every backend.

Smart Mute

Suspicious joins are silently muted — blocked from chat and from chat-driven commands — for a limited window, without an obvious kick that tells an attacker what tripped.

smart-mute:
  # Mute players who join on a VPN when kick-on-vpn is false
  mute-on-vpn-warn: true
  mute-duration-minutes: 5

Smart mutes are shared across the network through Redis.

Combat Logging

Players are combat-tagged when they enter PvP and see a live action bar timer. Disconnecting while tagged spawns a combat logger NPC that can be killed for the player's loot.

Configuration

combat-log:
  enabled: true
  timer: 15                 # combat duration in seconds
  graves-enabled: true      # false = vanilla drops instead of a grave

  # Combat restrictions
  disable-enderpearls: true
  disable-golden-apples: true
  disable-chorus-fruit: true
  disable-totems: false
  disable-inventory-open: true
  disable-flying: true

  block-world-change: true
  block-server-switch: true

  blocked-commands:
    - "home"
    - "spawn"
    - "tp"
    - "tpa"
    - "tpaccept"
    - "warp"
    - "auback"
    - "sethome"
    - "rtp"
    - "wild"

  safe-zone-regions:
    - "spawn"
    - "safezone"

  join-grace-period: 3           # seconds after joining where tagging is impossible
  grave-protection-minutes: 5    # owner/killer-only looting window

Anti-Escape Restrictions

Each restriction has its own bypass permission, so you can loosen individual rules for specific ranks:

• Enderpearls
• Golden Apples
• Chorus Fruit
• Totems of Undying
• Creative flight and elytra gliding
• Opening containers and the inventory
• Blocked commands such as /tp, /spawn, /home
• World changes — portals and plugin teleports (block-world-change)
• Backend server switches through AnziUtils network transfers (block-server-switch)

Note on server switches: block-server-switch covers AnziUtils' own transfers (/auback, /bring, /randomplayer spectate). A player who leaves the backend another way — a proxy /server command, for instance — is still treated as a combat logger, and the NPC spawns on the backend they left.

WorldGuard Safe Zones

Region names listed under safe-zone-regions (case-insensitive) never apply a combat tag, so players can move through spawn and protected areas safely. Requires WorldGuard.

Join Grace Period

join-grace-period blocks combat tagging for the first few seconds after joining, preventing spawn-kill loops. Set it to 0 to disable.

Secure Player Graves

When combat-log.graves-enabled is true, deaths that go through the combat system spawn a player-head grave at the death location instead of scattering items on the ground.

How It Works

1. A player combat-logs or dies in combat
2. All items and XP are collected into a grave
3. An interactive player head marks the grave location
4. Floating holograms above it show the owner, the stored XP and item count, and the grave's age
5. The player clicks the head to open the grave and retrieve their items
6. Once the protection timer expires, anyone can loot it

Anti-Theft Protection

For the first grave-protection-minutes only the grave's owner or their killer can interact with it. After that it becomes public loot — which keeps grave-raiding in the game without making deaths feel cheap. Set the value to 0 to disable protection entirely.

combat-log:
  graves-enabled: true
  grave-protection-minutes: 5

Graves persist across server restarts.

Staff Account System

The Staff Account system lets staff members operate two completely separated player profiles: a normal profile (the one they play on as a regular player) and a staff profile (used when actively moderating). Switching is instant, and nearby players are not told who is staff.

How It Works

1. A staff member runs /staffaccount (alias /staff) to enter staff mode.
2. Their backend server, world, coordinates, yaw/pitch, and gamemode are saved to the database as the /auback target.
3. Inventory, ender chest, statistics, balance, and LuckPerms groups swap to the staff profile, according to staff-account.separate.
4. Staff godmode activates — no damage, and no combat tags.
5. When they teleport, position/rotation/sound packets are hidden from non-admin players (ghosting).
6. Running /auback (alias /staffback) returns them to the saved location and gamemode and exits staff mode.

Because the session is stored centrally, a reload or a backend switch restores the correct session instead of stranding the staff member without a valid /auback target.

Ranks are applied additively. Entering or leaving staff mode never removes a player's existing LuckPerms groups.

Configuration

staff-account:
  enabled: true
  separate:
    inventory: true      # main inventory, armor, offhand
    ender-chest: true
    stats: true          # vanilla statistics (playtime, kills, deaths, ...)
    ranks: true          # requires LuckPerms
    currency: true       # requires Vault + an economy plugin

  block-in-combat: true       # no escaping combat via a profile swap
  block-while-frozen: true
  godmode: true               # invulnerable in staff mode, also blocks combat tags
  ghost-on-teleport: true     # hide position/rotation/sound packets from non-admins
  teleport-view-distance: 3   # view distance after a staff teleport (0 = don't change)
  require-back-to-exit: true  # must use /auback before leaving staff mode

  staff-only-commands:
    - "ban"
    - "tempban"
    - "ipban"
    - "kick"
    - "mute"
    - "tempmute"
    - "warn"
    - "vanish"
    - "v"
    - "freeze"
    - "bring"
    - "tp"
    - "tpo"
    - "tphere"
    - "teleport"

Staff-Only Commands

Commands listed under staff-only-commands are blocked for anyone holding anziutils.staffaccount while they are on their normal profile. This stops staff from moderating while playing as a regular player.

Commands

Network Staff Tools

With Redis enabled, the staff commands work across the whole network rather than one backend.

Staff Panel

/staffgui opens the AnziUtils — Staff Panel, a single inventory menu for staff mode, vanish, freeze, bring, announcements, panic mode, drop clearing, and spectating. Targeted actions open a player picker listing everyone online across the network, with their current backend shown in the lore.

Cross-Server Commands

Staff Target Hierarchy

Targeted staff commands (/freeze, /bring, /randomplayer) respect a rank hierarchy, so moderators cannot act on admins — and no staff member can target themselves.

staff-hierarchy:
  enabled: true
  require-luckperms: true

• The actor's highest LuckPerms group weight must be greater than the target's.
• Console bypasses the check entirely.
• With require-luckperms: true the check fails closed — if LuckPerms or a user's rank data is unavailable, the action is blocked rather than allowed.

Vanish

/vanish hides the staff member from other players. Sounds they generate are suppressed for nearby observers, and entity visibility is handled at the packet level so they do not give themselves away. Vanish state is synchronized across the network.

Server Utilities

Item Clearer

Periodically clears ground items to keep entity counts under control.

item-clear:
  enabled: true
  interval-minutes: 5
  excluded-worlds:
    - "world_the_end"

/cleardrops runs an immediate clear using the same filters.

Redstone Limiter

Throttles runaway redstone per chunk so a lag machine cannot tank the server.

redstone-limiter:
  enabled: true
  max-pulses-per-second: 150
  cooldown-seconds: 5
  alert-admins: true

When a chunk crosses the threshold it is suppressed for cooldown-seconds, and players with anziutils.admin are notified if alert-admins is on.

Chat @Mention Tagging

Mentioning a player's name in chat highlights it and plays a sound for them.

chat-mentions:
  enabled: true
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  color: "YELLOW"

Command Watch

Sends a Discord notification whenever a watched command is executed — an audit trail for the commands that matter. Matching is on the base command, so op matches /op Player.

command-watch:
  enabled: true
  commands:
    - "op"
    - "deop"
    - "stop"
    - "ban"
    - "ban-ip"
    - "pardon"
    - "gamemode"
    - "whitelist"
    - "kick"

Interactive Rule Books

New players automatically receive a written book of your server rules the first time they join. The contents live in rules.yml, where each list entry is one page:

enabled: true

book:
  title: "&6Server Rules"
  author: "&cServer Administration"
  pages:
    - "&lWelcome to the server!&r\n\nPlease read through our rulebook carefully."
    - "&l1. No Cheating/Hacking&r\nAny use of modified clients will result in a permanent ban."
    - "&l2. Be Respectful&r\nDo not harass, flame, or dox other players."

Use \n to start a new line within a page.

With Redis enabled, a player switching backends does not receive a duplicate book.

Discord Webhook Integration

Discord settings live in their own file, plugins/AnziUtils/discord.yml. Set the master toggle and your webhook URL, then enable the events you care about.

enabled: false
webhook-url: "https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN"
bot-name: "AnziUtils"
bot-avatar: "https://mc-heads.net/avatar/MHF_Question/128"

notifications:
  vpn-detection: ...
  alt-limit: ...
  combat-log-death: ...
  combat-log-rejoin: ...
  panic-mode: ...
  command-watch: ...

Available Notifications

Each event has its own enabled flag plus embed title, description, and color, so you can route only the alerts you want into your staff channel.

Test Your Webhook

Run /anziutilstest to send test payloads and confirm the integration works.

Commands

Lookup & Administration

Staff Tools

Permissions

Administrative

Bypasses

PlaceholderAPI

When PlaceholderAPI is installed, AnziUtils registers the anziutils expansion automatically. It persists across /papi reload.

Full config.yml

The complete default configuration, for reference:

# =======================================
#   AnziUtils Configuration
# =======================================

# AnziLock License Configuration
license:
  # Insert the license key you received via Discord here (see /claim).
  key: ""

# Database Configuration
# Supported types: sqlite, mysql
database:
  type: sqlite
  mysql:
    host: localhost
    port: 3306
    database: anziutils
    username: root
    password: ""
    use-ssl: false
    fallback-to-sqlite: false
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout-ms: 10000
      idle-timeout-ms: 600000
      max-lifetime-ms: 1800000

# Redis Synchronization (optional, for multi-server networks)
redis:
  enabled: false
  host: localhost
  port: 6379
  username: ""
  password: ""
  database: 0
  use-ssl: false
  timeout-ms: 5000
  key-prefix: "anziutils"
  server-id: "survival-1"
  heartbeat-seconds: 10
  registry-ttl-seconds: 30
  session-grace-seconds: 20
  action-timeout-seconds: 30
  spectate-lock-seconds: 45
  proxy-server-name: ""
  cache:
    geo-ttl-seconds: 86400
    vpn-ttl-seconds: 3600

# VPN / Proxy Detection
vpn-detection:
  enabled: true
  kick-on-vpn: true
  kick-message: "&cVPN/Proxy connections are not allowed on this server."

# Alt Account Limiter
alt-limit:
  enabled: true
  max-accounts-per-ip: 3
  kick-message: "&cToo many accounts have connected from your IP address."

# Exempt IPs
exempt-ips:
  - "127.0.0.1"

# Country Filter - 'disabled', 'whitelist', or 'blacklist'
country-filter:
  mode: disabled
  kick-message: "&cYou are not allowed to join from your country."
  countries:
    - "Slovenia"
    - "Croatia"
    - "Austria"

# Panic Mode
panic-mode:
  allowed-countries:
    - "Slovenia"
  max-accounts-per-ip: 1
  mute-new-players-minutes: 5

# Smart Mute
smart-mute:
  mute-on-vpn-warn: true
  mute-duration-minutes: 5

# Combat Log Module
combat-log:
  enabled: true
  timer: 15
  graves-enabled: true

  disable-enderpearls: true
  disable-golden-apples: true
  disable-chorus-fruit: true
  disable-totems: false
  disable-inventory-open: true
  disable-flying: true

  block-world-change: true
  block-server-switch: true

  blocked-commands:
    - "home"
    - "spawn"
    - "tp"
    - "tpa"
    - "tpaccept"
    - "warp"
    - "auback"
    - "sethome"
    - "rtp"
    - "wild"

  safe-zone-regions:
    - "spawn"
    - "safezone"

  join-grace-period: 3
  grave-protection-minutes: 5

# Chat @Mention Tagging
chat-mentions:
  enabled: true
  sound: ENTITY_EXPERIENCE_ORB_PICKUP
  color: "YELLOW"

# Item Clearer
item-clear:
  enabled: true
  interval-minutes: 5
  excluded-worlds:
    - "world_the_end"

# Redstone Limiter
redstone-limiter:
  enabled: true
  max-pulses-per-second: 150
  cooldown-seconds: 5
  alert-admins: true

# Command Watch (Discord Broadcast)
command-watch:
  enabled: true
  commands:
    - "op"
    - "deop"
    - "stop"
    - "ban"
    - "ban-ip"
    - "pardon"
    - "gamemode"
    - "whitelist"
    - "kick"

# Staff Target Hierarchy
staff-hierarchy:
  enabled: true
  require-luckperms: true

# Staff Dual Accounts
staff-account:
  enabled: true
  separate:
    inventory: true
    ender-chest: true
    stats: true
    ranks: true
    currency: true
  block-in-combat: true
  block-while-frozen: true
  godmode: true
  ghost-on-teleport: true
  teleport-view-distance: 3
  require-back-to-exit: true
  staff-only-commands:
    - "ban"
    - "tempban"
    - "ipban"
    - "kick"
    - "mute"
    - "tempmute"
    - "warn"
    - "vanish"
    - "v"
    - "freeze"
    - "bring"
    - "tp"
    - "tpo"
    - "tphere"
    - "teleport"

Troubleshooting

Q: The plugin disables itself on startup

A: Check the console for an [AnziLock] line. NO_KEY means license.key is still empty; a network error means the server could not reach license.ajdnikov-dev.com. Also confirm you are on Java 21 and Paper 1.21+.

Q: Every player is flagged as a VPN, or none are

A: VPN checks go to proxycheck.io and geolocation to ipwho.is. Make sure the server has outbound internet access, then run /anziutilsdebug to see live API results and rate-limit status. If you are behind a proxy, confirm the real player IP is being forwarded (ip_forward on BungeeCord, player-info-forwarding-mode on Velocity) — otherwise every player appears to come from the proxy's IP.

Q: The alt limiter counts everyone as the same player

A: This is the proxy-forwarding problem above. Without forwarding, all connections share the proxy's IP.

Q: Combat logging is not triggering

A: Verify combat-log.enabled: true, that the players are not inside a region listed in safe-zone-regions, that they are past the join-grace-period, and that they do not hold anziutils.combatlog.bypass.

Q: Graves are not spawning

A: Graves live under the combat module. Set combat-log.graves-enabled: true — when it is false, items and XP drop on the ground like vanilla.

Q: Staff data is split between servers

A: Every backend must point at the same MySQL database with fallback-to-sqlite: false, and each backend needs a unique redis.server-id.

Q: /bring or /auback does not transfer across servers

A: Cross-server transfers need Redis enabled on every backend, a correct proxy-server-name (or a server-id matching the proxy's registered name), and — on Velocity — bungee-plugin-message-channel = true.

Q: Discord webhook not working

A: Check discord.yml: the master enabled flag, the webhook URL, and the individual event toggle. Then run /anziutilstest.

Q: Need more help?

A: Join our Discord server for support and bug reports.