v3.0.0 - The RPG Gem System Update

SupperBackpack v3.0.0 introduces a massive overhaul to the gem system, transforming it from simple potion buffs into an engaging RPG-style ability system with crafting progression, single-active combo mechanics, and lag-free performance.

💎 Complete Gem System Overhaul

• 32 New RPG Ability Gems: Replaced old potion gems with highly specialized gems (e.g., Dash, Lifesteal, Magnet, Crafter).
• Rarity System (7 Tiers): Gems now scale from Common to Divine, with unique lore formatting, material costs, and particle effects.
• Crafting Progression: Added 32 new gem recipes. Upgrading a gem to Tier II now requires its Tier I version.

⚔️ New Active Combo Powers

• Single Active Combo Rule: You can now only have ONE combo active at a time (highest rarity combo takes priority).
• Each combo now grants a Passives + Active Ability (triggered by Sneak + Right-Click):
  • Dash (Parkour Set): Launch forward with 2s fall immunity.
  • Ore Pulse (Treasure Hunter): Highlight nearby ores behind walls for 5 seconds.
  • Blood Rage (Blood Warrior): Gain Strength II and 2x lifesteal chance for 6 seconds.
  • Water Surge (Ocean Explorer): Gain a massive dolphin-boost swimming propulsion.
  • Flame Burst (Nether Walker): Trigger a 3-block fire explosion that damages and ignites mobs.
  • Wind Lift (Sky Traveler): Automatically launch upward when squeezing sneak while falling.

🗺️ Visual & Quality of Life Improvements

• Revamped Combo GUI: /bp combos now displays required gems, active abilities, cooldowns, and a clear "ACTIVE COMBO" indicator.
• Tier 5 Backpack Removed: Streamlined tiers; Tier 4 (54 slots) is now the maximum upgrade.
• New Admin Command: Use /bpitem <gemType> to quickly obtain specific gems.

🛠️ Fixes & Technical Overhaul

• Blink Gem Fix: Blink teleportation now flawlessly ray-traces exactly where you look (including vertical angles) and ensures you only land in safe 2-block-tall air spaces.
• Magnet Gem Fix: Re-coded to strictly pull Dropped Items, preventing weird physics with XP orbs or arrows.
• Zero-Lag Event-Driven Architecture: Removed nearly all ticking tasks. The system now aggressively caches gem states per-player, updates only on inventory close/join, and uses timestamp tracking for abilities instead of Bukkit cooldowns. Everything runs instantly with zero TPS impact.

[2.1.0] - 2026-02-05

🛒 NEW: Vault Shop System

A complete item selling system integrated with Vault economy! Players can now sell items directly from their backpack.

Features Overview

• Sell GUI - Beautiful 54-slot inventory GUI to sell backpack items
• Vault Integration - Works with any Vault-compatible economy plugin
• Configurable Prices - Set prices for every item in a dedicated config file
• Enable/Disable Toggle - Server admins can completely disable the shop feature
• Safe Fallback - If Vault is not installed, the feature gracefully disables without crashes

---

💰 Compatible Economy Plugins

SupperBackpack works with any Vault-compatible economy plugin. Here are the tested and supported options:

Plugin	Type	Notes
EssentialsX	Free	Most popular, highly recommended
CMI	Premium	Feature-rich server management suite
TheNewEconomy	Free	Lightweight, multi-currency support
XConomy	Free	Multi-currency, MySQL support
iConomy	Free	Classic economy plugin
Reserve	Free	Lightweight alternative

⚠️ Important: Vault alone does NOT provide economy! You must install one of the above plugins alongside Vault.

---

📜 New Commands

Command	Aliases	Permission	Description
/backpacksell	/bpsell, /bagsell	supperbackpack.sell	Opens the sell GUI

---

🔐 New Permissions

Permission	Default	Description
supperbackpack.sell	true	Allows selling items from the backpack

---

📁 New Configuration Files

shop.yml - Dedicated Shop Configuration

A brand new configuration file specifically for the shop system:

# Enable or disable the shop feature entirely
enabled: true

# Multiplier for "Sell All" button (1.0 = normal, 0.9 = 10% less, 1.1 = 10% bonus)
sell-all-multiplier: 1.0

# Custom messages
messages:
  shop-disabled: "&cThe shop feature is disabled on this server!"
  vault-not-available: "&cEconomy is not available!"
  sold-item: "&a✓ Sold &e{amount}x {item} &afor &6{price}&a!"
  sold-all: "&a✓ Sold &e{amount} items &afor &6{price}&a!"

# Item prices (per single item)
sell-prices:
  DIAMOND: 100
  EMERALD: 75
  GOLD_INGOT: 15
  IRON_INGOT: 10
  # ... 100+ items pre-configured

---

🖥️ Sell GUI Features

The sell GUI provides a user-friendly interface:

• Size: 54 slots (6 rows)
• Display: Shows only sellable items from your backpack
• Price Info: Each item shows per-item price and stack value in lore
• Controls:
  • Left-click item: Sell that stack
  • Shift-click item: Sell ALL of that item type in backpack
  • Sell All button (Emerald Block): Sells all sellable items at once
  • Close button (Barrier): Closes the GUI
  • Info button (Book): Shows how to use the GUI

---

� Pre-Configured Sell Prices

The plugin comes with 100+ items pre-configured with balanced sell prices:

Category	Examples
Ores & Minerals	Diamond (100), Emerald (75), Gold Ingot (15), Iron Ingot (10)
Raw Ores	Raw Gold (12), Raw Iron (8), Raw Copper (3)
Ore Blocks	Diamond Block (900), Emerald Block (675), Gold Block (135)
Building Materials	Oak Log (1), Stone (0.2), Cobblestone (0.1)
Food	Cooked Beef (3), Bread (2), Golden Apple (50)
Mob Drops	Ender Pearl (15), Blaze Rod (20), Ghast Tear (50)
Nether Items	Netherite Ingot (500), Ancient Debris (150)
Rare Items	Nether Star (1000), Dragon Egg (5000), Elytra (2000)
Dyes	All 16 dye colors (1-3 each)

---

🛡️ Security Features

• Exploit Prevention: All clicks in sell GUI are cancelled
• Drag Prevention: Item dragging is completely disabled in sell GUI
• Backpack-Only: Items are read/modified ONLY via BackpackManager
• No External Access: Other plugins cannot access backpack items
• Transaction Validation: Each sale is validated before money is deposited

---

📋 Requirements

Requirement	Status	Description
Vault	Required	API bridge for economy integration
Economy Plugin	Required	EssentialsX, CMI, or any Vault-compatible plugin
Java 21	Required	Minimum Java version
Paper/Spigot 1.21+	Required	Server software

---

📋 Startup Messages

Success:

[SupperBackpack] Successfully hooked into Vault economy: Essentials Economy

Vault installed but no economy plugin:

[SupperBackpack] Vault found but no economy plugin is installed. Sell feature will be disabled.

Vault not installed:

[SupperBackpack] Vault not found. Sell feature will be disabled.

---

🔧 Technical Changes

New Files Created

• shop.yml - Dedicated shop configuration file
• ShopManager.java - Manages shop.yml loading and access
• VaultManager.java - Handles Vault economy integration
• SellGUI.java - Sell GUI creation and display
• BackpackSellCommand.java - /bpsell command handler
• SellGUIListener.java - Handles all click events in sell GUI

Modified Files

• SupperBackpack.java - Added ShopManager and VaultManager initialization
• config.yml - Removed shop settings (moved to shop.yml)
• plugin.yml - Added new command, permission, and Vault softdepend
• build.gradle - Added VaultAPI dependency from JitPack

Dependencies Added

• VaultAPI 1.7.1 (compileOnly - from JitPack)

---

🔄 Upgrade Notes

• No migration needed - This is a feature addition, not a data change
• Vault optional - The plugin works fine without Vault; only the sell feature is disabled
• Config preserved - Your existing config.yml settings are not affected
• New config - shop.yml will be created automatically on first startup

📋 Changelog

All notable changes to SupperBackpack will be documented in this file.

---

[2.0.0] - 2026-02-02

🛒 NEW: Vault Shop System

A complete item selling system integrated with Vault economy! Players can now sell items directly from their backpack.

Features Overview

• Sell GUI - Beautiful 54-slot inventory GUI to sell backpack items
• Vault Integration - Works with any Vault-compatible economy plugin (EssentialsX, CMI, etc.)
• Configurable Prices - Set prices for every item in a dedicated config file
• Enable/Disable Toggle - Server admins can completely disable the shop feature
• Safe Fallback - If Vault is not installed, the feature gracefully disables without crashes

---

📜 New Commands

Command	Aliases	Permission	Description
/backpacksell	/bpsell, /bagsell	supperbackpack.sell	Opens the sell GUI

---

🔐 New Permissions

Permission	Default	Description
supperbackpack.sell	true	Allows selling items from the backpack

---

📁 New Configuration Files

shop.yml - Dedicated Shop Configuration

A brand new configuration file specifically for the shop system:

# Enable or disable the shop feature entirely
enabled: true

# Multiplier for "Sell All" button (1.0 = normal, 0.9 = 10% less, 1.1 = 10% bonus)
sell-all-multiplier: 1.0

# Custom messages
messages:
  shop-disabled: "&cThe shop feature is disabled on this server!"
  vault-not-available: "&cEconomy is not available!"
  sold-item: "&a✓ Sold &e{amount}x {item} &afor &6{price}&a!"
  sold-all: "&a✓ Sold &e{amount} items &afor &6{price}&a!"
  # ... and more

# Item prices (per single item)
sell-prices:
  DIAMOND: 100
  EMERALD: 75
  GOLD_INGOT: 15
  IRON_INGOT: 10
  # ... 100+ items pre-configured

---

🖥️ Sell GUI Features

The sell GUI provides a user-friendly interface:

• Size: 54 slots (6 rows)
• Display: Shows only sellable items from your backpack
• Price Info: Each item shows per-item price and stack value in lore
• Controls:
  • Left-click item: Sell that stack
  • Shift-click item: Sell ALL of that item type in backpack
  • Sell All button (Emerald Block): Sells all sellable items at once
  • Close button (Barrier): Closes the GUI
  • Info button (Book): Shows how to use the GUI

---

🔧 Technical Changes

New Files Created

• shop.yml - Dedicated shop configuration file
• ShopManager.java - Manages shop.yml loading and access
• VaultManager.java - Handles Vault economy integration
• SellGUI.java - Sell GUI creation and display
• BackpackSellCommand.java - /bpsell command handler
• SellGUIListener.java - Handles all click events in sell GUI

Modified Files

• SupperBackpack.java - Added ShopManager and VaultManager initialization
• config.yml - Removed shop settings (moved to shop.yml)
• plugin.yml - Added new command, permission, and Vault softdepend
• build.gradle - Added VaultAPI dependency from JitPack

Dependencies Added

• VaultAPI 1.7.1 (compileOnly - from JitPack)

---

💰 Pre-Configured Sell Prices

The plugin comes with 100+ items pre-configured with balanced sell prices:

Category	Examples
Ores & Minerals	Diamond (100), Emerald (75), Gold Ingot (15), Iron Ingot (10)
Raw Ores	Raw Gold (12), Raw Iron (8), Raw Copper (3)
Ore Blocks	Diamond Block (900), Emerald Block (675), Gold Block (135)
Building Materials	Oak Log (1), Stone (0.2), Cobblestone (0.1)
Food	Cooked Beef (3), Bread (2), Golden Apple (50)
Mob Drops	Ender Pearl (15), Blaze Rod (20), Ghast Tear (50)
Nether Items	Netherite Ingot (500), Ancient Debris (150)
Rare Items	Nether Star (1000), Dragon Egg (5000), Elytra (2000)
Dyes	All 16 dye colors (1-3 each)

---

🛡️ Security Features

• Exploit Prevention: All clicks in sell GUI are cancelled
• Drag Prevention: Item dragging is completely disabled in sell GUI
• Backpack-Only: Items are read/modified ONLY via BackpackManager
• No External Access: Other plugins cannot access backpack items
• Transaction Validation: Each sale is validated before money is deposited

---

📋 Startup Messages

The plugin now logs shop status on startup:

[SupperBackpack] Shop feature enabled with Vault economy.

Or if Vault is not found:

[SupperBackpack] Shop feature enabled but Vault not found. Shop commands will show error.

Or if disabled in config:

[SupperBackpack] Shop feature is disabled in shop.yml.

---

🔄 Upgrade Notes

• No migration needed - This is a feature addition, not a data change
• Vault optional - The plugin works fine without Vault; only the sell feature is disabled
• Config preserved - Your existing config.yml settings are not affected
• New config - shop.yml will be created automatically on first startup

📋 Changelog

All notable changes to SupperBackpack will be documented in this file.

---

[1.3.0] - 2026-01-16

🐛 Bug Fixes

Fixed Gem Effect Levels

• Critical Fix: Level 1 gems were incorrectly giving Level 2 effects
• All ability gems now properly apply the correct effect level:
  • Level I gems → Effect amplifier 0 (Level I)
  • Level II gems → Effect amplifier 1 (Level II)
• Affected gems: Speed, Jump, Strength, Health, Resistance, and Haste

✨ New Features

bStats Integration

• Added bStats metrics for plugin usage tracking

📝 Technical Details

• Added getAbilityLevel() method to CustomItems.java and SpecialItemManager.java
• Modified BuffManager.applyBuff() to accept level parameter
• Uses Gradle Shadow plugin to bundle bStats dependency

---

[1.2.0] - 2026-01-01

🗄️ Database Storage Migration

Major Change: Player data storage has been migrated from individual YAML files to a single SQLite database for improved performance and reliability.

What's New

• Single Database File: All player data is now stored in backpacks.db instead of individual YAML files per player
• Automatic Migration: Existing YAML files in player_storage_db/ are automatically migrated to the database on first startup
• Better Performance: SQLite provides faster read/write operations, especially for servers with many players
• More Reliable: Reduces risk of data corruption from improper YAML formatting

Migration Process

1. On first startup with v1.2.0, the plugin scans for existing YAML files
2. All player data (tier, items) is migrated to backpacks.db
3. Original YAML files are moved to player_storage_db/migrated/ for backup
4. No manual intervention required!

📝 Technical Details

• New DatabaseManager.java class handles all SQLite operations
• Uses Base64 encoding for ItemStack serialization (BukkitObjectOutputStream)
• Username-based storage: Players are identified by username (case-insensitive), not UUID
• Database schema: players table (username, tier, last_used) and backpack_items table (username, slot, item_data)
• Thread-safe database operations

🐛 Bug Fixes

Fixed Upgrade Gem Crafting Recipe

• Fixed issue where Upgrade Gem Tier 3 could not be used to craft Upgrade Gem Tier 4
• Added CustomModelData identifiers (1001-1004) to upgrade gems for reliable recipe matching
• Removed duplicate recipe entries in recipes.yml that could cause conflicts

🔄 Upgrade Notes

• Automatic migration: Just replace the JAR file and restart
• Backup recommended: While migration is automatic, backing up your player_storage_db/ folder is recommended
• Original files preserved: Migrated YAML files are moved to migrated/ folder, not deleted

📋 Changelog

All notable changes to SupperBackpack will be documented in this file.

---

[1.2.0] - 2026-01-01

🗄️ Database Storage Migration

Major Change: Player data storage has been migrated from individual YAML files to a single SQLite database for improved performance and reliability.

What's New

• Single Database File: All player data is now stored in backpacks.db instead of individual YAML files per player
• Automatic Migration: Existing YAML files in player_storage_db/ are automatically migrated to the database on first startup
• Better Performance: SQLite provides faster read/write operations, especially for servers with many players
• More Reliable: Reduces risk of data corruption from improper YAML formatting

Migration Process

1. On first startup with v1.2.0, the plugin scans for existing YAML files
2. All player data (tier, items) is migrated to backpacks.db
3. Original YAML files are moved to player_storage_db/migrated/ for backup
4. No manual intervention required!

📝 Technical Details

• New DatabaseManager.java class handles all SQLite operations
• Uses Base64 encoding for ItemStack serialization (BukkitObjectOutputStream)
• Username-based storage: Players are identified by username (case-insensitive), not UUID
• Database schema: players table (username, tier, last_used) and backpack_items table (username, slot, item_data)
• Thread-safe database operations

🐛 Bug Fixes

Fixed Upgrade Gem Crafting Recipe

• Fixed issue where Upgrade Gem Tier 3 could not be used to craft Upgrade Gem Tier 4
• Added CustomModelData identifiers (1001-1004) to upgrade gems for reliable recipe matching
• Removed duplicate recipe entries in recipes.yml that could cause conflicts

🔄 Upgrade Notes

• Automatic migration: Just replace the JAR file and restart
• Backup recommended: While migration is automatic, backing up your player_storage_db/ folder is recommended
• Original files preserved: Migrated YAML files are moved to migrated/ folder, not deleted