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

📋 Changelog

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

---

[1.1.0] - 2025-12-29

🐛 Bug Fixes

Fixed Missing Buff Types

Resolved an issue where certain special ability crystals were not applying their effects when placed in backpack special slots.

Previously broken crystals:

• ⛏️ Haste Crystal I & II - Mining speed boost was not working
• 👁️ Vision Crystal - Night vision was not working
• 💖 Healing Crystal - Regeneration was not working
• 🍀 Lucky Crystal - Luck effect was not working

Players would see Unknown buff type: HASTE warnings in console every second. These crystals now work correctly!

✨ Working Buff Effects

Crystal	Effect	Level	Duration
Haste Crystal I/II	Mining Speed Boost	II	Permanent while equipped
Vision Crystal	Night Vision	I	Permanent while equipped
Healing Crystal	Health Regeneration	I	Permanent while equipped
Lucky Crystal	Better Loot Drops	I	Permanent while equipped

📝 Technical Details

• Added HASTE case to BuffManager.applyBuff() → PotionEffectType.HASTE
• Added NIGHT_VISION case → PotionEffectType.NIGHT_VISION (20s duration to prevent flickering)
• Added REGENERATION case → PotionEffectType.REGENERATION
• Added LUCK case → PotionEffectType.LUCK

🔄 Upgrade Notes

• No data migration required - Just replace the JAR file
• All existing player backpacks and settings are preserved
• Fully compatible with existing config.yml and recipes.yml

---

[1.0.0] - Initial Release

✨ Features

• Tiered Backpack System (Tier 1-5)

  • Tier 1: 9 slots
  • Tier 2: 18 slots + 2 special slots
  • Tier 3: 27 slots + 3 special slots
  • Tier 4: 54 slots + 6 special slots
  • Tier 5: Super Backpack with all features

• Special Ability Crystals

  • Speed Crystal I/II
  • Jump Crystal I/II
  • Strength Crystal I/II
  • Health Crystal I/II
  • Resistance Crystal I/II
  • Fire Resistance Crystal
  • Water Breathing Crystal
  • Conduit Power Crystal
  • Saturation Crystal (Legendary)
  • Crafting Gem (Legendary)

• Upgrade Gems

  • Upgrade Gem Tier I-IV for progression

• Custom Crafting Recipes

  • View recipes with /bprecipe
  • Configurable in recipes.yml

• Death Chest System

  • Backpack contents preserved on death

• Commands

  • /bp - Open backpack
  • /bp reload - Reload config
  • /bp craft - Portable crafting (with Crafting Gem)
  • /bpupgrade - View/upgrade backpack tier
  • /bpitem - Get special items (OP)
  • /bprecipe - View crafting recipes

---

📦 Installation

1. Stop your server
2. Place SupperBackpack-x.x.x.jar in your plugins/ folder
3. Start your server
4. Configure in plugins/SupperBackpack/config.yml

---

🔗 Links

• Modrinth: [Your Modrinth Link]
• GitHub: [Your GitHub Link]
• Discord: [Your Discord Link]

---

Made with ❤️ by younggamingdj

✨ Key Features

📦 Tiered Backpack System

• 5 Tiers of backpacks with increasing storage capacity
• Start with 9 slots (Tier 1) and upgrade up to 54 slots (Tier 5)
• Upgradeable using special Upgrade Gems crafted in-game
• Persistent storage - your items are saved even when you log off

💎 Special Ability Slots

• Unlock special slots starting from Tier 2
• Place Ability Gems in special slots to gain permanent buffs
• Visual markers with glowing purple glass panes show available special slots
• Restricted slots - only ability items can be placed in special slots

⚡ Powerful Ability Gems

Craft and equip various ability gems for permanent effects:

Movement Abilities:

• Speed Boost (I & II) - Move faster
• Jump Boost (I & II) - Jump higher

Combat Abilities:

• Strength (I & II) - Deal more damage
• Health Boost (I & II) - Increase max health
• Resistance (I & II) - Take less damage
• Regeneration - Slowly heal over time

Utility Abilities:

• Night Vision - See in the dark
• Haste (I & II) - Mine faster
• Luck - Better loot drops
• Crafting Gem - Portable crafting table with /bp craft

Environmental Abilities:

• Fire Resistance - Immunity to fire and lava
• Water Breathing - Breathe underwater
• Conduit Power - Enhanced underwater abilities
• Saturation - Never get hungry

🎮 User-Friendly Commands

• /bp - Open your backpack
• /bp help - Show command help
• /bp recipe [item] - View crafting recipes in a beautiful GUI
• /bp craft - Open portable crafting table (requires Crafting Gem)
• /bp reload - Reload configuration (OP only)

💀 Death Protection

• When you die, your backpack items are automatically stored in chests at your death location
• Two separate chests spawn to hold all items (up to 54 slots)
• Items are protected from despawning - no losing your valuable items!
• Clear location notifications show exactly where your chests are

🎨 Beautiful GUI System

• Interactive Recipe Viewer - Browse all crafting recipes with a sleek GUI
• Formatted displays with item icons and clear ingredient lists
• Search functionality - Find recipes by name
• Tab completion for all commands

⚙️ Highly Customizable

• Configure tier sizes, names, and upgrade requirements
• Customize all messages and colors
• Add/modify crafting recipes via YAML files
• Adjustable cooldowns and permissions
• Full permissions system for fine-grained control

🚀 Quick Start

• Install the plugin on your Spigot/Paper server
• Start playing - every player gets a Tier 1 backpack automatically
• Open your backpack with /bp
• View recipes with /bp recipe to see how to craft upgrade gems
• Upgrade your backpack by using Upgrade Gems
• Equip abilities by placing ability gems in the special slots (purple glass panes)