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

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

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

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.

rewards:
  inviter:
    commands:
      - "give %player% diamond 2"
      - "eco give %player% 500"
  invited:
    commands:
      - "give %player% diamond 1"
      - "eco give %player% 100"

Milestone Rewards

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

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

custom-codes:
  enabled: true
  min-length: 3
  max-length: 16
  allowed-pattern: "^[A-Za-z0-9_]+$"
  force-uppercase: true

Top Referrer Scheduled Rewards

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

License

This project is provided as-is for use on Minecraft servers.