🧙‍♂️ InventoryWizard

The magical sorting assistant for your Minecraft world! ✨

InventoryWizard is a powerful PaperMC plugin that brings intelligent, one-click inventory organization to your server. With intuitive controls and smart categorization, managing your items has never been easier!

🌟 Features

✨ Intelligent Sorting

Smart categorization - Items are grouped logically (weapons, tools, food, blocks, etc.)
Hotbar optimization - Weapons and tools prioritized for PvP/survival gameplay
Stack consolidation - Automatically combines partial stacks
Configurable partial stack sorting - Choose whether to sort only full stacks or include partial stacks (see config)
Metadata preservation - Maintains enchantments, names, and item data

🖱️ Multiple Control Methods

Shift+Right Click - Sort inventories, chests, and hotbar
Double Click - Alternative hotbar sorting
Commands - /iwiz for programmatic sorting
Shift+Right Click in Hotbar Slot 4 - Cycle through sorting modes

🎒 Comprehensive Coverage

Player Inventory - Organize your main storage
Hotbar - Optimized for quick access to combat/survival items
Chests - Keep your storage containers tidy
All-in-one - Sort everything simultaneously

📥 Installation

Download the latest InventoryWizard-x.x.x.jar from the releases page
Place the JAR file in your server's plugins folder
Restart your server
Configure the plugin using plugins/InventoryWizard/config.yml (optional)

Requirements

Minecraft: 1.21.x
Server: PaperMC, Spigot, or compatible fork
Java: 17 or higher

Database

H2 Database: Embedded, no external setup required
Storage: plugins/InventoryWizard/player_preferences.mv.db
Performance: Optimized for servers with 1-10,000+ players

🎮 Usage Guide

Control Scheme Overview

Action	Location	Permission Required	Result
Shift+Right Click	Hotbar (slots 0-8)	`inventorywizard.all`	Sort inventory + hotbar
Shift+Right Click	Hotbar (slots 0-8)	`inventorywizard.hotbar`	Sort hotbar only
Shift+Right Click	Hotbar Slot 4	`inventorywizard.use`	Cycle sorting modes
Shift+Right Click	Main Inventory (slots 9-35)	`inventorywizard.inventory`	Sort main inventory
Shift+Right Click	Chest	`inventorywizard.chest`	Sort chest contents
Double Click	Hotbar (slots 0-8)	`inventorywizard.hotbar`	Sort hotbar only

Sorting Your Inventory

Open your inventory (E)
Shift+Right Click any slot in your main inventory area (slots 9-35)
Watch the magic happen! ✨

Sorting Your Hotbar

Method 1: Shift+Right Click any hotbar slot (0-8) with inventorywizard.hotbar permission
Method 2: Double Click any hotbar slot
Method 3: Use command /iwiz hotbar

Sorting Chests

Open any chest
Shift+Right Click any slot in the chest
The entire chest will be organized!

Sorting Everything

Shift+Right Click in your hotbar (slots 0-8) with inventorywizard.all permission
Both your inventory and hotbar will be sorted!

Cycling Sorting Modes

Shift+Right Click in hotbar slot 4 (middle slot) to cycle through sorting modes
Default Mode: Smart categorization by item type
Alphabetical Mode: Sort items alphabetically by name
Stack-based Mode: Group by item type, then sort by stack size (full stacks first)
Your preferred mode is saved and remembered for future sorting!

🧙‍♂️ Commands

Command	Aliases	Description	Permission
`/iwiz`	`/inventorywizard`, `/sort`	Base command	`inventorywizard.use`
`/iwiz hotbar`	`/iwiz hb`	Sort hotbar only	`inventorywizard.hotbar`
`/iwiz inventory`	`/iwiz inv`	Sort inventory only	`inventorywizard.inventory`
`/iwiz all`	`/iwiz both`	Sort everything	`inventorywizard.all`

🔐 Permissions

Permission	Description	Default
`inventorywizard.use`	Basic plugin access	`true`
`inventorywizard.chest`	Sort chests	`true`
`inventorywizard.inventory`	Sort player inventory	`true`
`inventorywizard.hotbar`	Sort hotbar	`true`
`inventorywizard.all`	Sort everything at once	`true`

Permission Groups

# Example permissions setup
groups:
  default:
    permissions:
      - inventorywizard.use
      - inventorywizard.inventory
      - inventorywizard.hotbar
  
  vip:
    permissions:
      - inventorywizard.*  # All permissions

⚙️ Configuration

The plugin generates a config.yml file with the following options:

# InventoryWizard Configuration
settings:
  # Play magical sound effects when sorting
  play-sound: true
  
  # Sound settings for the wizard's magic
  sound:
    type: UI_BUTTON_CLICK
    volume: 0.5
    pitch: 1.2

  # Sorting method: "TYPE" for smart categorization or "ALPHABETICAL" 
  sort-method: "TYPE"

# Enable/disable magical features
features:
  chest-sorting: true
  inventory-sorting: true
  hotbar-sorting: true
  show-messages: true
  
  # Allow sorting of partial stacks in chests (set false to only sort full stacks)
  allow-partial-stacks-chest: true
  # Allow sorting of partial stacks in player inventory (set false to only sort full stacks)
  allow-partial-stacks-inventory: true

# Hotbar sorting priorities (optimized for PvP/survival)
hotbar-priorities:
  weapons: 100        # Swords, bows, crossbows first
  tools: 200          # Pickaxes, axes, shovels second  
  food: 300           # Sustenance third
  building-blocks: 400 # Quick-build materials fourth
  utility-items: 500  # Ender pearls, buckets, torches
  other: 999          # Everything else

Partial Stack Sorting Behavior

allow-partial-stacks-chest and allow-partial-stacks-inventory control whether partial stacks are included in sorting for chests and player inventory, respectively.
If set to true: All items, including partial stacks, are sorted and consolidated as much as possible.
If set to false: Only full stacks are sorted. Any leftover partial stacks are left unsorted at the end of the inventory or chest.

📋 Sorting Modes

Default Mode (Smart Categorization)

Items are sorted by logical categories:

Stone Types - Stone, granite, cobblestone, deepslate, etc.
Earth Types - Dirt, sand, gravel, clay, concrete, etc.
Wood Types - Logs, planks, leaves, saplings
Ores & Metals - Iron blocks, diamond blocks, etc.
Other Blocks - Remaining building materials
Tools - Pickaxes, axes, shovels, shears, etc.
Weapons - Swords, bows, arrows, tridents
Armor - Helmets, chestplates, boots, shields
Food - All edible items
Redstone - Redstone components and mechanisms
Transportation - Boats, minecarts, saddles
Decoration - Flowers, carpets, banners, etc.
Miscellaneous - Everything else

Alphabetical Mode

Items are sorted alphabetically by their material name (A-Z).

Stack-based Mode

Items are grouped by type first, then sorted by stack size within each type. Full stacks appear before partial stacks of the same item.

Hotbar Sorting Order (Optimized for PvP/Survival)

Weapons - Combat items for quick access
Tools - Essential survival tools
Food - Health restoration
Building Blocks - Cobblestone, dirt for quick building
Utility Items - Ender pearls, buckets, torches
Other Items - Miscellaneous

🔧 Building from Source

# Clone the repository
git clone https://github.com/VanishingTacos/inventorywizard.git
cd inventorywizard

# Build with Maven
mvn clean package

# The JAR will be in target/InventoryWizard-1.0.0.jar

Development Requirements

Java 17+
Maven 3.6+
PaperMC API 1.21.4+

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests, report bugs, or suggest features.

Fork the repository
Create a feature branch: git checkout -b feature-name
Commit your changes: git commit -am 'Add some feature'
Push to the branch: git push origin feature-name
Submit a pull request

📜 Changelog

Version 1.1.1

🛡️ Rate Limiting Added - Prevents excessive sorting to avoid server lag and abuse (configurable per player)
🗃️ H2 Database - Improved performance and secuirty for inventory data storage
🐛 Bug Fixes - Fixed rare issues with inventory sync and sorting edge cases
📚 Documentation Improvements - Expanded README and in-game help for new features

Version 1.1.0

✨ New Stack-based Sorting Mode - Group items by type, then sort by stack size (full stacks first)
- 🔄 Preserved Individual Stacks - Partial stacks maintain their original sizes without combining
📦 Alphabetical Material Grouping - Items grouped alphabetically by material name within stack-based mode
🎯 Enhanced Sorting Logic - Improved stack size sorting (largest to smallest within each material type)
🧙‍♂️ Mode Cycling - Easily switch between Default, Alphabetical, and Stack-based sorting modes

Version 1.0.1

🔧 Fixed control scheme - Removed middle click, improved Shift+Right Click logic
🎯 Enhanced hotbar sorting - Priority-based permission system for combined sorting
🛠️ Code optimization - Eliminated duplicate event handlers and improved reliability
📝 Updated documentation - Clearer instructions and permission requirements

Version 1.0.0

✨ Initial release
🧙‍♂️ Smart inventory sorting with type-based categorization
🎯 Hotbar optimization for PvP/survival gameplay
📦 Chest organization support
🖱️ Multiple control methods (click-based and commands)
🔊 Audio feedback and magical messages
⚙️ Comprehensive configuration options

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

PaperMC Team for the excellent server software
Minecraft Community for inspiration and feedback
Plugin Developers who paved the way for quality Bukkit plugins

☕ Support InventoryWizard

If you enjoy using InventoryWizard and want to support its development, you can buy me a coffee!

Made with ❤️ and ✨ for the Minecraft community

Transform your chaotic inventory into organized perfection with InventoryWizard! 🧙‍♂️

InventoryWizard