MysticalReferral

# MysticalReferral A feature-rich referral and invite reward system plugin for Minecraft Paper servers. Players can generate invite codes, share them with friends, and both parties receive configurable rewards when a code is used. --- ## Features - Invite code generation - short, unique, easy-to-share codes with click-to-copy - Reward system - fully configurable console commands for both inviter and invited player - Milestone/tier rewards - bonus rewards at configurable invite thresholds (5, 10, 25, 50, etc.) - Offline reward queue - rewards are queued and delivered when offline inviters come back online - Sound & title effects - configurable sounds and title screens on successful referrals - Referral history - players can view who they've referred and when - Leaderboard - server-wide top referrers ranking - Player stats - personal referral statistics - Admin commands - info, reset, and setcode commands for server administrators - Code expiration - optional time-limited referral codes - PlaceholderAPI support - expose referral data to scoreboards, chat, etc. - Update checker - notifies admins of new versions on login - Anti-abuse protection: - Self-referral prevention - One-time use per player - Configurable minimum playtime requirement - Optional IP address check to block alt-account abuse - MySQL storage with HikariCP connection pooling - Custom referral codes - players with permission can set their own vanity codes - Top referrer scheduled rewards - automatically rewards top N referrers on a daily/weekly schedule - Config versioning - automatic config migration when new settings are added (no manual deletion needed) - Fully configurable messages, rewards, effects, and settings --- ## Requirements - Minecraft 1. 21.x - Paper server (or forks like Purpur) - Java 21 - MySQL 8. 0+ database ### Optional Dependencies - PlaceholderAPI - for placeholder support in chat, scoreboards, etc. --- ## Installation 1. Download `MysticalReferral-1. 0. 0.jar` 2. Place the JAR in your server's `plugins/` folder 3. Start the server once to generate `config.yml` 4. Edit `plugins/MysticalReferral/config.yml` with your MySQL credentials 5. Restart the server or run `/referral reload` --- ## Building from Source ```bash git clone https://github.com/your-org/MysticalReferral.git cd MysticalReferral mvn clean package ``` The compiled JAR will be at `target/MysticalReferral-1. 0. 0.jar`. Build requirements: Java 21, Maven 3. 9+ --- ## Configuration ### Database ```yaml database: host: localhost port: 3306 name: mysticalreferral username: root password: password pool: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000 ``` Create the database beforehand: ``` CREATE DATABASE mysticalreferral; ``` ### Settings ```yaml settings: code-length: 5 min-playtime-minutes: 10 allow-ip-referrals: false leaderboard-size: 10 code-expiration-days: 0 language: en update-checker: true ``` ### Rewards Rewards are executed as console commands. Use `%player%` as a placeholder for the player's name. ```yaml rewards: inviter: commands: - "give %player% diamond 2" - "eco give %player% 500" invited: commands: - "give %player% diamond 1" - "eco give %player% 100" ``` ### Milestone Rewards ```yaml milestones: 5: commands: - "give %player% emerald 5" message: "&a&lMilestone! &eYou reached &b5 &einvites!" 10: commands: - "give %player% emerald 16" - "eco give %player% 2000" message: "&a&lMilestone! &eYou reached &b10 &einvites!" ``` ### Effects ```yaml effects: sound: enabled: true type: ENTITY_PLAYER_LEVELUP volume: 1. 0 pitch: 1. 0 title: enabled: true title: "&a&lReferral Used!" subtitle: "&7You and &e%player% &7received rewards!" inviter-title: enabled: true title: "&a&lNew Referral!" subtitle: "&e%player% &7used your code!" ``` ### Custom Referral Codes ```yaml custom-codes: enabled: true min-length: 3 max-length: 16 allowed-pattern: "^+$" force-uppercase: true ``` ### Top Referrer Scheduled Rewards ```yaml top-rewards: enabled: false interval-minutes: 1440 top-count: 3 broadcast: true positions: 1: commands: - "give %player% netherite_ingot 3" message: "#1 Top Referrer! Congrats %player%!" ``` --- ## Commands | Command | Description | Permission | |---|---|---| | `/invit