Referrals

A very customisable referral system, with support for milestones, rewards, waiting to execute rewards until player joins back, custom messages, reminders on join, account join time limits, referral limits, circular referral blocking, and placeholders.

Config

All config options are explained in the config.yml file

config.yml

# _____            __                                _             _                   _
#|  __ \          / _|                              | |           | |                 (_)
#| |__) |   ___  | |_    ___   _ __   _ __    __ _  | |    _ __   | |  _   _    __ _   _   _ __
#|  _  /   / _ \ |  _|  / _ \ | '__| | '__|  / _` | | |   | '_ \  | | | | | |  / _` | | | | '_ \
#| | \ \  |  __/ | |   |  __/ | |    | |    | (_| | | |   | |_) | | | | |_| | | (_| | | | | | | |
#|_|  \_\  \___| |_|    \___| |_|    |_|     \__,_| |_|   | .__/  |_|  \__,_|  \__, | |_| |_| |_|
#                                                         | |                   __/ |
#                                                         |_|                  |___/

# Prefix
# The prefix to use in messages
# default: "&6&l[Referral]"
prefix: "&6&l[Referral]"

# Circlular referrals
# If player1 refers player2, can player 2 also refer player1?
# default: false
circular-referrals: false

# Maximum referrals
# How many players can one player refer?
# Set to -1 for unlimited referrals
# default: -1
max-referrals: -1

# Maximum age
# How many seconds can a user have played before they cannot run /refer to claim their referral?
# Set to -1 for no limit
# default: 86400 (24 hours)
max-age: 86400

# Referree joined requirement
# Does the player that referred the player have to have joined the server before the referree joins?
# This helps prevent players from putting invalid usernames.
# default: true
referree-joined-requirement: true

# Notify on join
# Should players that haven't been referred be notified about the referral system on join, if the max-age hasn't been exceeded?
# default: true
notify-on-join: true

# Notify delay
# How long to wait (in milliseconds) before sending the notify message on join
# This ensures the message appears after the join message
# default: 1000 (1 second)
notify-delay: 1000

# Messages
# Customize all messages sent by the plugin
# Available placeholders:
# {prefix} - The prefix defined above
# {player} - The player's username
# {referrer} - The referrer's username
# {claimer} - The claimer's username
# {max-age} - The max age in seconds
# {max-age-hours} - The max age in hours
# {max-referrals} - The max referrals limit
# {hours} - Hours remaining (for time-remaining message)
# {minutes} - Minutes remaining (for time-remaining message)
# {value} - Generic value placeholder
messages:
  # Command messages
  player-only: "&cThis command can only be used by players."
  no-permission: "&cYou do not have permission to use this command."

  # /refer command messages
  refer-usage: "&cUsage: /refer <username>"
  refer-success: "{prefix} &aYou have been referred by {referrer}!"
  already-referred: "{prefix} &cYou have already set your referrer!"
  cannot-refer-self: "{prefix} &cYou cannot refer yourself!"
  referrer-not-joined: "{prefix} &cThe player '{referrer}' has not joined the server before!"
  account-too-old: "{prefix} &cYou cannot set a referrer because your account is too old!"
  account-too-old-details: "&cMaximum age: {max-age} seconds ({max-age-hours} hours)"
  circular-referral-blocked: "{prefix} &cCircular referrals are not allowed! {referrer} was referred by you."
  max-referrals-reached: "{prefix} &cThe player '{referrer}' has reached the maximum number of referrals!"

  # /refer explanation (when no args provided)
  refer-explanation-header: "{prefix} &eReferral System"
  refer-explanation-line1: "&eIf someone referred you to this server, use this command to give them credit!"
  refer-explanation-usage: "&eUsage: &a/refer <username>"
  refer-explanation-current: "&aYou were referred by: &f{referrer}"
  refer-explanation-time-remaining: "&eYou have &a{hours} hours and {minutes} minutes &eto claim your referral."
  refer-explanation-expired: "&cYour account is too old to claim a referral."
  refer-explanation-no-limit: "&eYou can claim your referral at any time!"

  # Join notification messages
  notify-line1: "{prefix} &eYou haven't set who referred you yet!"
  notify-line2: "&eUse &a/refer <username> &eto claim your referral reward!"

  # /referral help command
  help-header: "{prefix} &eReferral Plugin Commands:"
  help-refer: "&a/refer <username> &7- Claim who referred you to the server"
  help-referral-help: "&a/referral help &7- Show this help message"
  help-referral-config: "&a/referral config &7- View current configuration"
  help-referral-reload: "&a/referral reload &7- Reload the plugin configuration"

  # /referral command messages
  referral-usage: "&cUsage: /referral <help|config|reload>"
  referral-unknown-subcommand: "&cUnknown subcommand. Use &e/referral help &cfor available commands."
  reload-start: "{prefix} &eReloading referral configuration..."
  reload-complete: "{prefix} &aReferral configuration reloaded."

  # /referral config messages
  config-header: "{prefix} &eCurrent Referral Configuration:"
  config-circular: "&eCircular referrals: &f{value}"
  config-max-referrals: "&eMax Referrals: &f{value}"
  config-max-age: "&eMax Age: &f{value}"
  config-referree-joined: "&eReferree Joined Requirement: &f{value}"
  config-notify-on-join: "&eNotify on Join: &f{value}"
  config-store-offline: "&eStore Rewards if Offline: &f{value}"

# Rewards
# Rewards to give to the referrer and referree when a referral is claimed.
rewards:
  # Claimer is the player who ran /refer <username>, aka the new player
  claimer:
    # Commands to run as console when a referral is claimed
    # {player} is replaced with the claimer's username
    commands:
      - "give {player} diamond 5"
    # Messages to send to the claimer when a referral is claimed
    messages:
      - "&aYou have received 5 diamonds for being referred!"
  # The player who referred the new player, this is the <username> that was passed to /refer <username>
  referrer:
    # Store if offline means if the referrer is offline when the referral is claimed, the commands and messages will run/send when they next join
    # default: true
    store-if-offline: true
    # Commands to run as console when a referral is claimed
    # {player} is replaced with the referrer's username
    commands:
      - "give {player} emerald 10"
    # Messages to send to the referrer when a referral is claimed
    # {claimer} is replaced with the claimer's username
    messages:
      - "&aYou have received 10 emeralds for referring {claimer}!"

  # Milestone rewards
  # These are given to the referrer when they reach a certain number of referrals
  # Milestones are only triggered once per milestone
  # Available placeholders: {player}, {milestone}, {total}
  milestones:
    # Enable or disable milestone rewards
    # default: true
    enabled: true

    # Individual milestone configurations
    # The key (5, 10, 17, 25, etc.) is the number of referrals needed
    5:
      commands:
        - "give {player} diamond_block 1"
      messages:
        - "&6&lMILESTONE REACHED!"
        - "&eYou have referred &a{total} &eplayers!"
        - "&aYou received 1 Diamond Block!"
    10:
      commands:
        - "give {player} emerald_block 2"
      messages:
        - "&6&lMILESTONE REACHED!"
        - "&eYou have referred &a{total} &eplayers!"
        - "&aYou received 2 Emerald Blocks!"


# bStats
# Enable or disable bStats metrics collection
# This helps me understand how the plugin is being used
# default: true
bstats: true

# PlaceholderAPI Integration
# Available placeholders (requires PlaceholderAPI):
# %referral_referred_by% - Username of who referred the player (or "None")
# %referral_has_referrer% - "true" or "false"
# %referral_total_referrals% - Number of players this player has referred
# %referral_first_join% - Timestamp of first join (or "Unknown")
# %referral_account_age% - Account age in seconds (or "Unknown")
# %referral_account_age_hours% - Account age in hours (or "Unknown")
# %referral_can_claim% - "true" or "false" if player can claim a referral
# %referral_time_remaining% - Seconds until referral claim expires ("Unlimited", "Expired", or seconds)
# %referral_time_remaining_hours% - Hours until referral claim expires ("Unlimited", "Expired", or hours)
# %referral_next_milestone% - Next milestone the player will reach (or "None"/"Disabled")
# %referral_referrals_until_next% - How many more referrals until next milestone (or "None"/"Disabled")

Placeholders

If you have PlaceholderAPI installed, you can use the following placeholders:

Placeholder	Description
%referral_referred_by%	Who referred the player, "None" if not referred
%referral_has_referrer%	Does the player have a referrer, true/false
%referral_total_referrals%	How many players has this player referred
%referral_first_join%	Timestamp in unix millis that the player first joined since the plugin has been installed
%referral_account_age%	Seconds since the player joined for the first time
%referral_account_age_hours%	Hours since the player joined for the first time
%referral_can_claim%	Can the player still claim a referral, checks if they have already been referred, and if they have joined too long ago
%referral_time_remaining%	Seconds until they can no longer claim a referral, or "Unlimited", or "Expired"
%referral_time_remaining_hours%	How many hours are left until they can't claim a referral, or "Unlimited", or "Expired"
%referral_next_milestone%	How many referrals they need to have in total until the next milestone
%referral_referrals_until_next%	How many referrals they need until they get the next milestone

All placeholders are also explained at the bottom of the config.yml file

Milestones

Reward players for inviting more players, for example, give a bonus reward for the 5th referral, or for the 50th

Permissions

There are only 2 useful permissions

1. referral.use - Allows players to run /refer , defaults to enabled
2. referral.admin - Allows for /referral reload and /referral config, defaults to OP

Commands

Command	Description	Permission	Default
/refer <username>	Sets who referred you	referral.use	Defaults to enabled for all users
/referral reload	Reloads the config	referral.reload/referral.admin	Defaults to OP
/referral config	Shows some of the config values, mainly for debugging	referral.config/referral.admin	Defaults to OP

Support

Need help with the plugin? Send a message to me on discord, my username is editid.