🛡️ Ultimate Anti-Illegals

Ultimate Anti-Illegals is a powerful, lightweight, and fully customizable protection plugin engineered for modern Paper Minecraft servers (1.21-26.2). Designed specifically to maintain economy balance and server integrity, it finds illegally glitched or modified items and removes, repairs or quarantines them in real-time, while staying out of the way of other plugins.

Every behavior is controlled from config.yml: what counts as illegal, where it is checked, what happens to the item, who is exempt and what happens to repeat offenders.

✨ Features

🔍 What it detects

🚫 Forbidden Items: A configurable list of materials (spawners, command blocks, bedrock, barriers, ...) and optionally all spawn eggs.
📚 Over-Stacked Items: Stacks larger than the item's maximum stack size.
🧪 Enchantment Validation: Over-leveled enchantments (Sharpness X), conflicting enchantments (Sharpness + Smite, Mending + Infinity) and, optionally, enchantments that do not belong on the item. Also checks the stored enchantments of enchanted books.
🧬 NBT Checks: Unbreakable items, custom lore, attribute modifiers and (optionally) custom names. Each check can be switched on or off separately.
🧳 Shulker Boxes & Bundles: Looks inside them, up to a configurable depth. Only the illegal item inside is dealt with, the box itself stays.

📍 Where it protects

⚡ Player Inventory Scan: Periodically scans online players' inventories without hurting TPS.
📦 Containers: Chests, barrels, shulker boxes, ender chests and more are cleaned when a player opens them, and illegal items can not be stored in them.
🗺️ Chunk Scan: Placed containers are cleaned when their chunk loads, so nobody has to open a chest to clean it. Chunks are processed a few per tick, so it can not cause lag spikes.
🔻 Hoppers: Hoppers, droppers and hopper minecarts can not move illegal items, and can not pick them up from the ground.
🧱 Actions: Dropping and placing illegal items is blocked.
🎒 Custom Inventories: Backpack and virtual chest plugins can optionally be covered too. Menus can be excluded by title.

🎚️ What happens to an illegal item

Choose per violation type, with a global default:

Action	Result
`REMOVE`	The item is deleted.
`SANITIZE`	The item is repaired: enchants back to their max level, conflicting enchants dropped, unbreakable/lore/name/attributes removed, stack size back to max. Things that can not be repaired (forbidden materials, spawn eggs) are removed.
`QUARANTINE`	The item is deleted, but a copy is saved. Restore false positives with `/antiillegal quarantine restore <id>` or delete them for good with `/antiillegal quarantine delete <id>`.
`LOG_ONLY`	Nothing is touched or blocked, it is only logged and alerted.

🧪 Dry-Run

New on a server? Turn on dry-run and the plugin will only log and alert: nothing is removed, repaired, blocked or punished. Read the log, add exceptions for false positives, then switch it off. Start it in the config, or temporarily with /antiillegal dryrun 60.

🚨 Punishments

Warn, kick or run your own commands (e.g. a temporary ban with your ban plugin) after X violations within Y minutes. Violations that were only logged (LOG_ONLY, dry-run) never count.

🔔 Alerts & Logging

Staff alerts for everyone with antiillegal.alerts, with a cooldown so chat does not get spammed. They show what was found, where, and what was done about it.
💬 Discord Webhook: Send findings and punishments to a Discord channel. Messages are batched and rate-limit safe, can ping a role, and show the player, source, action and items.
🔄 Update Checker: Tells you (and staff with antiillegal.update) when a new version is available on Modrinth. It only reads version info and never downloads anything.
📊 bStats: Anonymous usage statistics for the author, easy to switch off.
🔌 PlaceholderAPI: Show statistics on scoreboards, holograms or tab lists (optional, see below).
Log file plugins/UltimateAntiIllegals/logs/illegals.log with player, source, type, action, item and location. Written in the background, so it never blocks the server.

🔐 Control

Bypass per category: staff can skip only some checks (for example NBT items yes, bedrock no).
Per-world control: enabled-worlds and disabled-worlds, for example to leave a creative or lobby world alone.
Plugin-friendly: menus and hotbar items from other plugins (server selectors, kit items, ...) are not wiped. NBT checks only block moving such items by default, and a trusted-items allowlist exempts specific items completely.
Fully customizable messages: every message, the prefix, the reasons and the actions live under messages in config.yml.
🚀 Lightweight & Optimized: Settings are cached, item data is only read when a check needs it, and the file work happens off the main thread.

🎮 Commands & Permissions

Command	Description	Permission	Default
`/antiillegal reload`	Reloads the plugin configuration	`antiillegal.admin`	OP
`/antiillegal dryrun [minutes\|off]`	Starts or stops a temporary dry-run. Without arguments it shows the status.	`antiillegal.admin`	OP
`/antiillegal quarantine list [player]`	Shows the newest quarantined items	`antiillegal.admin`	OP
`/antiillegal quarantine restore <id> [player]`	Gives a quarantined item back to you or the given player	`antiillegal.admin`	OP
`/antiillegal quarantine delete <id>`	Permanently deletes a quarantined item	`antiillegal.admin`	OP
`/antiillegal discord test`	Sends a test message to your Discord webhook	`antiillegal.admin`	OP
`/antiillegal update`	Checks right now for a new version	`antiillegal.admin`	OP

Aliases: /ultimateantiillegals, /uai

Permission	Description	Default
`antiillegal.alerts`	Receive staff alerts	OP
`antiillegal.update`	Get a message on join when a new version is available	OP
`antiillegal.bypass`	Exempt from all checks	Nobody
`antiillegal.bypass.materials`	Exempt from the forbidden items list and spawn eggs	Nobody
`antiillegal.bypass.stacks`	Exempt from the over-stacked check	Nobody
`antiillegal.bypass.enchants`	Exempt from the enchantment checks	Nobody
`antiillegal.bypass.nbt`	Exempt from the NBT checks (unbreakable, name, lore, attributes)	Nobody
`antiillegal.bypass.nested`	Exempt from shulker box and bundle inspection	Nobody

By default OPs bypass everything (op-bypass: true in the config).

⚙️ Installation

Download the latest release .jar.
Drop the file into your server's plugins/ directory.
Start your Paper server (Java 21+ required).
(Recommended) Run /antiillegal dryrun 60 and watch plugins/UltimateAntiIllegals/logs/illegals.log for the first hour.
Edit plugins/UltimateAntiIllegals/config.yml to your liking.
Run /antiillegal reload to apply any changes live!

🧠 How It Works

Every item goes through the same three questions:

Does the check apply to this player? Not in a disabled world, and not for the categories they have a bypass permission for.
Does the item break a rule? Forbidden material, stack size, enchantments, NBT and the contents of shulker boxes and bundles. Items that match trusted-items are never touched.
What do we do about it? The actions section decides per violation type. During a dry-run the answer is always "only log it".

Other plugins' items

Lobby menus, duel kits and custom item plugins hand out items with a name, lore or an unbreakable flag. These would normally look illegal. That is why the NBT checks are split into where they apply:

nbt-checks:
  apply-to:
    inventory-scan: false   # periodic scan (would delete the item)
    container-scan: false   # container scan (would delete the item)
    transfers: true         # dropping, placing, storing (only blocks the action)

Menus created by other plugins are not containers and are ignored. For anything that still gets flagged, exempt it with trusted-items.

🧩 Configuration Highlights

Choose what happens per violation:

actions:
  default: REMOVE
  overrides:
    over-enchanted: SANITIZE
    unbreakable: SANITIZE
    illegal-material: QUARANTINE

Exempt items from other plugins:

trusted-items:
  - material: COMPASS
    lore-contains: "Click to open the menu"
  - pdc-namespace: "yourplugin"

Every rule needs at least one of name-contains, lore-contains or pdc-namespace. Prefer lore or PDC over the name, since players can rename items in an anvil.

Leave worlds alone:

disabled-worlds:
  - creative
  - lobby

Cover backpack or virtual chest plugins:

custom-inventories:
  check-transfers: true
  scan-on-open: true
  ignored-titles:
    - "Server Selector"

Backpacks and menus look the same to the server, so use ignored-titles for your menus.

Send everything to Discord:

discord:
  enabled: true
  webhook-url: "https://discord.com/api/webhooks/..."
  mention-punishments: "<@&123456789012345678>"   # optional ping
  actions: [REMOVED, QUARANTINED]                  # empty = everything

Create the webhook in Discord (Channel settings > Integrations > Webhooks) and keep the URL secret. Run /antiillegal discord test to check it. Only real discord.com / discordapp.com webhook URLs are accepted. Messages are sent in batches of up to 10 (at most one message every batch-seconds), and the same player is not sent again within cooldown-seconds. The log file always has everything.

Punish repeat offenders:

punishments:
  enabled: true
  window-minutes: 10
  steps:
    - violations: 3
      warn: "&cStop trying to use illegal items!"
    - violations: 5
      kick: "Illegal items are not allowed on this server."
    - violations: 8
      commands:
        - "tempban {player} 1d Repeatedly using illegal items"

commands are run by the console, so use the syntax of your ban plugin. One violation is one incident (one scan, one blocked drop, ...), no matter how many items were involved.

Everything else (scan interval, chunk scan speed, hopper checks, shulker/bundle depth, alerts, logging, quarantine retention, messages) is documented with comments in the default config.yml.

🔄 Updates & Statistics

Update checker. On startup and then every 12 hours (update-checker.interval-hours), the plugin asks Modrinth for the list of versions of this plugin. If a newer release exists, it is shown in the console, and staff with antiillegal.update get a message when they join. Beta and alpha versions are ignored unless you set include-prereleases: true. Nothing is downloaded or installed, and nothing about your server is sent besides the plugin name and version (in the User-Agent, which Modrinth requires). Check manually with /antiillegal update.

update-checker:
  enabled: true
  interval-hours: 12
  notify-on-join: true
  include-prereleases: false

bStats. The plugin uses bStats to count how many servers and players use it, which server and Java versions are common, and which features are switched on (yes/no only: default action, dry-run, punishments, Discord webhook, chunk scan, custom inventories, trusted items, PlaceholderAPI). It never sends player names, items, IP addresses or logs. Turn it off for this plugin with metrics.enabled: false (restart needed), or for all plugins in plugins/bStats/config.yml.

🔌 PlaceholderAPI

If PlaceholderAPI is installed, these placeholders are registered automatically (nothing to configure, and the plugin works fine without PlaceholderAPI):

Placeholder	Description
`%antiillegal_total_violations%`	Total violations on the server (only counts when something was done about it)
`%antiillegal_total_removed%`	Total items removed (including quarantined)
`%antiillegal_total_sanitized%`	Total items repaired
`%antiillegal_total_quarantined%`	Total items quarantined
`%antiillegal_quarantine_count%`	Items in quarantine right now
`%antiillegal_dryrun%`	`true` while a dry-run is active
`%antiillegal_dryrun_minutes%`	Minutes left of a temporary dry-run (`0` if none)
`%antiillegal_update_available%`	`true` when a newer version is available
`%antiillegal_latest_version%`	The newest known version (your own version if nothing newer is known)
`%antiillegal_violations%`	Violations of this player
`%antiillegal_removed%`	Items removed from this player
`%antiillegal_sanitized%`	Items repaired for this player
`%antiillegal_bypassed%`	`true` if this (online) player is exempt from all checks

Statistics are saved to plugins/UltimateAntiIllegals/stats.yml.

📝 Log Example

[2026-10-08 05:13:01] player=Steve uuid=... source=SCANNER type=OVER_ENCHANTED action=SANITIZED item=DIAMOND_SWORD x1 detail=sharpness 6>5 location=world 118 72 -126
[2026-10-08 05:13:01] player=- uuid=- source=CHUNK_SCAN type=ILLEGAL_MATERIAL action=REMOVED item=SHULKER_BOX > BEDROCK x1 detail=BEDROCK location=world 5 64 5

🛠️ Compatibility

Minecraft Version: 1.21 – 26.2
Optional Plugins: PlaceholderAPI
Server Software: Paper. Spigot, Purpur and Pufferfish compatibility is being tested. Folia is not supported.
Java Version: Java 21+

Good to know

Items in unloaded chunks are only cleaned when the chunk loads or the container is opened.
Offline players are not scanned. Their inventories are checked when they join and on the next scan.
Menus and backpacks from other plugins are ignored unless you enable custom-inventories.

💬 Need Support or Have Questions?
Join our community on Discord: dsc.gg/geturplugins

Made with ❤️ by Berkayprof - GetUrPlugins

Ultimate Anti-Illegals

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details