"Referred By" Rewards

Referred By

With the 'referred by' extension to OnTime, players can be rewarded for referring their friends to the server, but they will only receive the reward after the new player has been on the server for a configurable amount of time.

The configuration and setup of the feature gives the administrator the ability to reward groups of players differently, for example a reward for a referral by a server donor can be greater than the reward issued to just some average player. Rewards can also be set up in tiers so a minimal reward can be given right away for a referral, but then a larger reward issued after the new player has been on for much longer. (a 'reward set')

Also, referral rewards can be defined such that they are only issued after a player has successfully referred a certain number of different players.

The 'referred' player can also receive a reward as incentive for executing the 'referred by' command.

Only one referral reward set will be issued per new player, but a player can be credited for making any number of referrals. A player can never refer themselves.

If the MySQL storage option of player data is used for OnTime, the number of referrals made by a player will be counted and stored, and the name of the person that referred a player will also be maintained.



In order to make and receive 'referred by' rewards a player or group must have the 'ontime.referredby.enable' permission.

Configuration (/ontime/config.yml)

In order for the 'referred by' functions to be active on the server, it must be enabled:

referredByEnable: true

To prevent long time players from suddenly claiming they were referred by someone else, a max time can be set, such that if the player has more than that many hours played on the server, a 'recommended by' request will be denied. Setting this parameter to -1 will disable the function, and all players can claim they were referred.

referredByMaxTime: -1

Reward Setup

Basic Referral Reward

Example 1: Define a referral reward of 100 coins to be issued to the referring (source) player, once the referred (target) player has been on the server for one hour.

1. Define a reward of 100 coins.

/ontime rewards add econ 100 1h

2. Make that reward a referral reward

/ontime rewards refer 1 (The number here is the rewardID. Since we only have one reward defined, it is #1)

3. Done!

Target Player Reward

Example 2: Define a reward of 50 coins to be given to the target player, to be issued at the same time as the referring player gets the reward above.

1. Define reward of 50 coins

/ontime rewards add econ 50 1h

2. Make that reward a referral (target) reward

/ontime rewards refer 2 target
(Here the 'target' keyword is required to indicate this is a reward for the player receiving the referral. Also note that this is RewardID=2. Because its has the same timestamp as above, but was created second, so it ID will be "2". Remember you can always find out the RewardID using the command "/ontime rewards list")

3. Done!

Exclusive Referral Reward

Example 3: Define a referral reward of 20 diamonds, to only be issued to source players whom are members of the 'donor' group, once the target player has been on the server for one day.

1. Define a reward of 20 diamonds

/ontime rewards add item 20 diamonds 1d

2. Make that reward a referral reward

/ontime rewards refer 3 source (In this example the optional keyword 'source' is used, which indicates this is a referral reward for the referring (source) player.

3. Make that reward 'exclusive' to the 'donor' group.

4. Done!

Referral Count Reward

(Note: This reward type requires use of MySQL option for player data storage for OnTime.)

Example 4: Define a group change to VIP reward, issued to a referral source only after that player has successfully referred a certain number of other players.

1. Define a reward of group change to VIP group.

/ontime rewards add addgroup VIP 1h

2. Make this a referral reward that requires 5 referrals, before it is issued.

/ontime rewards refer 3 source count=5

(alternatively: ' /ontime rewards refer 3 count=5')

3. Done!

(Note that the rewardID (3) above assumes you did the other examples. The actual rewardID can be found using the "/ontime reward list" command.) 3. Done!

Making it Happen

When the new player joins the server, they simply need to execute the 'referred by' command.


Assuming that I'm the one that made the reference:

/referred by Edge209

(Note that this command does NOT start with ontime.)

In the example above, I would receive 100 coins after the player that executed the 'referred by' command has been on the server for 1 hour. If I am a member of the 'donor' group on the server, I will receive an additional 20 Diamonds after that same player has been on the server for 1 days worth of playtime. If I am on the server at the time that the player achieves these playtime levels I will get the rewards immediately. If I am not on the server at that time, I will get the reward(s) shortly after I next login to the server. The player that executed the 'referred by' command will receive his reward for executing this command once he has been on the server for one hour. If this is the fifth player I have referred, I will get a bonus reward of being put into the server's VIP group!

If the player had entered the following instead:

/referred by edge

"edge" would not be found as a user in my server's OnTime database. The response to the user would be a list of possible close matches:

There is no EdgeCraft record of a player named edge
Did you mean one of the following?
Edge209     fredgeMan

The player would then need to re-enter and provide the correct full name.

This feature requires that MYSQL be used to maintain the OnTime data.

Undoing a Referral

If you need to rollback a player's referral status, such that they can again issue a 'referred by' command, this can easily be done with the command:

/referred undo <playerName>

Where 'playerName' is the player you would again like to be able to issue a 'referred by' command.

If this command is executed after a 'referred by' command is done but before the player has reached the total OnTime needed to issue the rewards, the rewards will be cancelled. If the player has already reached that total OnTime required and rewards have been issued and/or scheduled for the 'referral source' the rewards cannot be stopped or undone.
This command can be executed from the console or in game, and requires the 'ontime.referred.admin' permission node.

Seeing a Player's Referrals

You can see the names of all of the players referred by a specified player using the following command:

/referred list <playerName>

This feature requires that MYSQL be used to maintain the OnTime data.

Behind the Scenes

  • After a new player has issued the 'referred by' command, 'referred by' rewards will be scheduled for that player. So if you execute the '/ontime <playerName>' command for that new player, you will see listed for them these rewards. This does not mean they will receive the reward, but the plugin is using the same mechanism to track their playing time to know when to issue the reward later to the referring player. Once the new player reaches the target playing time, a reward will then be scheduled for the referring player, and would show up for that player when '/ontime <playerName>' is executed.
  • Once a new player has been 'successfully referred' by another player, meaning the referring player has received at least one reward, the new player will be given the 'permission string' of 'ontime.referredby.success'. This string will appear in the permission plugin's configuration for that new player. It is this permission sting that prevents the player from issuing additional 'referred by' commands.


Posts Quoted:
Clear All Quotes