HopperSort

# HopperSort — Smart Chest Auto-Deposit & Filter (Paper/Spigot 1.21+)


> **HopperSort** is a modern, lightweight, lag-free chest auto-sorting plugin for Paper and Spigot 1.21+.
> Tired of sorting chests manually? Just open your chest — matching items from your inventory are automatically deposited in a fraction of a second!

---

## ✨ Features

- ⚡ **Instant Auto-Deposit**: Automatically transfers matching items from player inventory to chest on open without latency or GUI desync.
- ️ **Item Frame Filter**: Simply attach an Item Frame to the chest (or on the wall directly above it) and insert a filter item.
- **Universal Item Support**: Works with **every single item** in Minecraft 1.21+ (diamonds, netherite, blocks, farm crops, mob drops, custom items).
- **Custom 3x3 Recipe**: Craft special `Hopper Tool` with enchantment glint.
- **Gradient & SmallCaps Styling**:
- `/hs lamdep`: Toggle gorgeous RGB gradient colors powered by Adventure MiniMessage.
- `/hs fontsmall`: Toggle clean, aesthetic SmallCaps typography.
- ️ **100% Anti-Dupe Protection**: Atomic matrix deduction, ghost-result auto-clearing, and rapid-open debounce protection.
- **Multi-Container Support**: Single Chests, Double Chests (both halves scanned), Barrels, and Shulker Boxes.
- **Visual & Audio Feedback**: Sound effects, Happy Villager particles, and customizable Action Bar notifications.

---

## ️ How It Works (3 Easy Steps)

1. **Attach an Item Frame** to the front or top of a chest (or on the wall block directly above the chest).
2. **Place a filter item** into the frame:
- Insert a crafted **Hopper Tool**, **OR**
- Place **any regular item directly** (e.g., Raw Iron, Diamond, Cobblestone).
- An instant chat and Action Bar confirmation will pop up!
3. **Open the chest**: All matching items from your inventory (hotbar + storage) are automatically stored into the chest!

---

## Crafting Recipe (3x3 Table)

| Slot | Ingredient |
| :--- | :--- |
| **Corners (1, 3, 7, 9)** | Redstone Dust |
| **Sides (2, 4, 6, 8)** | Hopper |
| **Center (5)** | Any Target Item (e.g., Diamond) |

> ➔ **Result:** `[Item Name] Hopper Tool` *(Glowing enchanted item)*

---

## Commands & Permissions

| Command | Description | Permission | Default |
| :--- | :--- | :--- | :--- |
| `/hs help` | Displays the help menu & recipe guide | `hoppersort.use` | Everyone (`true`) |
| `/hs lamdep` | Toggles dynamic RGB Gradient color mode | `hoppersort.use` | Everyone (`true`) |
| `/hs fontsmall` | Toggles modern SmallCaps font style | `hoppersort.use` | Everyone (`true`) |
| `/hs get <item>` | Gives a specific Hopper Tool instantly | `hoppersort.admin` | OP only |
| `/hs reload` | Reloads `config.yml` | `hoppersort.admin` | OP only |

**Aliases:** `/hs`, `/hoppersort`, `/hoppertool`

---

## ⚙️ Configuration (`config.yml`)

```yaml
settings:
enable-sounds: true
deposit-sound: "ENTITY_ITEM_PICKUP"
activate-sound: "ENTITY_PLAYER_LEVELUP"
enable-deposit-message: true
enable-gradient: true
enable-smallcaps: true

messages:
prefix: "<gradient:#00e5ff:#1de9b6>[ʜᴏᴘᴘᴇʀsᴏʀᴛ]</gradient> "
filter-activated: "<gradient:#00e5ff:#1de9b6>đã ᴋíᴄʜ ʜᴏạᴛ ʙộ ʟọᴄ ᴄấᴛ đồ ᴛự độɴɢ!</gradient>"
filter-item: "<gradient:#ffe259:#ffa751>ᴠậᴛ ᴘʜẩᴍ đượᴄ ʟọᴄ: {item}</gradient>"
filter-removed: "<gradient:#ff416c:#ff4b2b>đã ɢỡ ʙỏ ʙộ ʟọᴄ: {item}</gradient>"
filter-warn-not-chest: "<gradient:#f7971e:#ffd200>ᴋʜᴜɴɢ ɴàʏ ᴄʜưᴀ đượᴄ ɢắɴ ᴛʀên ʀươɴɢ/ᴛʜùɴɢ ᴄʜứᴀ để ᴛự độɴɢ ᴄấᴛ đồ!</gradient>"
deposit-success: "<gradient:#00e5ff:#1de9b6>đã ᴛự độɴɢ ᴄấᴛ: {details} ᴠàᴏ ʀươɴɢ!</gradient>"
deposit-actionbar: "<gradient:#00e5ff:#1de9b6>✔ đã ᴛự độɴɢ ᴄấᴛ {amount} ᴠậᴛ ᴘʜẩᴍ ᴠàᴏ ʀươɴɢ!</gradient>"
actionbar-activated: "<gradient:#00e5ff:#1de9b6>✔ đã ᴋíᴄʜ ʜᴏạᴛ ʙộ ʟọᴄ: {item}</gradient>"
actionbar-removed: "<gradient:#ff416c:#ff4b2b>✖ đã ɢỡ ʙỏ ʙộ ʟọᴄ: {item}</gradient>"
craft-success: "<gradient:#00e5ff:#1de9b6>ʙạɴ đã ᴄʜế ᴛạᴏ ᴛʜàɴʜ ᴄôɴɢ: {item}</gradient>"
craft-success-amount: "<gradient:#00e5ff:#1de9b6>ʙạɴ đã ᴄʜế ᴛạᴏ ᴛʜàɴʜ ᴄôɴɢ: {item} (x{amount})</gradient>"
mode-gradient-enabled: "<gradient:#00e5ff:#1de9b6>✔ đã ᴋíᴄʜ ʜᴏạᴛ ᴄʜế độ ᴍàᴜ ɢʀᴀᴅɪᴇɴᴛ (ʟàᴍ đẹᴘ) ᴄʜᴏ ᴛᴏàɴ ʙộ ʜệ ᴛʜốɴɢ!</gradient>"
mode-gradient-disabled: "<gradient:#ff416c:#ff4b2b>✖ đã ᴛắᴛ ᴄʜế độ ᴍàᴜ ɢʀᴀᴅɪᴇɴᴛ!</gradient>"
mode-smallcaps-enabled: "<gradient:#00e5ff:#1de9b6>✔ đã ᴄʜᴜʏểɴ ᴛᴏàɴ ʙộ ᴠăɴ ʙảɴ ʜɪểɴ ᴛʜị sᴀɴɢ ғᴏɴᴛ sᴍᴀʟʟᴄᴀᴘs!</gradient>"
mode-smallcaps-disabled: "<gradient:#ff416c:#ff4b2b>✖ đã ᴛắᴛ ᴄʜế độ ғᴏɴᴛ sᴍᴀʟʟᴄᴀᴘs!</gradient>"
no-permission: "<gradient:#ff416c:#ff4b2b>ʙạɴ ᴋʜôɴɢ ᴄó ǫᴜʏềɴ sử ᴅụɴɢ ʟệɴʜ ɴàʏ!</gradient>"
reload-success: "<gradient:#00e5ff:#1de9b6>đã ᴛảɪ ʟạɪ ᴄấᴜ ʜìɴʜ ᴛʜàɴʜ ᴄôɴɢ!</gradient>"
not-in-game: "<gradient:#ff416c:#ff4b2b>ʟệɴʜ ɴàʏ ᴄʜỉ ᴅùɴɢ ᴛʀᴏɴɢ ɢᴀᴍᴇ!</gradient>"
item-not-found: "<gradient:#ff416c:#ff4b2b>ᴋʜôɴɢ ᴛìᴍ ᴛʜấʏ ᴠậᴛ ᴘʜẩᴍ: {item}</gradient>"