OnTime Rewards

With this component of the OnTime plugin the server administrator can establish a system of rewards. Rewards can be issued in several ways:

  • A onetime event

Automatically issued when a player has been on the server for a specified amount of time, or number of different days.

  • A daily, weekly or monthly event

Automatically issued to all eligible players based on their amount of play time for the specified time scope.

  • A recurring event for a limited time frame

Automatically issued when a player has been on the server for a specified time, repeating at a specified interval until the next defined reward's time is achieved, or for a specified number of occurrences (count). These rewards can be scoped for total time (default), daily, weekly or monthly.

  • A perpetual event which is issued forever

Automatically issued when a player has been on the server for a specified time, repeating at a specified interval, continuing forever.

  • A onetime event for a specified player

Issued at an optional time in the future. (See 'individual' rewards below for details.)

  • A referral reward

As a reward for referring another player, but only after that player has been on the server for the specified amount of time.

  • A Votifier rewards

As a reward for voting for the server from a website (Votifier plugin required)

  • For Top Players

Issued to the 'top players' with the most playtime, points, referrals, or votes for the previous day, previous week, previous month and/or overall total.

  • When players are purged from OnTime Database

Issued at the same time players are removed from the OnTime database via the automated 'purge' function. Since a player is being removed due to lack of play, the only 'reward' type that makes sense is a 'command' reward. Using this function an administrator can define a 'command reward' in the rewards.yml , and then these commands can be executed on the player at the time they are purged. This could be used to remove players from other plugins' records such as a permission plugin.

  • When player is absent from the server (MySQL required)

At the start of each new day OnTime will check for 'rewards' of this type and issue them to any player that has not logged into the server (been absent) for a specified number of days.

  • Player death

Each time a player dies, they will receive rewards of this type.

  • Player purchase via a Reward Shop

When used in conjunction with the OnSign plugin, administrators can establish sign-based shops that allow players to receive OnTime rewards for a specified number of [|'loyalty' points]] or econ units (e.g. coins).

Reward Types

Rewards can be one of the following types.

  • an amount to be added or removed from a player's economy account
  • a quantity of a MineCraft item to be added to a player's inventory, including:
  • Enchanted Items
  • Potions
  • Item sub-types (e.g. chiseled stone)
  • a promotion to a specified group (rank up)
  • a demotion to a specified group (rank down)
  • a group added to a player's set of group memberships
  • a group removed from a player's set of group memberships

Automated Time-based Rewards

When a player logs into the system, the next automated OnTime Reward for which the player is eligible will be determined, and a system event will be scheduled to issue that reward at the right time. If a player quits or is kicked before their next reward time is reached, the reward event(s) will be automatically cancelled.

If "AFKCheck" is enabled, OnTime will determine when a player is Away From Keyboard (AFK) and will not include AFK time in Total OnTime nor will it be applied toward rewards. While AFK a player will never receive any rewards.

RewardIDs and Reward Tags

There are two ways to identify a reward when executing commands or viewing the current OnTime Rewards setup.


One identifier is the “RewardID”, which is a numerical ID based on time sorted order defined by OnTime. The current “RewardID” for all rewards can be seen by running the “/ontime rewards list” command. A given reward’s “RewardID” can change as reward definitions are added and removed from the OnTime Rewards system.


The second identifier is the “RewardTag”. A RewardTag is an alphanumeric tag (e.g. name) that is automatically set by OnTime, or manually set by the administrator. A RewardTag is permanently associated with a reward, and does not change unless modified by the administrator.

When a reward is “added”, the administrator can specify the RewardTag as part of the “/ontime rewards add” command.

For example: / ontime rewards add item 2 diamond 1h daily tag=dailyDiamond

The above reward will issue two diamonds to players each day that they accumulate one hour or more of playtime. If this is the only reward defined on the server, the RewardID = 1 and the RewardTag = dailyDiamond.

The administrator can take further action on this reward and use either the RewardID or RewardTag to identify the reward. So the following two commands, to get the details of the reward, are equivalent:

/ontime rewards info 1

/ontime rewards info dailyDiamond

If you forget the tags you have assigned, or want to see the tags assigned by OnTime, you can get this information with the following:

/ontime rewards list tags

If a tag is not specified when the reward is added, OnTime will automatically create a unique tag for the reward.

Any tag assigned to a reward can be changed using the “/ontime rewards edit” command. So if the admin wanted to change the tag from “dailyDiamond” to “2dailyDiamonds”, they could use either of these commands:

/ontime rewards edit 1 tag=2dailyDiamonds

/ontime rewards edit dailyDiamonds tag=2dailyDiamonds

Time Scope

Time-based rewards can be defined to occur upon different units, or time scope including: Total 'OnTime', Daily, Weekly, and Monthly

For example, a reward with time scope of 'daily' will be issued to all eligible players each day.

/ontime rewards add item 1 diamond daily 1h

The above command will create a reward that will give a player 1 diamond each day that player is online for at least one hour.

Without the ‘daily’ keyword above, the one diamond would have been given for the first hour of total play time on the server, and never issued again to the player.

Each of the four time scopes (total, daily, weekly, and monthly) are independent reward ‘streams’, so it is possible for a player to be simultaneously scheduled for one reward of each type of reward scope.

Perpetual and Recurring Rewards

There are two types of repeating rewards, Perpetual and Recurring, which are very similar, but have a couple of significant differences. Only command, econ, item, message, points and XP rewards can be defined repeating rewards.

Perpetual Rewards

A “perpetual” reward is a reward that is not issued a single time, but is issued continuously at a specified time interval, forever. To flag a reward as perpetual it must first be created using the '/ontime rewards add' command, where the target time specified is the time of the first occurrence of the reward. At the time it is "added" the reward will have its time scope set as total (default), daily, weekly, or monthly.

Once created, the reward is then flagged as perpetual using the '/ontime rewards perp' command. Specified in this command is the 'repeat' interval. Once a player's total OnTime reaches the 'target time' the reward will be issued, and it will be issued again as specified by the 'repeat' interval, and will continue to be issued on that interval, forever (or as long as your sever is up.)

It is possible to have multiple perpetual rewards active at one time.

Recurring Rewards

A recurring reward is pretty much the same as a perpetual reward, but there are a couple of major differences. A recurring reward is defined in the same way, such that it must first be created using the '/ontime rewards add' command. At the time it is "added" the reward will have its time scope set as total (default), daily, weekly, or monthly. The reward is then flagged as a 'recurring reward', but this time using the '/ontime rewards recur' command.

Once a player's play time corresponding to the scope of the reward reaches the reward’s 'target time', it will be issued for the first time. The recurring reward will be issued again as specified by the 'repeat' interval, but unlike the 'perpetual' rewards, it will only continue to be issued until the target time of the next reward in chronological order and of the same scope, is reached. Because of this limit, only one 'recurring' reward per scope type is ever active at one time.

Example: A recurring reward of $100, scoped for total time played, is defined to start at 1 day 0 hour 0 min with a recurrence time of 0 days 4 hours 0 minutes, and a second reward, also scoped for total time played, of $200 is defined to happen one time at 2 days 0 hours 0 min. Once the player has been on for 1 day they will receive a $100 reward every 4 hours until they have been on the server for 2 days, at which time they will received a $200 reward. If there are no other rewards defined after this second one, the player would never receive another reward.

Commands for this example:

/ontime rewards add econ 100 total 1d tag=econ100
/ontime rewards recur econ100 4h
/ontime rewards add econ 200 2d


  • In the third command the time scope (e.g. total, daily, weekly, monthly) was omitted, so the default "total" will be applied.

    Recurring rewards come with a feature that allows the administrator to specify that the reward should be issued a fixed number of times and stop. So, it is possible to have a recurring reward be issued, for example, every 10 minutes for one hour and then stop.

    Finally there is one aspect of recurring rewards about which you should be aware. If a recurring reward is the last reward in chronological order defined, and no count limit is set, it will continue to repeat forever like a perpetual reward. This happens because there is no 'next' reward to cancel the repeating aspect of the reward.

Individual or 'Indi' Rewards

An individual reward is a single occurrence award that is only given to a single, specified player. The rewards that can be issued are the same as those that are automated; in fact the administrator can select one of the automated rewards and issue the specified user the reward at almost any time. A reward once added to the list can also be identified as an 'individual only' reward such that it is never issued automatically. Individual rewards are one time only so even if the reward 'set' is a recurring reward, the set instance will not repeat.

When an individual reward is specified for a player, the admin has several options to determine when the reward will be issued. This is known as the “time reference”.

  • Delta - A 'delta' time setting will issue the reward when the specified player has be on the server that much time longer then their current Total Ontime.
  • Login - A 'login' setting will issue the reward the next time the player logs onto the server. (No time stamp is specified with this option.) If the player is online at the time the reward is setup, they will have to logoff and then log back on to receive the reward.
  • OnTime - An 'ontime' setting will issue the reward when the specified player's Total OnTime reaches that value. This is the setting most similar to the automated rewards. (This is synonymous with ‘total’ play time.)
  • Real - A 'real' setting will issue the reward according to the server, or 'real' time. Similar to the 'delta' setting this is an amount of time that must pass before the reward is issued. The 'clock' will be ticking for this reward regardless if the player is on line or not. If the player is offline when the timer expires, the reward will be issued when the user next logs on.

For this example, I will be using a pre-set list of OnTime Rewards:

\ontime rewards list

2013-01-25 22:50:22 [INFO] #1 Total: 2D 2M             R: 1 of DIAMOND (RA)
2013-01-25 22:50:22 [INFO]    Interval:  4  Hr
2013-01-25 22:50:22 [INFO] #2 Total: 5D                R: 100  (RA)
2013-01-25 22:50:22 [INFO]    Interval:  4  Hr
2013-01-25 22:50:22 [INFO] #3 Total: 6D                R: 5 of COAL (SA)
2013-01-25 22:50:22 [INFO] #4 Total: 10D               R: 100 XP (SA)
2013-01-25 22:50:22 [INFO] #5 Total:  (Individual)     R: 100  (IA)

  • > ontime rewards set edge209 delta 4 1h

This command will create a single occurrence of the Reward #4 to happen for edge209 in 0 days 1 hour 0 minutes of additional time on the server. This player and all other players will still receive the same reward #4 when they get to 10 days on the server.

  • > ontime rewards set edge209 real 5 5h

This command will create a single reward for edge209, which will happen 5 hours of real (server) time in the future, regardless of Edge209's amount of OnTime. Only rewards 'set' in this manner can deliver a RewardID= #5, as this reward will be give automatically.

The following command is what makes a reward an 'individual reward' only.

  • > ontime rewards indi <RewardID / RewardTag>

Exclusive Rewards

'Exclusive' rewards are controlled via group-based permissions, and OnTime is compatible with a large number of 'permissions' plugins via Vault. When a reward is defined as exclusive, a permission string is automatically generated, which can be used in the permission plugin's config files or commands.

The command string will be of the format: 'ontime.reward.<rewardTag>'. <rewardTag> can be defined by the admin, or it can be auto-generated by OnTime. The RewardTag can be found in the 'rewards.yml' file, or displayed using the “/ontime rewards info <rewardID/[ALL]>” or “ontime rewards list tags” commands.

To make management easier, the applicable groups can be listed in the OnTime command which sets the 'exclusive' mode, and OnTime will update the permissions config files directly.

(ex: "/ontime rewards exclusive add 1 builder", where "1" is the exclusive reward's RewardID, and 'builder' is the permission group to have access to reward #1)

After exclusive rewards are defined, only members of groups which have the associated permissions string for a reward, will receive that reward. For all other players, who don't have the right permission, the exclusive rewards will be skipped.

To see the reward's permission string as well as the groups which have this permission the following command can be used:
"/ontime rewards info <RewardID / RewardTag>

World Specific Rewards

An administrator can specify that a particular reward should only be issued to a player when they are in a specific world of the server. This is handy for example where it does not make sense to reward a player with items when they are in a creative world, yet the admin still wants the player to be rewarded for the time spent playing creative.

The default behavior for these rewards is such that when a player is in a world other than the 'specific' world for a reward, they will be informed that they are now eligible to receive the reward, but the issue of the reward will be put on hold. When the player next enters the world where the reward is valid, the will immediately receive the reward and be reminded that they had earned the reward while in some other world.

The world where the reward is valid can be specified at the time that the reward is defined, or later using the "ontime rewards edit" command.

It is also possible to define the reward such that when a player is in a world other than the 'specific' world for a reward (a.k.a. off-world), the reward will be discarded, and the player will never be aware that they missed out on a reward. With this method it is possible to set up different rewards for the same event, such as Votifier vote, for each world and the player would only receive the one reward for the world they currently occupy when at the time that the vote is cast.
This above setting is achieved by appending a "+" to the front of the name of the world when it is specified at the time of reward definition, or use of the "ontime rewards edit" command. (e.g. /ontime rewards add item 1 diamond 1h world=+PVPWorld)
When the "/ontime reward info" command is used in order to see the details of a reward, the valid world for a reward will be shown. If the reward is valid for all worlds, no 'world' information is displayed.

'Days On' Rewards

Players can receive rewards for joining the server for a specified number of days. In this case it does not matter how much time they spend on the server each day, just that they have logged onto the sever that many different days.
For example you want to reward players for logging into the server on seven different days, then you would use the command:
/ontime rewards dayson <RewardID / RewardTag> 7d

'Referred By' Rewards

Players can receive reward(s) for referring other players to your server. (Please see the 'Referred By' page for more details on how to use this feature.) To define a reward as a 'referred by' reward, the following command must be executed:

/ontime reward refer <RewardID / RewardTag> {[source/target]} {[count=]<count>}

'Referred by' rewards will never be awarded automatically, and will only be used as referral rewards. The “[source /target]” specifies if this is a reward intended for the player who made the referral (source), or the player that was referred (target).
The 'count=<count>' is an optional parameter which specifies the number of successful referrals that must be provided by a player before they will receive the reward. The MySQL dataStorage option is required to use this 'count' function.

'Purge' Rewards

A 'purge' reward will be issued at the same time that players are removed from the OnTime database via the automated 'purge' function. Since a player is being removed due to lack of play, the only 'reward' type that makes sense is a 'command' reward. Using this function an administrator can define a 'command' reward in the rewards.yml , and then these commands can be executed on the player at the time they are purged. This could be used to remove players from other plugins' records such as a permission plugin.


Let’s say I am using the GroupManager permissions plugin, and I want OnTime to clean up that database when players are purged due to lack of playtime.

I would first need to hand edit the rewards.yml as follows under the "commands" keyword:

    - deleteGM:'manudel [player]'

I would next execute the following:

/ontime reload rewards
/ontime rewards add command deleteGM tag=deleteGMrw
/ontime rewards purge deleteGMrw

Now the next time OnTime purges players from its database, it will run this command on each of the players, and hence also remove them from GroupManager's records.

'Top Player' Rewards

The players on your server which log the most playtime, points, referrals, or votes for a given day, week, month, and/or total, can be rewarded for their dedication. At the start of each new day, OnTime will look for any 'top' rewards and issue them as appropriate per the configuration. If Reports are enabled, these rewards will be issued at the same time that any auto reports are generated so that the players receiving rewards are the same as those appearing at the tops of the reports.

After a reward has been added, the following command is used to define it as a 'top player' reward:

Command to set up: ontime rewards top <RewardID / RewardTag> [play/point/refer/vote] [daily/weekly/monthly/total] <startPlace> {<endPlace>}


<rewardID> = is the reward order number shown in the "/ontime rewards list" command. <RewardTag> is the tag defined by the admin or automatically by OnTime

[play/point/refer/vote] is the 'event' for the reward where play= playtime (OnTime), point = loyalty points, refer = referrals of other players, and vote=votifier votes

[daily/weekly/monthly/total] is the 'top list' to be used as the source for players to receive rewards

<startPlace> is the number (1,2,3, etc) of the player position in the list (1st, 2nd, 3rd) to receive this reward

For 'top points', only 'total' is supported because OnTime does not collect daily, weekly, or monthly point totals.

<endPlace> is optional, and if used will create a range of player positions, between and including <startPlace> and <endPlace> to receive the same reward.

In the /plugin/ontime/config.yml the administrator can enable each of the 'top reward' types (daily, weekly, etc.) independently, and they can set the day of the week (firtsDayofWeek) and day of the month (firstDayofMonth), when the weekly and monthly rewards should be issued. This is the same parameter used to determine when the auto-reports are generated.

Also in the config.yml the 'time period' for the issuing of rewards to the 'top players' with the highest total playtime, points, referrals, or votes should receive rewards (totalTopPlayReward, totalTopPointReward, totalTopVoteReward, totalTopReferReward), must be set by the administrator. Based on this setting 'total top' rewards will be issued daily, weekly, or monthly.

Votifier Rewards

OnTime supports the Votifier plugin through an integrated listener, and command support to specify the Votifier Rewards. Just like the other reward definitions, the first step is to create a reward using the '/ontime rewards add' command. Once created the reward is designated as a Votifier reward using a command specialized for this purpose: '/ontime rewards votifier'.

Once this is set up the rewards flagged as 'Votifier rewards' will be issued to players each time they vote through websites which support the Votifier plugin such as MineStats and PlanetMineCraft. The players will need to have racked up the required total playtime set as part of the '/ontime rewards add' command, and on most systems this is set to 0 Day 0 Hours 0 Minutes, such that even the newest of players will be rewarded for voting.

Votifier rewards can be specified to be 'exclusive' just as any other rewards, such that players that are members of certain groups will be able to receive such rewards.

There is no limit to the number of rewards that can be set up as Votifier rewards, and when a player votes they will receive each of the votifier rewards for which they are eligible. What this means is that you can set up different Votifier rewards and using the 'exclusive' function you can then have different rewards for different groups of players. In other words you can reward your donators differently then how you reward a noobie.

Similar to the referral rewards, a 'vote' count can be specified in the definition of the reward, which means that the reward will not be issued to a player until they have voted that many times. Players will be rewarded each in the future for each "batch" of votes equal to the count. (e.g. if the count=5, they would receive this reward on their 5th, 10th, 15th, etc vote.) The MySQL dataStorage option is required to use this 'count' function.

If the admin wants to define a votifier reward to not repeat every “x” votes, but only issue one time on a specific count, then they must specify that it is a “single” instance only. For example:

/ ontime rewards add item 1 diamond tag=voteDiamond
/ ontime rewards votifier voteDiamond count=5 single

Absence Rewards

Absence 'rewards' are the opposite of other play time rewards as they are issued due to a lack of play by a player. At the start of each new day OnTime will determine which players meet the definition of the absence reward based upon the player's last login date. If they have not been on the server for the number of days or greater, as defined in the 'reward' it will be issued to the player per the following:

Rewards of the following types will only be issued once per absent player: addgroup, rmgroup, permission, denial, promotion, demotion, message, and Command

Rewards of the following types will be issued every day the player is considered absent: econ and points

Rewards of the following types cannot be 'absence' rewards: Item, Kit, XP


On my server I am using "points" to track which players are most loyal to my server. But I don't want players that are no longer active to retain leadership at the top of my 'points' leader boards. So for every day they are absent longer than a week, I want them to lose 100 'points'. To do this I need this command:

/ontime rewards add points -100 8d absence

With this command 100 points will be deducted from their point total starting on their 8th day absent from the sever, and deducted every day until they again log in.


On my server I want to take away privileges from a player that has not been on the server for a long time (30 days or more). So, I have created special permissions group called 'limbo', which has a very limited set of permissions. This will force those players to talk to an admin or moderator before they can be reinstated to their prior rank or some other rank.

/ontime rewards add demotion limbo 30d absence

Death Rewards

Death rewards (or penalties) are issued each time a player dies on the server.


On my server I use a point system to track my best players, I want to encourage players to engage in PvP, so every time a player dies, I want them to lose 10 points. I do this with the following command:

/ontime rewards add points -10 death

Linking Rewards

OnTime provides the advanced capability of linking two or more rewards together. Linked rewards are issued as a chain, with each link scheduled when the reward in front of it is issued. This capability was created initially to support servers that wanted to grant temporary use of a permission, or temporary rank membership. Please see this tutorialfor examples and the commands used to create reward chains.

Economy Rewards Notes

The OnTime plugin uses the Vault economy plugin, so any economy systems compatible with Vault are therefore supported by OnTime. An econ reward can be further defined to be recurring, such the same reward is issued at each recurring time period.
See here for more information on ways to use economy rewards.

Item Rewards Notes

The item can be specified using the item NAME or item ID. An item reward can also be further defined to be recurring, such the same reward is issued at each recurrent time period.

If at the time that an item reward is issued to a player the player's inventory is completely full, the user will be informed of the pending reward, and the plugin will try to issue the reward again in 1 minute. The plugin will re-try every minute until the player makes room in their inventory to receive the reward.

Enchanted Items

Enchanted items can be used as rewards too! When the item reward is defined an enchantment number (or numbers) can be added to the item name or number. Examples:

  • A 'power' enchanted bow reward at 0D 1H 0M:

/ontime rewards add 1 bow+48 1h

  • An 'efficiency' and 'unbreaking' shovel reward at 0D 2H 0M:

/ontime rewards add 1 shovel+32+34 2h

The enchantment codes can be easily learned by using the command:

/ontime help enchant


Adding potion reward is very similar to enchanted items! When the potion reward is defined an potion number simply needs to be added. Examples:

  • A 'harming' potion reward at 0D 1H 0M:

/ontime rewards add 1 potion+8204 1h

  • A 'strength potion II' reward at 0D 2H 0M:

/ontime rewards add 1 potion+8233 2h

The potion codes can be easily learned by using the command:

/ontime help potion

Item Data

What is known as "damage" data can also be added to any item. This data is used to define different 'flavors' of certain items Examples:

  • Chiseled Stone Block (5) reward at 0D 1H 20M:

/ontime rewards add 5 stone+3 1h 20m

  • A pink wool reward (8 units) at 0D 2H 0M:

/ontime rewards add 8 wool:6 2h

The item codes can be easily learned by using the command:

/ontime help <item>

Kit Rewards Notes

A 'kit' is a collection of MineCraft items that can be rewarded to a player as a set. Currently, kits can only be defined by directly editing the /ontime/rewards.yml file. The format of this section of the yml is:

   - <kitname>,<item count>,<item 1 quantity>,<item 1>,<item 2 quantity>,<item 2> ....


  • kitname = any name you want to give the kit
  • item count = number of items in the kit
  • item 'x' quantity = quantity of items to give
  • item 'x' = item to give

The "item 'x' quantity" and "item 'x'" pair is repeated for the number of times equal to the 'count'



When editing of the /ontime/rewards.yml is complete, the new data can be loaded into the plugin with the command:

>/ontime reload rewards

The plugin will validate that all of the items specified are correct, and if they are not ALL kits defined will be disabled until ALL kits are correct.

Group , Permission & Denial Reward Notes

The OnTime plugin uses the Vault permissions plugin, so any permission systems compatible with Vault are therefore supported by OnTime. A Vault supported permission plugin is required for this OnTime function to be available.

Add Group, Remove Group, Add Permission, Remove Permission (Denial), Promotion and Demotion rewards are onetime events, so these cannot be defined as recurring.

A ‘denial’ reward is the opposite of a ‘permission’ reward and serves to take a permission away from a player.

Because there are countless permissions out there, no validity checking is done on the string entered. So any incorrect permission specifications will not be detected by OnTime. You will also never see any error messages from an incorrect permission spelling, so be careful.

For the Add Group, Remove Group, Promotion and Demotion rewards to work, the names of the different groups used by the system must be included in the rewards.yml file found in the '/plugins/ontime' directory. It is very important that the groups be listed in order from lowest to highest. The reason for this is that a player should never be automatically 'promoted' to a group which is lower than their currently assigned group, or 'demoted' to a higher group. This logic should help maintain group assignments made prior to adding OnTime to your plugin list. The only way to add the groups to the rewards.yml is by editing the file directly.

There is special handling provided for players which may have been purged from the OnTime records (due to lack of play), yet retained a high rank. For this case administrators can configure OnTime to automatically place players into a specified group when they next log into the system.
from config.yml

# Enable if purged players should be auto-demoted
purgeDemotionEnable: true

# If purgeDemotion is enabled, this is target group for demotion
purgeDemotionGroup: default

By setting 'purgeDemotionEnable: true' and specifying a target group, 'default' being the actual name of the group in this case, when players with no OnTime record join the server, they will be put into the default group and removed from their currently highest level priority group.

Special Note for PermissionsBukkit Users

When there is a new player with no previous record when using the PermissionsBukkit plugin, they don't show up in the permissions/config.yml until after they are put into their first group, but when this happens the 'default' group is still listed. This causes a conflict within OnTime.

You can fix this by adding a new reward to force those new players into the 'default' group making the PermissionsBukkit create an entry for them. So try this:

/ontime rewards add group default 1m

So after their first minute of play they will be pushed into the default group. When the next promotion happens, the 'remove' from 'default' will work because there will actually be a record of them being in that group.

Command Rewards Notes

'Reward' may not be the right term since a command could be almost anything, but I'll call 'em rewards to be consistent. For command rewards to be available they must first be defined in the rewards.yml file under the "commands:" keyword. The format for these definitions is:

- <commandTag>:'<command> <parameter> [player] [voteSource] <parameter>'

<commandTag> is a string identifier you create for the command. This is the string used in the '/ontime rewards add' command to define a reward of this type.

<command> is the command you want to execute. This can be almost* any command supported by your server.

<parameter> is any parameters required by the command you want to be executed

'[player]' will be replaced with the target player's when the command is executed.

"[voteSource]" is only valid when associated with a 'votifier' reward. This variable will be replaced with the source website of the vote being rewarded by OnTime.

I say 'almost' because if there are more variables needed other than '[player]' it may not be possible to create a working reward for some commands.


- creative:'creative [player]'
- kill:'kill [player]' (Ok, not really a good reward. :-) )

Please note that the (') are required and that there must be no space before or after these marks.

Unlike the rest of the rewards there is no in game notice sent to the player when the command happens. I figure that the command itself will already have appropriate messages.

Message Reward Notes

A message reward is simply that, a message that is displayed to a user based on their time played. The messages are defined in the plugins/OnTime/messages.yml file, and can be created by editing that file, or managed using the in game/console ‘/ontime message ’ command set.

Other Notes

Reward Messages

Default Reward Messages

By default OnTime will automatically issue a pre-defined message to a player when they receive a reward. There is a different message for each type of reward, and administrators can customize these messages by editing the plugins/OnTime/output.yml file. OnTime supports a configuration in the config.yml that can disable all reward messaging if desired.

Community Reward Broadcast

By default OnTime will also broadcast messages to all online users when some rewards are issued to other players. The rewards that support broadcast are:

  • AFK Status
  • Top Daily
  • Top Weekly
  • Top Monthly
  • Top Total
  • Group Changes
  • Referred By (Source and Target)
  • Votifier

These broadcast messages can be enabled/disabled fully via the config.yml, or individual messages can be disabled by editing the output.yml file. To disable an individual broadcast message the "lines" setting associated with a specific message should be set to zero .

Reward Unique Messaging

It is also possible to create unique messaging to be displayed to a user on a per-reward basis, and OnTime supports the ability to turn off messaging for a specified rewards.
Using the OnTime Messaging feature the admin can create and manage any number of different messages that can be displayed to players. These messages can be created via in game/console commands, or by directly editing the /plugins/OnTime/messages.yml file.

For example if you would like to give some special thanks to your subscribing VIP players when they join each day, the following could be set up:

/ ontime message add VIP-thanks Thank you [player] for your donation! Here is your daily diamond.
/ ontime rewards add item 1 diamond daily msg=VIP-thanks
/ ontime rewards exclusive 1 add VIP

The first command above defines a message with the msgTag=VIP-thanks. When it is displayed, "[player]" will be replaced with the player's in-game name.

The second command defines a reward of one diamond to be issued daily. Because no time is specified it will be issued upon the players first login each day. Instead of displaying the standard message defined in output.yml for item rewards, the "VIP-thanks" message will be displayed.

The last command makes this reward exclusive to the VIP group, such that only members of that group will receive this reward. The "1" is the rewardID , as I am assuming this is the only reward defined on my server.

Disabling Messages Per Reward

It is possible to disable the displaying of messages for a specific reward. This may be useful if you want to issue a number of different rewards to a player at one time, but only want to send them one message. For example, when a player votes for my server I want to reward them with 1 diamond and 1000 XP, but I don't want to see the two different votifier messages that would normally be displayed. Here is what I could do to achieve this:

/ontime message add vote-reward [player] thank you for voting! 
/ontime message add vote-reward Here is your gift of one diamond and 1000 XP!
/ontime rw add item 1 diamond msg=off tag=vote1Diamond
/ontime rewards add xp 1000 msg=vote-reward tag=vote1Kxp
/ontime rewards votifier vote1Diamond
/ontime rewards votifier vote1Kxp

Here is what these command achieve:

  1. Creates a message with msgTag of "vote-reward"
  2. Adds a second line to the message
  3. Creates a reward of one diamond. When this reward is issued no message will be displayed to the player (msg=off), and no broadcast message will be sent to the community.
  4. Creates a reward of 1000 XP. When this reward is issued, the "vote-reward" message will be displayed to the player instead of the standard 'votifier' message, but no message will be broadcast to the community. Currently there is no support for customized messages for broadcast, so when a custom message is used broadcasting is disabled for that reward.
  5. Defines the first reward (RewardTag=’vote1Diamond’) as a votifier reward.
  6. Defines the second reward (RewardTag=’vote1Kxp’) as a votifier reward.

Changing Messaging for Existing Rewards

For rewards that may already be defined for which the admin wants to change the messages displayed, this can be done using the "rewards edit" command. For example:

/ontime rewards edit 1 msg=vote-reward
/ontime rewards edit vote1Kxp msg=off
/ontime rewards edit 3 msg=default
  1. This first command will now have the "vote-reward" message displayed when that reward is issued.
  2. The next command will turn off messaging for the RewardTag = ‘vote1Kxp’.
  3. The third command will use the default message found in output.yml for the reward with ID=3.

Reward Recalculation

Each time a reward is added or removed in game, the rewards for all online players are automatically recalculated to take into account the changes.
Rewards can also be recalculated by issuing the "/ontime reload rewards" command.


It is possible to control what players are eligible to receive the OnTime Rewards via permissions, so this capability can be reserved for certain classes or groups already established on the server. 'ontime.rewards.receive' is set to true by default, but this could be removed for groups or individuals you do not want to receive rewards. See the permissions page for more information.

Per-world Enable

It is possible to enable and disable rewards on a per-world basis. This is set via the 'worlds' keyword found within the '/plugins/ontime/rewards.yml' file. By default this is set to "- global", which will apply rewards on a ‘global’ basis, and is used for permission plugins that support a ‘global’ concept for worlds.

Alternatively this could be set to "- all", in which case all rewards will be issued and applied equally to all worlds defined on your server. This is the setting that should be used for permission plugins that do not support a ‘global’ set of permission concept, yet you want all worlds to support rewards. The third option is to list out all of the worlds where you want rewards issued and applied. In this case a player will only receive a reward for which he becomes eligible if he is also in an reward enabled world at that time, otherwise the reward will be forfeit. The one exception to the 'forfeit' rule is that a player will receive promotion/demotion rewards for which he has qualified the next time he logs into the server, entering a world where OnTime rewards are enabled.


(from rewards.yml)

# Worlds enabled for Rewards
   - edgeLand
   - edgeWorld

For the above settings as long as a player is playing in the worlds 'edgeLand' and 'edgeWorld' will they receive rewards.


Posts Quoted:
Clear All Quotes