Referrals

```yaml

_____ __ _

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

| | __/ |

|_| |___/

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")

```