Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
๐ก๏ธ Ultimate Anti-Illegals
๐ก๏ธ Keep your Minecraft server safe from illegal, glitched and modified items.
Ultimate Anti-Illegals detects, removes, repairs or quarantines illegal items in real-time โ protecting your server's economy and integrity without interfering with other plugins.
๐ Overview
Ultimate Anti-Illegals is a powerful, lightweight and fully customizable protection plugin for modern Paper Minecraft servers (1.21โ26.3).
It continuously checks player inventories, containers, item transfers and more for items that violate your server's rules. From over-stacked items and over-leveled enchantments to forbidden materials and suspicious NBT data, the plugin gives you full control over what is allowed on your server.
Every behavior can be configured through config.yml:
- ๐ Choose exactly what counts as an illegal item.
- ๐ Control where and when items are checked.
- โ๏ธ Decide what happens when an illegal item is found.
- ๐ Exempt trusted players, worlds and custom items.
- ๐จ Configure alerts and punishments for repeat offenders.
โจ Why Choose Ultimate Anti-Illegals?
- ๐ก๏ธ Complete Item Protection โ Detects a wide range of illegal and modified items.
- โ๏ธ Fully Customizable โ Configure checks and actions individually.
- ๐งช Safe Dry-Run Mode โ Test your settings without changing or removing items.
- ๐ฆ Advanced Container Scanning โ Checks containers, nested storage and chunk-loaded inventories.
- ๐ Plugin-Friendly โ Avoids interfering with menus and custom items from other plugins.
- ๐ Performance Optimized โ Cached settings and background file operations help keep server performance stable.
- ๐ Discord Integration โ Receive findings and punishment notifications directly in Discord.
โจ Features
๐ What It Detects
- ๐ซ Forbidden Items โ Configurable list of materials such as spawners, command blocks, bedrock and barriers. Spawn eggs can optionally be included.
- ๐ Over-Stacked Items โ Detects item stacks that exceed their maximum stack size.
- ๐งช Enchantment Validation โ Detects over-leveled enchantments (e.g. Sharpness X), conflicting enchantments (e.g. Sharpness + Smite or Mending + Infinity) and optionally enchantments that do not belong on the item.
- ๐ Enchanted Book Checks โ Also validates stored enchantments on enchanted books.
- ๐งฌ NBT Checks โ Detects unbreakable items, custom lore, attribute modifiers and optionally custom names.
- ๐งณ Nested Storage Checks โ Inspects shulker boxes and bundles up to a configurable depth. Only the illegal item inside is handled; the container itself remains intact.
๐ Where It Protects
- โก Player Inventories โ Periodically scans online players' inventories.
- ๐ฆ Containers โ Checks chests, barrels, shulker boxes, ender chests and more when opened. Illegal items cannot be stored in them.
- ๐บ๏ธ Chunk Scanning โ Cleans placed containers when their chunk loads. Only a few containers are processed per tick to avoid lag spikes.
- ๐ป Hoppers & Automation โ Prevents hoppers, droppers and hopper minecarts from moving illegal items or picking them up from the ground.
- ๐งฑ Item Actions โ Blocks dropping and placing illegal items.
- ๐ Custom Inventories โ Can optionally cover backpack and virtual chest plugins. Menus can be excluded by title.
๐๏ธ What Happens to Illegal Items?
Choose an action for each violation type, with a global default action.
| Action | Description |
|---|---|
REMOVE |
Deletes the illegal item permanently. |
SANITIZE |
Repairs the item where possible. Enchantments are corrected, conflicting enchantments are removed, illegal NBT data is cleared and stack sizes are restored. Items that cannot be repaired, such as forbidden materials and spawn eggs, are removed. |
QUARANTINE |
Removes the item and saves a copy. Staff can restore it or permanently delete it later. |
LOG_ONLY |
Does not modify or block the item. The finding is only logged and reported. |
Quarantined items can be managed with:
/antiillegal quarantine restore <id>/antiillegal quarantine delete <id>
๐งช Dry-Run Mode
Want to test your configuration before enabling protection?
Enable Dry-Run Mode to let the plugin detect and report illegal items without taking action.
While dry-run is active:
- ๐ Findings are logged and reported.
- ๐ซ Items are not removed.
- ๐ง Items are not repaired.
- ๐ Actions are not blocked.
- โ๏ธ Punishments are not triggered.
You can enable it in the configuration or temporarily run:
/antiillegal dryrun 60
Review the log, configure exceptions for false positives and disable dry-run when you're ready.
๐จ Punishment System
Configure automatic responses to repeated violations.
The plugin can warn or kick players, or execute custom console commands after a configurable number of violations within a time window.
For example, you can use your existing ban plugin to temporarily ban repeat offenders.
Violations that are only logged โ through LOG_ONLY or dry-run mode โ never count towards punishments.
๐ Alerts & Logging
- ๐ข Staff Alerts โ Notify staff members with
antiillegal.alerts. Alerts include what was found, where it was found and which action was taken. A cooldown helps prevent chat spam. - ๐ฌ Discord Webhooks โ Send findings and punishments to a Discord channel. Messages are batched and rate-limit safe, with optional role mentions.
- ๐ Update Checker โ Notifies the console and staff with
antiillegal.updatewhen a newer Modrinth release is available. It only checks version information and never downloads anything. - ๐ bStats โ Anonymous usage statistics that can be disabled.
- ๐ PlaceholderAPI โ Display plugin statistics through scoreboards, holograms or tab lists.
- ๐ Detailed Logs โ All findings are written to
plugins/UltimateAntiIllegals/logs/illegals.log. Logging runs in the background.
๐ Control & Customization
- ๐ Category Bypass โ Give staff permission to bypass specific checks instead of all protection.
- ๐ Per-World Settings โ Enable or disable protection in selected worlds.
- ๐ค Plugin-Friendly Protection โ Custom items from menus, kits and other plugins are protected from unwanted NBT-related removal by default.
- ๐ Trusted Items โ Fully exempt specific custom items using
trusted-items. - ๐ฌ Custom Messages โ Configure every message, prefix, reason and action through the
messagessection. - ๐ Optimized Checks โ Settings are cached and item data is only read when needed.
๐ Documentation
โ๏ธ How It Works
Every item goes through three main checks:
-
Does the check apply?
The plugin checks whether the player is in an enabled world and whether they have a bypass permission for the relevant category.
-
Does the item violate a rule?
The plugin checks forbidden materials, stack sizes, enchantments, NBT data and nested storage contents. Items matching
trusted-itemsare exempt. -
What should happen?
The configured action determines whether the item is removed, sanitized, quarantined or only logged.
During dry-run mode, the plugin only logs and reports findings.
๐ค Compatibility With Other Plugins
Many plugins use custom items with names, lore or unbreakable flags. Examples include:
- ๐งญ Server selector items.
- โ๏ธ Custom duel and kit items.
- ๐ Items from custom inventory plugins.
- ๐ Other plugin-generated items.
These items can look suspicious to an item protection plugin. Ultimate Anti-Illegals therefore separates NBT checks by where they apply.
By default, NBT checks do not apply to periodic inventory scans or container scans, but they do apply to item transfers.
nbt-checks:
apply-to:
inventory-scan: false
container-scan: false
transfers: true
Menus created by other plugins are not treated as containers and are ignored. If an item is still incorrectly flagged, add it to trusted-items.
๐งณ Shulker Boxes & Bundles
The plugin can inspect items stored inside shulker boxes and bundles.
- ๐ Nested contents are checked up to a configurable depth.
- ๐ฏ Only the illegal item is handled.
- ๐ฆ The shulker box or bundle itself is kept intact.
๐ฎ Protection & Configuration Systems
๐๏ธ Configurable Actions
Set a global default action and override it for individual violation types.
actions:
default: REMOVE
overrides:
over-enchanted: SANITIZE
unbreakable: SANITIZE
illegal-material: QUARANTINE
๐ก๏ธ Trusted Items
Exempt custom items from other plugins so they are not incorrectly flagged.
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.
๐ก Tip: Prefer lore or PDC checks over names, because players can rename items using an anvil.
๐ World Control
Exclude specific worlds from protection.
disabled-worlds:
- creative
- lobby
You can also configure enabled-worlds to control exactly where the plugin is active.
๐ Custom Inventories
Enable checks for backpack and virtual chest plugins.
custom-inventories:
check-transfers: true
scan-on-open: true
ignored-titles:
- "Server Selector"
๐ก Note: Backpacks and menus can look similar to the server. Use ignored-titles to exclude menus that should not be checked.
๐ฌ Discord Webhook
Send findings and punishments to a Discord channel.
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
mention-punishments: "<@&123456789012345678>"
actions: [REMOVED, QUARANTINED]
- Create a webhook through Discord โ Channel Settings โ Integrations โ Webhooks.
- Keep your webhook URL secret.
- Use
/antiillegal discord testto test the connection. - Only real
discord.comanddiscordapp.comwebhook URLs are accepted. - Messages are sent in batches of up to 10, with a configurable sending interval.
- The same player is not sent again within the configured cooldown.
- The log file always contains all findings.
An empty actions list means all actions are included.
๐จ Punishment Configuration
Configure how the plugin handles 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 executed by the console, so use the command syntax of your installed punishment or ban plugin.
One violation represents one incident โ for example, one scan or one blocked drop โ regardless of how many items were involved.
๐ Update Checker
The update checker contacts Modrinth on startup and then at the configured interval.
update-checker:
enabled: true
interval-hours: 12
notify-on-join: true
include-prereleases: false
- ๐ New versions are reported in the console.
- ๐ค Staff with
antiillegal.updateare notified when joining. - ๐งช Beta and alpha releases are ignored by default.
- โ๏ธ Set
include-prereleases: trueto include them. - ๐ฅ The plugin never downloads or installs updates automatically.
The request only sends the plugin name and version in the User-Agent required by Modrinth.
๐ bStats
Ultimate Anti-Illegals uses bStats to collect anonymous usage statistics.
This includes information such as server and player counts, server and Java versions, and whether certain plugin features are enabled.
It does not send player names, items, IP addresses or log contents.
To disable metrics for this plugin:
metrics:
enabled: false
A restart is required after changing this setting.
You can also disable bStats for all plugins through plugins/bStats/config.yml.
๐ Logging
Detailed findings are stored in:
plugins/UltimateAntiIllegals/logs/illegals.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
๐ป Commands
All commands require administrator access by default.
| Command | Description | Permission |
|---|---|---|
/antiillegal reload |
Reloads the plugin configuration. | antiillegal.admin |
/antiillegal dryrun [minutes|off] |
Starts or stops a temporary dry-run. Without arguments, displays the current status. | antiillegal.admin |
/antiillegal quarantine list [player] |
Shows the newest quarantined items. | antiillegal.admin |
/antiillegal quarantine restore <id> [player] |
Restores a quarantined item to you or the specified player. | antiillegal.admin |
/antiillegal quarantine delete <id> |
Permanently deletes a quarantined item. | antiillegal.admin |
/antiillegal discord test |
Sends a test message to your Discord webhook. | antiillegal.admin |
/antiillegal update |
Checks for a new version immediately. | antiillegal.admin |
Command aliases:
/ultimateantiillegals
/uai
๐ Permissions
Ultimate Anti-Illegals provides both global and category-specific bypass permissions.
๐ Permission Overview
| Permission | Description | Default |
|---|---|---|
antiillegal.admin |
Access administrative commands. | OP |
antiillegal.alerts |
Receive staff alerts. | OP |
antiillegal.update |
Receive update notifications when joining. | OP |
antiillegal.bypass |
Bypass all protection checks. | Nobody |
antiillegal.bypass.materials |
Bypass forbidden material and spawn egg checks. | Nobody |
antiillegal.bypass.stacks |
Bypass over-stacked item checks. | Nobody |
antiillegal.bypass.enchants |
Bypass enchantment checks. | Nobody |
antiillegal.bypass.nbt |
Bypass NBT checks, including unbreakable, name, lore and attributes. | Nobody |
antiillegal.bypass.nested |
Bypass shulker box and bundle inspection. | Nobody |
๐ก Note: Operators bypass all checks by default. This behavior can be changed with op-bypass: true in the configuration.
๐ค PlaceholderAPI
Ultimate Anti-Illegals supports PlaceholderAPI.
If PlaceholderAPI is installed, the following placeholders are registered automatically. No additional configuration is required.
| Placeholder | Description |
|---|---|
%antiillegal_total_violations% |
Total server violations. Only counts when an action was taken. |
%antiillegal_total_removed% |
Total items removed, including quarantined items. |
%antiillegal_total_sanitized% |
Total items repaired. |
%antiillegal_total_quarantined% |
Total items quarantined. |
%antiillegal_quarantine_count% |
Number of items currently in quarantine. |
%antiillegal_dryrun% |
true while dry-run mode is active. |
%antiillegal_dryrun_minutes% |
Minutes remaining in a temporary dry-run. 0 if inactive. |
%antiillegal_update_available% |
true if a newer version is available. |
%antiillegal_latest_version% |
Newest known version, or your current version if no newer version is known. |
%antiillegal_violations% |
Total violations for the player. |
%antiillegal_removed% |
Items removed from the player. |
%antiillegal_sanitized% |
Items repaired for the player. |
%antiillegal_bypassed% |
true if the online player is exempt from all checks. |
Statistics are stored in:
plugins/UltimateAntiIllegals/stats.yml
Requirements: PlaceholderAPI is optional. Ultimate Anti-Illegals works without it.
โ๏ธ Configuration
The plugin's behavior is controlled through config.yml.
The configuration includes settings for:
- ๐ Item detection and validation.
- ๐๏ธ Actions per violation type.
- ๐งช Dry-run mode.
- ๐ฆ Inventory, container and chunk scanning.
- ๐ป Hopper and item transfer checks.
- ๐งณ Shulker box and bundle inspection depth.
- ๐ Bypass permissions and world restrictions.
- ๐ Custom inventories and trusted items.
- ๐จ Punishments and staff alerts.
- ๐ฌ Discord webhooks.
- ๐ Logging and quarantine retention.
- ๐ Update checker and metrics.
- ๐ฌ Custom messages.
The examples in the documentation highlight some of the most useful settings. All other options are documented with comments in the generated default config.yml.
๐ฅ Installation
Getting started is easy!
๐ Requirements
| Requirement | Version / Details |
|---|---|
| Minecraft | 1.21 โ 26.3 |
| Server Software | Paper |
| Java | Java 21+ for Minecraft 1.21.x; Java 25 for Minecraft 26.x |
| Dependencies | None required |
| Optional Plugins | PlaceholderAPI |
Compatibility notes:
- Paper is the supported server software.
- Spigot, Purpur and Pufferfish compatibility is being tested.
- Folia is not supported.
๐ Installation Steps
- ๐ฆ Download the latest Ultimate Anti-Illegals
.jarrelease. - ๐ Place the
.jarfile inside your server'splugins/directory. - ๐ Start or restart your Paper server.
- ๐งช Recommended: Run
/antiillegal dryrun 60and monitor the log file during your initial setup. - โ๏ธ Edit
plugins/UltimateAntiIllegals/config.ymlto customize your protection settings. - ๐ Run
/antiillegal reloadto apply configuration changes. - ๐ Your server is protected!
๐ก Important Notes
- 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 during the next scan.
- Menus and backpacks from other plugins are ignored unless you enable
custom-inventories.
๐ Support & Bug Reports
Need help, found a bug or have a suggestion?
Join the GetUrPlugins Discord community!
We're happy to help!
- ๐ Bug Reports โ Report bugs and unexpected behavior.
- ๐ฌ Support โ Get help with installation and configuration.
- ๐ก Suggestions โ Share ideas for future improvements.
- ๐ข Announcements โ Stay informed about updates and releases.
โ ๏ธ When reporting an issue, please include your Minecraft version, server software and relevant error logs.
๐ Credits & License
Developed by: Berkayprof - GetUrPlugins
License: All Rights Reserved (ARR).
ยฉ GetUrPlugins. All rights reserved.
- โ Unauthorized redistribution or resale is prohibited.
- โ Modification, decompilation or republishing is prohibited without explicit permission.
- โ Usage is permitted under the conditions set by the author.
See https://gcl.onl/licenses/arr for the full license terms.


