Referrals

Ever wanted to reward players for directing people to your server? see your server empty most of the time? then Referrals is for you! Referrals is a super-configurable plugin that allows you to award players who bring new people to your server. So, how does this work? basicly, users can generate referral codes using the command /generatecode. these codes can then be used by new players using the command /redeem <code> this will give the player and the referrer configurable prizes in the form of items, economy or even make it run console commands! players can also use the command /referstats to view how many people they have referred or /codes to view their current active codes.

/redeem has be changed to /redeemcode in v0.42 and above!

Features

super-configurable
Messages Config
Give players prizes in the form of money, items or even make it run console commands for referring another player to your server
help page /help referrals
configurable number of maximum codes
configure the required playtime of a player for them to be allowed to generate a code
create custom codes
set whether to use player names instead of codes
code deleted after use
Checks if players have played before when plugin is started to ensure old players don't refer each other
Players cannot refer themselves
Players cannot refer users from the same ip address
players cannot redeem more than 1 code
Config auto updates with updates
log file which logs all records of referrals (turned on by changing value "showReferralsLog" in config to true)
view stats about how many people you/another player has referred
config option to only allow players to redeem a code the first time they log in
config option to deactivate old users codes
839,299,365,868,340,224 possible codes, Thats over 839 Quadrillion!

ShowCase by SGTCaze

How to Use

The player who wants to refer another player types /generatecode to generate a code for the other player to use. They can also use /codes to view their active codes. A maximum amount of codes can be set in the config.
The player who was referred logs in and is prompted with a message telling them to use the command /redeem <code> to redeem a referral code. The message can be changed in the massages config.
Both players recieve configurable rewards for referring someone and redeeming a code (to make it worth actually using the /redeem command). You can also add special prizes for when they reach a certain number of referrals.

Commands

Below is a list of commands and what they do

[ ] = Optional
< > = Necessary

/redeemcode <code> - The command used to redeem a users code, declaring that they referred you.

(In versions before v0.42 use /redeem)

/generatecode [code] - The command used to generate a code to be used in /redeem <code>, If enabled on server when you type /generatecode with a code after it it will create a code called that.

/codes - The command to view your active codes.

/refertop [page] - Allows you to view who the top referrers are on your server.

/referstats [player] - Allows you to view the referral stats of the given player. defaults to sender if no player is named.

/help referrals - Displays the referrals help page

/fixrefferers - Sets all players play time to 0, used for if you are recieving glitch when players cant use /generatecode because it says they have to play another ridiculous amount of time.

How to Install

To install this plugin simply drag the referrals.jar file into your servers plugins folder and then restart your server!

Permissions

below is a list of permissions along with a brief description on what they do and what they are defaulted to. Do not add the colon ( : ) to after the pemission that is just to show that it is associated with the lines following it.

    referrals.fix:
        description: Allows you to use /fixreferrers
        default: false
    referrals.redeem:
        description: Allows you to redeem someones code in-game
        default: true
    referrals.generate:
        description: Allows you to generate a referral code
        default: true
    referrals.stats:
        description: Allows you to view your referral stats
        default: true
    referrals.top:
        description: Allows you to view the referral top list
        default: true

Set Rewards for when players reach certain goals

Many people have made it obvious in the comments that they dont know how to set rewards at certain goals. To do it read everything in the config section under Prizes.

Config

Below is the default config along with a list of what all the values do.

showReferralsLog: false
loginMessageDelay: 40
usePlayerNames: false
allowCustomCodes: false
autoUpdate: true
checkIpAdress: true
onlyAllowReferralsFirstLogin: true
requiredPlayTime: 0
maxCodes: 1
useEconomy: false
removeOldUsersCodes: 14
Prizes:
  onRedeem:
    money: 20
    items:
      - DIAMOND:0:2
    commands:
  onEvery:
    money: 100
    items:
      - DIAMOND:0:5
    commands:
  on5:
    money: 500
    items:
      - DIAMOND:0:10
    commands:
      - referstats @p

showReferralsLog: false - sets whether a log should be created with records of all referrals

loginMessageDelay: 40 - sets the delay time for the messageFirstLogin message. counted in ticks (20 ticks = 1 second).

usePlayerNames: false - true or false, sets whether to use player names instead of codes for referring people

onlyAllowReferralsFirstLogin - true or false, sets whether players can only use the command /redeem <code> when they first login.

maxCodes - a number, sets the maximum number of active codes the player can have at any one time.

useEconomy - true or false, sets whether or not to use economy integration for giving money to players when they refer a player or redeem a code.

checkIpAdress - true or false, sets whether to block people being referred by another user using the same ip address. Can be used to stop people using their multiple accounts to get free rewards.

Prizes - the list of all prizes that can be awarded to players. onRedeem will be given to players who redeem a code and onEvery will be given to players who refer someone unless they hit a referrals milestone. on<number> will be given to players when they hit the required number of referrals. Example: "on5" will give players who hit 5 referrals the configured items.

money - a number, sets the amount of money the player will be given when they recieve a prize. Only works if useEconomy is set to true

items - a list of items to be rewarded the the players, it goes NameOfItem:dataValue:amount. for example "DIAMOND:0:50" would give the player 50 diamonds. If you do not want to give the player items just clear everything after items: but do not remove the items:

commands - a list of commands to be executed upon the receiving of a prize. You can use the symbol "@p" to use players names, just type in @p and it will be replaced with the players name or @r and it will be replaced by the player who was referred or if used in onRedeem it will be replaced with the referrers name. Example: "gamemode 1 @p" this would set the gamemode of the player who recieved the prize to 1 or "gamemode @r 1" would set the referred player to gamemode 1.

requiredPlayTime - the required play time of the player to refer someone, counted in minutes.

removeOldUsersCodes - the amount of days before old users codes will be removed, set to 0 if you do not want them to be removed.

Messages

referrals contains a custom config file for messages. Below is the default messages config along with how to use it.

To use colours in your messages simply use the chatcolor numbers/letters with an & sign before them. For example "&cpotato!" would make the text potato! red.

there are also special codes beginning with an @ symbol to include names of players/codes to your message. Note these are only available in some of the messages.

@n - gives a players name, could be who referred you or who redeemed your code.

@c - displays the referral code instead of the @c

@r - displays the number of referrals the player has made

MESSAGE_FIRST_LOGIN: "&aType /redeem <code> to set who referred you and get some &6Free Items!"
MESSAGE_INVALID_CODE: "&cThe code you have entered is invalid"
MESSAGE_INVALID_PLAYER: "&c unable to find the player @p"
MESSAGE_INVALID_PAGE: "&cThere is no page number @n"
MESSAGE_NO_PERMISSION: "&cSorry, You do not have the required permissions"
MESSAGE_NO_CODES: "&cYou have not generated any codes, /codes to view your codes"
MESSAGE_NOT_PLAYER: "&cYou must be a player to run this command"
MESSAGE_VIEW_CODES: "&a Below is a list of all your active &6referral codes"
MESSAGE_VIEW_CODE: "&a - &6@c"
MESSAGE_VIEW_STATS: "&aYou have referred &6@r &apeople"
MESSAGE_VIEW_STATS_OTHERS: "&6@n &ahas referred &6@r &apeople"
MESSAGE_REFFER_SELF: "&cYou can not refer yourself!"
MESSAGE_SAME_IP: "&cYou can not refer someone with the same ip address as you!"
MESSAGE_TOP_HEADER: "&aReferrals top, Page &6@p"
MESSAGE_TOP: "&a@n - &6@p&a: &6@r"
MESSAGE_NOT_NUMBER: "&c@s must be a number"
MESSAGE_MAX_CODES_REACHED: "&cYou have already reached the max amount of codes, /codes to view your codes"
MESSAGE_REDEEM_REFERRERS_CODE: "&cyou can not have been referred by the person you referred"
MESSAGE_REFERRED: "&6@n has redeemed your code"
MESSAGE_ALREADY_REDEEMED: "&cYou can only redeem 1 code"
MESSAGE_BELOW_REQUIRED_PLAYTIME: "&cyou must play another @t minutes before you can refer someone"
MESSAGE_BEEN_REFFERED: "&aYou have been referred by &6@n"
MESSAGE_CREATE_CODE: "&aSuccesfully registered code: &6@c"
MESSAGE_FIX_REFERRERS: "&cSuccesfully fixed referrers"
MESSAGE_USEPLAYERNAME: "&cThere is no need to generate a code, you can just use your username!"

Source

The source for referrals can be found inside the jar, feel free to take a look.

How to use on Bungee Servers

If you were to run this plugin on a bungee server you may find that it will disable you from being able to refer players and it will send you the message "you cannot refer players with the same ip address" or something along those lines.

to fix it simply go to the config and change the value "checkIpAdress: true" to "checkIpAdress: false".

Edit: you can also if you want set it to use the players actual ip address on bungee to ensure people dont refer people on the same ip address. Thanks to theoneofcheese123 for telling me about this.

To set bungee to use players actual ip addresses simply go into you bukkit.yml and spigot.yml (if using spigot) and ensure that you have both you dedicated server/VPs/server IP and 127.0.0.1 under "bungee-proxies:" like this -

bungee-proxies:

- 127.0.0.1

- 198.27.70.213

That will make it so BungeeCord sends real player IP's allowing this plugin to be able to use ip checking

Found an Error?

please post below with this template and i will have a look into it:

version:
error description:
stacktrace(if any):
config:

also please use the code tags for your config and the stack trace to make it easier to read, the code tags can be used by clicking the icon of the three cogs at the very right of the toolbar next to the link and picture icons.

MCStats

This plugin uses metrics to record data. If you wish to turn this off simply go to your plugins folder then into the PluginMetrics folder and then open the file config.yml and change opt-out: false to opt-out: true. Metrics is helpful to see stats about how your plugin is going, like how many servers are using it.

Examples of what data Metrics collects:

Server Type / Version
Java Version
Minecraft Version
Metrics version!
Amount of players
Operating system & version
Auth mode

What data metrics does not collect:

IPs
Nicknames
Other private informations

Below is the results metrics generates. Stats

Donate

Donating helps me find time to update this plugin! although not necessary donating is greatly appreciated! a donate button can be found in the top right of the page if you would like to help me out!

Official Server

The official server of the plugin referrals is lividiusgaming, play at hub.lividiusgaming.com