📦 TCrates — The Next-Generation Reward Engine

---

⚡ What is TCrates?

Most crate plugins in Minecraft were designed almost a decade ago — heavy on the main server thread, bloated with obsolete libraries, lacking player-retention mechanics, and using outdated formatting.

TCrates is a completely modern, high-performance reward and crate engine designed from the ground up for modern Paper and Purpur servers (1.21+). Built with zero-lag asynchronous architectures, production-grade connection pooling, and modern Adventure MiniMessage text, it transforms ordinary crate opening into an addictive, fair, and engaging gamified experience.

---

✨ Key Features & Game Mechanics

🎯 1. Fair Gacha & Pity System (Guaranteed Rewards)

No more endless bad-luck streaks for your players:

• Dynamic Pity Counters: Automatically guarantees higher-tier rewards after a configurable number of non-rare rolls.
• Transparent Drop Odds: Players can see their exact calculated percentage chance for every reward in real-time.
• Duplicate Protection: Automatically detects if a player already owns an exclusive reward and converts duplicates into shards, in-game currency, or consolation keys.

🔮 2. Shards & Alchemy Fusion

Give worthless drops real purpose:

• Unwanted or low-tier crate rewards can grant or be dismantled into Shards (COMMON, UNCOMMON, RARE, EPIC, LEGENDARY).
• Interactive Alchemy GUI (/tcrates shards) lets players fuse 10 lower-tier shards into 1 higher-tier shard, creating a satisfying long-term progression path.

🎰 3. Progressive Community Jackpots

• Every crate opened contributes a small portion to a global, server-wide Jackpot Pool.
• When a lucky player hits the jackpot, the server celebrates with broadcast announcements, particle effects, and customizable jackpot payouts.

📜 4. Interactive Crate Missions & Milestones

• Daily and weekly opening quests (e.g., "Open 5 Starter Crates" or "Fuse 3 Rare Shards").
• Players track their progress through clean progress bars in the GUI (/tcrates missions) and claim exclusive rewards.

📬 5. Offline & Overflow Mailbox

• Players will never lose crate rewards due to a full inventory or sudden disconnects.
• Undelivered items are automatically routed to their personal secure Virtual Mailbox (/tcrates mailbox), accessible anytime.

👁️ 6. Instant Left-Click Rewards Preview

• Players can Left-Click any physical crate block in the world to open an interactive, multi-page rewards preview showing item lore, rarity tiers, and exact win percentages.
• Right-Click consumes a key and launches the opening animation.

🧪 7. Monte Carlo Simulation Engine (For Admins)

• Never guess whether your crate drop rates will break your economy!
• Admins can simulate 1,000 to 100,000 rolls in milliseconds directly from the console:

  /tcrates simulate starter 10000
  

  Provides instant distribution stats, standard deviation, and payout balance verification.

⚡ 8. Modern Visuals & Zero-Lag Architecture

• MiniMessage Gradients: Crisp, high-contrast, modern gradient typography with zero unwanted vanilla italics.
• Asynchronous Database: Powered by HikariCP with non-blocking SQLite and MySQL support.
• Featherweight Footprint: Ultra-optimized JAR (< 550 KB) without unneeded shaded dependencies.

---

🎮 How to Setup in 60 Seconds

1. Drop into plugins/ and start your Paper 1.21+ server.
2. Place any block in the world (e.g., Ender Chest, Chest, or Beacon).
3. Look directly at the block and register it as a crate:

   /tcrates create starter
   

4. Give yourself a key to test:

   /tcrates key starter
   

5. Left-Click the crate to preview rewards, or Right-Click with the key to open!

---

📋 Commands Reference

Command	Permission	Description
/tcrates preview <crate>	tcrates.player	Opens the rewards preview GUI.
/tcrates open <crate>	tcrates.player	Virtually opens a crate using available keys.
/tcrates bulkopen <crate> <amount>	tcrates.player	Bulk opens multiple crates in a single instant click.
/tcrates shards	tcrates.player	Opens the Shard Alchemy & Fusion GUI.
/tcrates missions	tcrates.player	Opens the Crate Missions & Milestones menu.
/tcrates jackpot	tcrates.player	Displays the current server jackpot pool & history.
/tcrates mailbox	tcrates.player	Opens your pending reward mailbox.
/tcrates pity [crate]	tcrates.player	Checks current rolls until guaranteed pity reward.
/tcrates collection [crate]	tcrates.player	Opens your unlocked rewards collector album.
/tcrates history	tcrates.player	Displays your personal opening history log.
/tcrates create <crate>	tcrates.admin	Links the targeted block to a crate.
/tcrates remove	tcrates.admin	Unregisters the targeted physical crate block.
/tcrates givekey <player> <crate> [qty] [phys/virt]	tcrates.admin	Gives physical or virtual keys to a player.
/tcrates luck boost <player> <multiplier> <seconds>	tcrates.admin	Grants a temporary luck multiplier to a player.
/tcrates simulate <crate> <iterations>	tcrates.admin	Runs a Monte Carlo economic balance simulation.
/tcrates backup	tcrates.admin	Creates an instant hot-backup of the database.
/tcrates reload	tcrates.admin	Hot-reloads all configs, crates, and rarities.

---

🔑 Permissions

• tcrates.player — Grants access to all core player commands, GUIs, and crate interactions (Default: true).
• tcrates.admin — Grants full administrative access to creation, editing, simulation, key giving, and reloads (Default: op).

---

📊 PlaceholderAPI Placeholders

Placeholder	Description
%tcrates_keys_<crate>%	Total keys (virtual + inventory) for a crate.
%tcrates_virtual_keys_<crate>%	Virtual keys stored in player account.
%tcrates_pity_<crate>%	Current rolls accumulated towards pity.
%tcrates_jackpot%	Current progressive jackpot pool amount.
%tcrates_shards_<tier>%	Player balance for a specific shard tier.
%tcrates_opened_total%	Total lifetime crates opened by the player.
%tcrates_luck_multiplier%	Active temporary luck multiplier (e.g. 1.5x).

---

⚙️ Configuration Preview

Crates are cleanly defined in plugins/TCrates/crates/*.yml. Adding rewards and configuring pity is dead simple:

id: "starter"
name: "<gradient:#55ffff:#00aaff><bold>STARTER CRATE</bold></gradient>"
description: "A well-balanced starter crate for new adventurers."

key:
  name: "<aqua><bold>Starter Key</bold></aqua>"
  material: "TRIPWIRE_HOOK"
  glowing: true

pity:
  enabled: true
  threshold: 15
  guaranteed-rarity: "RARE"

rewards:
  - id: "god_sword"
    rarity: "LEGENDARY"
    weight: 5
    item:
      material: "DIAMOND_SWORD"
      name: "<gradient:#ffaa00:#ff5500><bold>Excalibur</bold></gradient>"
    commands:
      - "broadcast <gold><player></gold> found <yellow>Excalibur</yellow>!"

---

🛠️ Requirements & Compatibility

• Server Software: Paper, Purpur, or compatible forks.
• Minecraft Version: 1.21.x (Supports 1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4).
• Java Version: Java 21 or higher.
• Optional Hooks: PlaceholderAPI, Vault (for economy/currency duplicate conversions).