📦 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

🔑 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

⚙️ 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).