RedeemMaster

RedeemMaster is a lightweight, dependency-free referral and milestone reward framework built for Minecraft 1.21+ networks running Paper, Purpur, or Spigot.

Instead of hard-coding economy or crate plugin APIs, RedeemMaster executes configurable console commands using placeholder tokens (<player>, <owner>, <count>). This lets you trigger rewards across any economy, token, or crate plugin (Vault, EssentialsX, PlayerPoints, ExcellentCrates) without needing additional soft-dependencies.

---

⚡ Key Features

• Zero External Dependencies: Native JVM execution that dispatches rewards directly via server console commands.
• Dual-Layer Anti-Alt Protection:
  • IP / Subnet Lock: Prevents players on the same network or IP from claiming each other's referral codes.
  • Playtime Requirement Gate: Validates active gameplay time using native statistics (PLAY_ONE_MINUTE) before allowing code redemptions.
• Flexible Reward Engine:
  • Referee Rewards: Starter packages given to the newcomer upon code usage.
  • Linear Owner Rewards: Fixed payouts given to the code owner for every referral.
  • Milestone Rewards: Supports both cyclic triggers (EVERY_X, e.g., every 5th invite) and one-time static milestones (EXACT, e.g., 25th invite).
• High-Performance Caching: Uses inverted UUID hash maps for O(1) runtime code lookups backed by simple flat-file YAML storage (invite.yml).
• Geyser & Floodgate Support: Compatible with Bedrock player prefixes (e.g., .PlayerName) and offline UUID tracking.

---

📜 Commands & Permissions

Root Command: /redeemmaster
Aliases: /redeem, /code, /ref

Command	Permission	Description
/redeem <code>	redeemmaster.use	Redeems an active referral code for starter bonuses.
/redeem create [code]	redeemmaster.use	Generates a custom alphanumeric code (3–12 chars) or a random 6-character code.
/redeem info <player>	redeemmaster.admin	Inspects player referral stats, creator IP, and referral counts.
/redeem revoke <player>	redeemmaster.admin	Deactivates an active referral code.
/redeem reactivate <player>	redeemmaster.admin	Re-enables a revoked referral code.
/redeem verify <player> [qty]	redeemmaster.admin	Force-verifies pending referrals and triggers milestone checks.
/redeem reload	redeemmaster.admin	Hot-reloads configuration files and memory caches.

---

⚙️ Configuration Example

settings:
  anti-alt:
    prevent-same-ip: true
    min-playtime-minutes: 15

  referee-rewards:
    - "[console]eco give <player> 5000"
    - "[console]crates key give <player> starter 1"

  owner-per-referral-rewards:
    - "[console]points give <owner> 1"

  owner-milestones:
    5:
      type: "EVERY_X" # Triggers at 5, 10, 15, 20...
      commands:
        - "[console]crates key give <owner> rare 1"
        - "[console]broadcast &a[RedeemMaster] &e<owner> &7reached &b<count> &7referrals and earned a &6Rare Key&7!"
    25:
      type: "EXACT"   # One-time grand bonus at 25 referrals
      commands:
        - "[console]points give <owner> 25"
        - "[console]crates key give <owner> legendary 1"