# MysticalReferral<\/p>\n
A feature-rich referral and invite reward system plugin for Minecraft Paper servers.<\/p>\n
Players can generate invite codes, share them with friends, and both parties receive configurable rewards when a code is used.<\/p>\n
—<\/p>\n
## Features<\/p>\n
– **Invite code generation** – short, unique, easy-to-share codes with click-to-copy
\n – **Reward system** – fully configurable console commands for both inviter and invited player
\n – **Milestone\/tier rewards** – bonus rewards at configurable invite thresholds (5, 10, 25, 50, etc.)
\n – **Offline reward queue** – rewards are queued and delivered when offline inviters come back online
\n – **Sound & title effects** – configurable sounds and title screens on successful referrals
\n – **Referral history** – players can view who they’ve referred and when
\n – **Leaderboard** – server-wide top referrers ranking
\n – **Player stats** – personal referral statistics
\n – **Admin commands** – info, reset, and setcode commands for server administrators
\n – **Code expiration** – optional time-limited referral codes
\n – **PlaceholderAPI support** – expose referral data to scoreboards, chat, etc.
\n – **Update checker** – notifies admins of new versions on login
\n – **Anti-abuse protection:**
\n – Self-referral prevention
\n – One-time use per player
\n – Configurable minimum playtime requirement
\n – Optional IP address check to block alt-account abuse
\n – **MySQL storage** with HikariCP connection pooling
\n – **Custom referral codes** – players with permission can set their own vanity codes
\n – **Top referrer scheduled rewards** – automatically rewards top N referrers on a daily\/weekly schedule
\n – **Config versioning** – automatic config migration when new settings are added (no manual deletion needed)
\n – **Fully configurable** messages, rewards, effects, and settings<\/p>\n
—<\/p>\n
## Requirements<\/p>\n
– Minecraft **1.21.x**
\n – **Paper** server (or forks like Purpur)
\n – **Java 21**
\n – **MySQL 8.0+** database<\/p>\n
### Optional Dependencies<\/p>\n
– **PlaceholderAPI** – for placeholder support in chat, scoreboards, etc.<\/p>\n
—<\/p>\n
## Installation<\/p>\n
1. Download `MysticalReferral-1.0.0.jar`
\n 2. Place the JAR in your server’s `plugins\/` folder
\n 3. Start the server once to generate `config.yml`
\n 4. Edit `plugins\/MysticalReferral\/config.yml` with your MySQL credentials
\n 5. Restart the server or run `\/referral reload`<\/p>\n
—<\/p>\n
## Building from Source<\/p>\n
“`bash
\n git clone https:\/\/github.com\/your-org\/MysticalReferral.git
\n cd MysticalReferral
\n mvn clean package
\n “`<\/p>\n
The compiled JAR will be at `target\/MysticalReferral-1.0.0.jar`.<\/p>\n
Build requirements: Java 21, Maven 3.9+<\/p>\n
—<\/p>\n
## Configuration<\/p>\n
### Database<\/p>\n
“`yaml
\n database:
\n host: localhost
\n port: 3306
\n name: mysticalreferral
\n username: root
\n password: password
\n pool:
\n maximum-pool-size: 10
\n minimum-idle: 2
\n connection-timeout: 30000
\n idle-timeout: 600000
\n max-lifetime: 1800000
\n “`<\/p>\n
Create the database beforehand:<\/p>\n
“`
\n CREATE DATABASE mysticalreferral;
\n “`<\/p>\n
### Settings<\/p>\n
“`yaml
\n settings:
\n code-length: 5
\n min-playtime-minutes: 10
\n allow-ip-referrals: false
\n leaderboard-size: 10
\n code-expiration-days: 0
\n language: en
\n update-checker: true
\n “`<\/p>\n
### Rewards<\/p>\n
Rewards are executed as **console commands**. Use `%player%` as a placeholder for the player’s name.<\/p>\n
“`yaml
\n rewards:
\n inviter:
\n commands:
\n – “give %player% diamond 2”
\n – “eco give %player% 500”
\n invited:
\n commands:
\n – “give %player% diamond 1”
\n – “eco give %player% 100”
\n “`<\/p>\n
### Milestone Rewards<\/p>\n
“`yaml
\n milestones:
\n 5:
\n commands:
\n – “give %player% emerald 5”
\n message: “&a&lMilestone! &eYou reached &b5 &einvites!”
\n 10:
\n commands:
\n – “give %player% emerald 16”
\n – “eco give %player% 2000”
\n message: “&a&lMilestone! &eYou reached &b10 &einvites!”
\n “`<\/p>\n
### Effects<\/p>\n
“`yaml
\n effects:
\n sound:
\n enabled: true
\n type: ENTITY_PLAYER_LEVELUP
\n volume: 1.0
\n pitch: 1.0
\n title:
\n enabled: true
\n title: “&a&lReferral Used!”
\n subtitle: “&7You and &e%player% &7received rewards!”
\n inviter-title:
\n enabled: true
\n title: “&a&lNew Referral!”
\n subtitle: “&e%player% &7used your code!”
\n “`<\/p>\n
### Custom Referral Codes<\/p>\n
“`yaml
\n custom-codes:
\n enabled: true
\n min-length: 3
\n max-length: 16
\n allowed-pattern: “^[A-Za-z0-9_]+$”
\n force-uppercase: true
\n “`<\/p>\n
### Top Referrer Scheduled Rewards<\/p>\n
“`yaml
\n top-rewards:
\n enabled: false
\n interval-minutes: 1440
\n top-count: 3
\n broadcast: true
\n positions:
\n 1:
\n commands:
\n – “give %player% netherite_ingot 3”
\n message: “#1 Top Referrer! Congrats %player%!”
\n “`<\/p>\n
—<\/p>\n
## Commands<\/p>\n
| Command | Description | Permission | ---<\/p>\n ## License<\/p>\n This project is provided as-is for use on Minecraft servers.<\/p>\n","protected":false},"excerpt":{"rendered":" A feature-rich referral and invite reward system plugin for Minecraft Paper servers.<\/p>\n","protected":false},"featured_media":108308,"template":"","meta":{"_minecraft_slug":"mysticalreferral","_minecraft_project_id":"lWCaIvYW","_minecraft_author":"mysticalcraft-ancientvipers","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":21,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"mysticalreferral.zip","_minecraft_size_bytes":4389612,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:28:28.335155Z","_minecraft_date_created":"2026-03-12T08:38:02.888266Z","_minecraft_date_modified":"2026-03-09T23:32:50.927918Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/mysticalreferral","_minecraft_icon_attachment_id":108308,"_minecraft_imported_at":"2026-06-06T06:19:03+00:00","_minecraft_import_hash":"1decf5cb11d92b240f8c957a11e264c8","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[127],"mod_loader":[132],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-108307","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-paper","mod_loader-paper","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n |—|—|—|
\n | `\/invite` | Generate or view your referral code (click-to-copy) | `mysticalref.invite` |
\n | `\/invite set ` | Set a custom vanity referral code | `mysticalref.customcode` |
\n | `\/ref ` | Use a referral code | `mysticalref.use` |
\n | `\/referral stats` | View your referral stats | `mysticalref.referral` |
\n | `\/referral top` | View the leaderboard | `mysticalref.referral` |
\n | `\/referral history` | View who you've referred | `mysticalref.referral` |
\n | `\/referral reload` | Reload configuration | `mysticalref.reload` |
\n | `\/referral admin info
\n | `\/referral admin reset
\n | `\/referral admin setcode ` | Set a custom referral code | `mysticalref.admin` |<\/p>\n