Advanced OnTime Rewards

The OnTime Rewards system is very flexible and offers many different features that when combined, can create a large variety of playtime-based reward programs. In this tutorial I will be covering some of the more advanced features of the OnTime Rewards system, with some combinations that achieve a more sophisticated rewards system.

In this tutorial I will cover:

• Pay for Play (a.k.a. salaries)
• Pay Scales (a.k.a. Different salaries for different ranks)
• Daily, Weekly, Monthly Rewards

• Linking Rewards

• Customizing messages for a specific rewards
  

Configuration

config.yml

The base plugin configuration is found in /plugin/ontime/config.yml, and there are of different configuration parameters related to the rewards system. When first downloaded, the plugin has the rewards system fully enabled by default, so unless you have changed something the following is just for your information.
The OnTime Rewards system must be enabled, and if you want players to receive notice when they receive a reward, or the occurrence of some special rewards broadcast to the server, these must be enabled too.

from config.yml

For the daily, weekly, and monthly rewards covered in this tutorial to be available, tracking of this data must be enabled, and these reward types must be enabled.

If a ‘top total’ reward is going to be issued the timing (frequency) of when these rewards are issued needs to be specified by setting the ‘totalTopReward’ parameter. These rewards can be issued daily, weekly, or monthly.

The following is the pre-set conditions found when OnTime is first installed.

from config.yml

# Enable if daily playingtime should be collected and reported
collectDailyEnable: true

# Enable if weekly playingtime should be collected and reported
collectWeeklyEnable: true

# Enable if monthly playingtime should be collected and reported
collectMonthlyEnable: true
……
# Top Player Rewards
# Enable if rewards should be allowed to be defined as 'top player' rewards for the associated time period.
topRewardDailyEnable: true
topRewardWeeklyEnable: true
topRewardMonthlyEnable: true
topRewardTotalEnable: true

# When should rewards be issued to the overall top (total OnTime) players?  Valid settings: "daily", "weekly", and "monthly"
totalTopReward: weekly

rewards.yml

There is an additional configuration file plugin/ontime/rewards.yml that is used to configure the various pieces of the OnTime Rewards system. Later in the tutorial we will have a reason to directly edit this file, but under most circumstances, OnTime will make most changes needed to this file automatically.

OnTime Advanced Rewards

There are many different use cases, or reward scenarios that can be achieved with OnTime. The ‘building block’ commands are defined and explained in the ‘Rewards’ page, so instead of repeating that info here, I will be describing some use cases and showing how they can be achieved with OnTime.

“Pay for Play” Rewards

Repeating Rewards (1)

One way to reward players for playing on your server is to give them a reward for every so many minutes or hours of playtime. To do this with OnTime the most common method is to use a perpetual reward. Let’s say I want to reward my players for every hour they spend on my server with 50 coins, beginning with the 3rd hour they have played. To do this I will execute the following two commands:

The first command above, defines a ’50 coin’ reward to be issued after 3 hours of playtime. The second command establishes that this reward should be issued there after every one hour, and by definition of a perpetual reward this will continue forever.

The reward to make perpetual was specified using the “pay50” RewardTag. Alternatively, I could have used the RewardID, which is a number automatically assigned to the reward based upon its time sorted order. Because this is the only reward I have defined I know it must be rewardID=1. You can always find out the rewardID assignments through use of the command: “/ontime rewards list”. The sorted order number found at the beginning of each reward is the ‘rewardID’.

Repeating Rewards (2)

Another common scenario is to have repeating rewards that increase over time as players spend more time on the server. Here I want to reward players as I did above, but after they log a full day worth of playtime I want to increase the amount of coin they get to 100 coins for every hour, and then go to 200 coins per hour after 5 full days of play. To set this up the following commands would be used:

>/ontime rewards add econ 50 1h tag=pay50
>/ontime rewards recur pay50 1h
>/ontime rewards add econ 100 1d tag=pay100
>/ontime rewards recur pay100 1h
>/ontime rewards add econ 200 5d tag=pay200
>/ontime rewards recur pay200 1h

For the 50 coin and 100 coin rewards I used the‘recur’ command to designate these as recurring rewards. A recurring reward is very much the same as a perpetual reward, except that it will stop repeating once a subsequent reward start time is reached. Therefore the 50 coin reward will happen every hour until the first 100 coin reward is issued after 1 day of playtime. Same goes then for the 100 coin reward, happening every hour until the five days of playtime has been achieved. Because I have no more rewards defined after the 200 coin reward, it will continue forever.

Repeating Rewards (3)

When using economy awards, one thing that server owners need to be cautious of is killing their own economy by “printing” too much money. One way to do this is to limit the number of econ rewards made to each player at each of the intervals, this can be achieved with OnTime using the “count=” parameter. Here I will use the same scenario above, but this time limit the number of payouts at each level to 12, or half a day. To set this up the following commands would be used:

>/ontime rewards add econ 50 1h tag=pay50
>/ontime rewards recur pay50 1h count=12
>/ontime rewards add econ 100 1d tag=pay100
>/ontime rewards recur pay100 1h count=12
>/ontime rewards add econ 200 5d tag=pay200
>/ontime rewards recur pay200 1h count=12

In this case I have used the “recur” command for all three levels (50, 100, and 200 coins) and used the “count=” parameter to limit the number of payments made at each level to 12. In each case the player will receive 12 rewards at each level, and will not receive any more rewards until the minimum time is reached for the next level. The 200 coin reward was changed from the perpetual setting used in the previous example, because by definition a “perpetual” reward can have no limits applied.

Pay Scales

Servers sometime like to set up payment system for their players based on time played, with a different pay scale based on the rank of the players. This can be done with OnTime by using the ‘exclusive’ reward setting.

Configuration

There is one piece of configuration that must be done to allow OnTime Rewards to work with permission groups (ranks). The group used by the server must be listed in the /plugins/OnTime/rewards.yml file under the “groups:” keyword. A best practice is to always list every group used by the sever, even if they are not involved in the rewards you want to set up. Doing this will help avoid issues in the future if you decided to use OnTime’s auto-promotion function. The group names must be added by directly editing the rewards.yml file, there is no OnTime command to do this.

groups:
- Default
- Noobie
- Builder
- VIP
- Moderator
- owner

On my server I have three ranks: noobie, builder, and VIP that are to receive a salary. I want to reward these players for each hour they play, but want to give the noobie 1 coin/hour, the builder 3 coins/hr, and the VIP 10 coins/hour. Here is how I would set that up:
Adding the pay rate for the noobie:

>/ontime rw add econ 1 1h tag=noobiePay
>/ontime rw perp noobiePay 1h
>/ontime rw exclusive noobiePay add noobie

The first command above creates the 1 coin reward to occur at the first hour of play. The second command makes this reward repeat forever at one hour intervals. The last command makes it such that this reward is only given to members of the group “noobie”.
The following sets up the same thing for the pay rates for the “builder” and “VIP” groups.

Adding the pay rates for the builder and VIP:

>/ontime rw add econ 3 1h tag=builderPay
>/ontime rw perp builderPay 1h
>/ontime rw exclusive builderPay add builder
>/ontime rw add econ 10 1h tag=vipPay
>/ontime rw perp vipPay 1h
>/ontime rw exclusive vipPay add VIP

Daily, Weekly, Monthly Play Rewards

Daily Login Bonus

With OnTime you can create a reward that will be issued to every player each day that they log into the server. This reward would only be issued once per player, per day and can be set such that it is immediate upon the first login, or you can require some minimum amount of playtime such as five minutes.

If you want to reward every player upon each login with no minimum playtime, you would execute the following command. In this case I am going to give every player one diamond.

>/ontime rewards add item 1 diamond daily

If you want to make it such that they have to play for five minutes first, that command would be:

>/ontime rewards add item 1 diamond 5m daily

Weekly and Monthly Rewards

You can also reward players for playing a minimum amount of time on a weekly or monthly basis. So let’s say you want to give a player a diamond sword if they play a minimum of eight hours in a week, and you want to give them a “smite” enchanted diamond sword for playing a full day during a calendar month. To do this the following two rewards would be added:

>/ontime rewards add item 1 diamond_sword 8h weekly
>/ontime rewards add item 1 diamond_sword+17 1d monthly 

In both of these cases only one such reward will be issued to each player per week/month. Daily, weekly, and monthly rewards can be set up to be recurring with a fixed count, and would ‘reset’ for each player at the beginning of each day, week, or month.

>/ontime rewards add econ 100 1h daily
>/ontime rewards recur 1 1h count=3

The above example would reward a player with 100 coins for the first three hours of play each day. (The rewardID=1 assumes this is the only reward I currently have defined for my server.)

When measuring the time played for a week or a month, it is aligned to the calendar, not to when a player joins the server. You can configure how the plugin determines the first day of a week or month, and then the plugin will reset all of the weekly and monthly player data on those days. For example if you have the first day of the week set to be Mondays, the plugin will start measuring all players ‘weekly’ data at 12:01AM on Monday. If a player joins the server for the first time on Sunday and plays for 7 hours and 59 minutes that day, they would not get the diamond sword at 12:01 AM (00:01) on Monday because the 'weekly' count would have reset at midnight.

Rewarding Top Players

OnTime Rewards offers a system that allows you to regularly reward the top playtime, voting, or referring players on your server.

On my server I want to reward the top players every day (10 coins), every week (50 coins), every month (200 coins), and a bonus (5 diamonds) to the very top players on a weekly basis. For the daily and weekly rewards I want to give the same reward to the top three finishers.

To do this I first need to set up the four rewards, but in this case because they are going to the top players, no time stamp has to be specified.

/ontime rewards add econ 10 tag=topDaily
/ontime rewards add econ 50 tag=topWeekly
/ontime rewards add econ 200 tag=topMonthly
/ontime rewards add item 5 diamonds tag=topTotal

Now the rewards need to best up as 'top' rewards:

/ontime rewards top topDaily play daily 1 3
/ontime rewards top topWeekly play weekly 1 3
/ontime rewards top topMonthly play monthly 1
/ontime rewards top topTotal play total 1

In the first 'top' command above the '1 3' at the end indicates the top three positions (" 1 through 3") are to receive this top reward.

By default the 'top' rewards are issued on Mondays (weekly) and the first day of the month, and this is setup in the /plugins/OnTime/config.yml. The timing of the issuing of the 'top total' reward on a weekly basis is also set via the /plugins/OnTime/config.yml.

Linking Rewards

Admin givith and Admin takeith away

Often server admins want to grant temporary status to a player, this can be done by'linking’ OnTime rewards together.
Let’s pretend that on my server I want to encourage players to vote for my server by rewarding them with the ability to use (essentials) warps. Each time that a player votes they will get the ‘sethome’ permission, but if they don’t vote for a 24 hour period, they will lose the capability until they again cast a vote. Here’s how I do this:

/ontime rewards add addperm essentials.sethome
/ontime rewards votifier 1
/ontime rewards add rmperm essentials.sethome 1d real
/ontime rewards link 1 2

The first command establishes the ‘essentials.sethome’ permission grant reward to be issued immediately (no time specified). The second command makes this a ‘votifier’ reward such that it is granted each time a player votes at a ‘votifier’ supporting site. The third command is a ‘reward’ that removes (denies) the ‘essentials.sethome’ permission. This reward is configured to execute 24 hours of 'real' (clock) time, not OnTime (a.k.a. play time), later. The last command links the second reward to the first reward such that as soon as the first reward is delivered to the player, the second reward is scheduled.

Now regardless of the amount of time that a player plays if he does not cast a vote every 24 hours, he will lose the use of ‘sethome’. If the player is offline at the time it expires, he will lose the permission almost immediately upon his next login.

If the player votes on multiple sites during a single day, with each vote the ‘expiration’ of his use of 'sethome' will be reset to the full 24 hours.

Temporary Rank

Similarly, you can set up rewards to give players temporary membership to a permission group (rank). In this example I want to give players membership in the ‘VIP’ group if they play at least eight hours every week. This setup is as follows:

/ontime rewards add promotion VIP 8h weekly
/ontime rewards add demotion default 7d real
/ontime rewards link 1 2

The first command establishes the promotion to the VIP group, to be granted after eight hours of play each week. The second command will change the group back to the ‘default’ group after seven days. The last command links the two rewards together such that the clock to change back to ‘default’ will begin as soon as the player is placed into ‘VIP’.

Because it is a ‘real time’ seven day clock the player will be in the group for at least seven days. Each time a player hits the eight hours of play for a given week, the “VIP” group timer will be reset to seven days. They only time that a player may get ‘ripped off’ is if they log in something less than eight hours (say 7 hours and 59 min) by midnight on Sunday, and then play one more minute on Monday morning. The weekly counter will have reset at midnight and they would be back at zero Monday at 12:01AM. If this were to occur and a player complained, an admin can always ‘grant’ the reward manually using the ‘rewards set’ command.

/ontime rewards set 1 edge209 login

If the above command is run, upon my next login I would receive the promotion to the VIP group, and the 7 day timer would start.

If putting players into the "VIP" group manually is the 'normal' way to get them into that group, then this reward should be tagged as an 'individual' (or indi) reward, such that it is never given automatically by OnTime. This setting might be used if you are accepting donations and want to manually put people into the VIP group once you have received payment. The above reward would be declared 'indi' with the command:

/ontime rewards 1 indi

Where the '1' above is again the 'rewardID'.

There is one improvement I can make to this sequence. Right now when the person is demoted to 'default' the standard reward message is displayed on the players screen, congratulating them for their 'promotion'. In this case I want to give the user a special message that tells them why they have been demoted. Here's how I would do this:

/ontime message add back-to-default [player] you have been demoted to 'default' due to lack of playtime
/ontime message add back-to-default Play 8 hours this week and you will be back in VIP.
/ontime rewards edit 2 msg=back-to-default

The first two commands define a two line message with the message tag "back-to-default". The third command specifies that this message should be displayed when rewardID=2 is issued to a player.

The message created will be found in the file plugins/OnTime/messages.yml, and it can be modified etc. by directly editing that file, or it can be removed with 'ontime message remove back-to-default', and re entered if a error was made when you tried to create it.

If you find any part of this tutorial confusing, please open up a service ticket against this page, describe what you don't understand so I can both answer your question and improve the tutorial. - Edge

END TUTORIAL