MysticalReferral

Minecraft 版本： 1.21 1.21.1 1.21.2 1.21.3 1.21.4 1.21.5 1.21.6 1.21.7 1.21.8 1.21.9 1.21.10 1.21.11

平台： paper

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.