ItemScannerPro Plugin Introduction Document

I. Plugin Overview

ItemScannerPro is a security plugin developed for Minecraft Bukkit/Spigot/Paper/Purpur servers. Its core function is to automatically detect and handle prohibited items and illegal enchantments (including ultra-high-level enchantments) carried by players. It supports flexible configuration rules (whitelist/blacklist, scan trigger timing, cooldown mechanism, etc.), and provides auxiliary functions such as violation statistics and administrator notifications, helping server administrators maintain in-game item security and order.

Where can I use ItemScannerPro?

II. Core Features

1. Multi-scenario Automatic Scanning

   • Automatically scan inventory + ender chest when players join the server (configurable);
   • Real-time scanning when players open backpacks or switch items;
   • Scan all items in the container when players open any backpack/container;
   • Support manual trigger scanning (admin/player-initiated scanning).

2. Prohibited Content Control

   • Support configuring a list of prohibited items for automatic detection and handling;
   • Support configuring a list of prohibited enchantments to detect and handle items with prohibited enchantments;
   • Detect ultra-high-level enchantments (default level cap: 10), items exceeding the cap will be deemed illegal;
   • Item whitelist mechanism: items in the whitelist are not restricted by scanning rules;
   • Player blacklist mechanism: blacklisted players are prohibited from carrying any items (inventory will be cleared directly).

3. Flexible Handling Rules

   • Safe Mode: Only send reminders without deleting items when enabled; automatically clear prohibited items when disabled;
   • Scan cooldown mechanism: Avoid high-frequency scanning from occupying server resources (default 5-second cooldown);
   • Permission bypass: Players with specific permissions are exempt from scanning rules.

4. Logs & Notifications

   • Automatically record violations to the console (configurable);
   • Online administrators receive real-time violation notifications (notification format configurable);
   • Violating players receive custom warning messages.

5. Statistics & Management Tools

   • Record the number of player violations, item violations, and enchantment violations;
   • Support commands for config reloading, player whitelist/blacklist management, manual scanning of specified players, etc.

III. Installation & Initialization

1. Installation Steps

1. Place ItemScannerPro.jar into the server's plugins folder;
2. Start the server, the plugin will automatically generate the default configuration file (plugins/ItemScannerPro/config.yml);
3. Stop the server and edit the configuration file as needed;
4. Restart the server (or use /isp-reload to reload config) to activate the plugin.

2. Environment Requirements

• Support Minecraft 1.17+ (compatible with Bukkit/Spigot/Paper/Purpur servers);

IV. Commands & Permissions

1. Core Commands

Command Format	Function Description	Required Permission
/isp-reload	Reload plugin config (no server restart required)	itemscannerpro.admin
/isp-scan	Scan own inventory + ender chest	None (player-only)
/isp-scan <PlayerName>	Scan inventory + ender chest of a specified online player	itemscannerpro.admin
/isp-stats	View server violation statistics (player/item/enchantment)	itemscannerpro.admin
/isp-blacklist add <PlayerName>	Add specified player to blacklist	itemscannerpro.admin
/isp-blacklist remove <PlayerName>	Remove specified player from blacklist	itemscannerpro.admin

2. Permission Nodes

Permission Node	Function Description
itemscannerpro.bypass	Exempt from all scanning rules (players with this permission won't be detected/handled for carrying prohibited items)
itemscannerpro.admin	Use admin commands (reload, statistics, whitelist/blacklist, scan other players)

V. Configuration File Details

The plugin config file config.yml contains the following core configurations, all supporting hot reload via /isp-reload:

# Safe Mode: true=only remind without deleting items; false=auto clear prohibited items
safe-mode: true

# Whether to scan ender chest (takes effect when player joins/manual scan)
scan-ender-chest: true

# Auto-scan when player joins the server
scan-on-join: true

# Real-time scan when player opens backpack/switches items
scan-on-click: true

# Output violation logs to console
log-to-console: true

# Notify online admins (admins need itemscannerpro.admin permission)
notify-admins: true

# Scan cooldown (milliseconds) to avoid high-frequency scanning
scan-cooldown: 5000

# Warning message for violating players (supports & color codes)
warning-message: "§cProhibited items detected, automatically cleared!"

# Admin notification format (%player%=player name, %item%=prohibited item)
admin-notification-format: "§8[&6ItemScannerPro&8] §cPlayer %player% is carrying prohibited item: %item%"

# Prohibited items list (fill in uppercase Material names)
banned-items:

# Prohibited enchantments list (fill in lowercase enchantment namespaces)
banned-enchants:

# Item whitelist (not restricted by scanning rules)
whitelist-items:

Configuration Notes

1. Item Names: Must use official Minecraft Material constant names (uppercase, e.g., DIAMOND_SWORD); incorrect names will be prompted in the console;
2. Enchantment Names: Must use enchantment namespaces (lowercase, e.g., sharpness, unbreaking); incorrect enchantments will be prompted in the console;
3. Color Codes: All message configurations support color codes with & replaced by § (e.g., &6=gold, &c=red).

VI. FAQs

1. Configured items/enchantments not taking effect

   • Check if item/enchantment names in the config file are correct (case-sensitive);
   • Execute /isp-reload to reload config after modification;
   • Confirm the target player does not have the itemscannerpro.bypass exemption permission.

2. Ender chest scanning not working

   • Confirm scan-ender-chest is set to true;
   • Ender chest is only scanned when players join or manual scan is triggered; only current containers are scanned when opening backpacks.

3. Blacklisted players still able to carry items

   • Confirm the blacklist operation took effect (console shows success prompt after executing /isp-blacklist add <PlayerName>);
   • Blacklisted players' inventory will only be cleared when scanning is triggered (e.g., opening backpack, joining server).

VII. Plugin Lifecycle

• Activation: The plugin automatically loads config and registers events/commands on startup; the console outputs success message (including version, number of prohibited items, etc.);
• Operation: Real-time monitoring of player behaviors, scanning/handling items according to configured rules;
• Deactivation: When the server stops, the plugin outputs uninstallation prompt and clears temporary cache (e.g., scan cooldown records).

VIII. Disclaimer

1. This plugin only detects and handles items/enchantments, and must be used with the server permission system;
2. Configuration errors (e.g., incorrect whitelist/blacklist settings) may cause functional abnormalities; it is recommended to test after modifying the config;
3. The default cap for ultra-high-level enchantment detection is level 10; to adjust it, modify the MAX_ENCHANT_LEVEL constant in the config and restart or reload the plugin.