# 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

```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 " 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 " 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 &eto claim your referral reward!" # /referral help command help-header: "{prefix} &eReferral Plugin Commands:" help-refer: "&a/refer &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 " 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 , 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 that was passed to /refer 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 ![Milestones config section](https://cdn.modrinth.com/data/cached_images/bccf85305be72c3d7483db5f6fc55836639b29cf.png) ## 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 `|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`.