Tutorials/3. Auto Rank - Group Promotions

Group/Rank Promotions

The OnTime Rewards system provides the capability to generate group (rank) promotions automatically based upon the total playtime a player has on your serve, or as a reward for voting and making player referrals. In this tutorial I will explain how to set up some basic and some more advanced ranking systems.

In this tutorial I will cover:

  • Configuration setup for group/rank auto promotions.
  • Creation of regular (standard) OnTime Automated Promotions
  • Creation of multiple independent rank ladders
  • Setup for automated demotion to a lower rank for players absent for a long time

Permissions Plugin & Vault

You must have a permissions plugin such as GroupManager, bPermissions, PAX, etc. installed on your server for this part of OnTime to have any purpose. You must also install on your server, the plugin "Vault", as it is the glue that enables OnTime to work with the permissions plugin of your choice.

Example for the Basic Auto Promotion Tutorial

The first part of this tutorial will be 'implementing' the following promotion schema:

My server "EdgeCraft" has the following groups:

  • Regular player groups: 'default', 'noobie', 'builder', and 'trusted'
  • Donor groups: 'BronzeDonor', 'SilverDoner', and 'GoldDoner'
  • Staff groups: 'moderator', 'admin', and 'owner'.

    My 'basic' promotion scheme is:

default -> noobie after 30 minutes of play time.
noobie -> builder after 1 hour of play time.
builder -> trusted after 1 day of play time.

For the rest of the groups there should be no automated promotion/demotion out of those groups. (The second part of this tutorial will add some changes for those.)



The base plugin configuration is found in /plugin/ontime/config.yml, and there are a couple of things that need to be set here to enable the rewards system. When first downloaded, the plugin has the rewards system 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 get a reward, that must be enabled too.

from config.yml
# Enable if OnTime Rewards system to be enabled
rewardsEnable: true

# Enable if Reward Notification Messages to players should be displayed
rewardNotifyEnable: true


There is an additional configuration file, plugin/ontime/rewards.yml, that is used to configure the various pieces of the OnTime Rewards system. In here is a very key piece to the automated rank/group promotion solution. This file contains an ordered list of the groups defined for your permissions plugin. Not all defined groups must be listed, but it is highly recommended that you do list every group within the ontime/rewards.yml.

The order of this list is from the lowest rank (first) to the highest rank (last). This order matters because OnTime will never auto-promote a player from a higher rank to a lower rank, or auto-demote a player from a lower rank to a higher rank. So for example if you have a new player (with no OnTime record) and you assign them as a moderator, they will not be 'promoted' to noobie after they have logged 30 minutes of playtime. This promotion does not happen because moderator is below noobie in the groups list (as shown below).

from rewards.yml
  - default
  - noobie
  - builder
  - trusted
  - BronzeDonor
  - SilverDonor
  - GoldDonor
  - moderator
  - admin
  - owner

NOTE: It is very important that you include at the bottom of the group list those groups you DO NOT want subject to promotions. In the example above I have added moderator, admin, and owner to the bottom of the (making them the highest rank), so that these groups will not be subject to any rewards which target the groups listed above them.

This is the only modification you need to make directly to the /plugin/ontime/rewards.yml

The resulting rewards.yml for this full tutorial can be found here.

Creating Promotion Rewards

Now all that is left to do is to set up the promotion rewards. This can be done by executing the following commands from the server console or in-game from a player account with ontime.rewards.admin permission.

command syntax

ontime rewards add promotion <group> {<dd>d <hh>h <mm>m}

Commands to execute:

ontime rewards add promotion noobie 30m

ontime rewards add promotion builder 1h

ontime rewards add promotion trusted 1d

That's it! Any (non-donor and non-staff) player joining EdgeCraft at this point will be auto-promoted.

Viewing Promotion Rewards

Viewing these rewards is the same as for the 'standard' rewards, so please look here for more information.

Example for Multiple / Separate Ladders

In this part of the tutorial I will explain how to set up a separate promotion ladder for the donor groups in the example EdgeCraft server.

In this new ladder I want the following promotions:

BronzeDonor -> SilverDonor after two days of total playtime.

SilverDoner -> GoldDoner after three days of total playtime.

rewards.yml and config.yml

Because I have already listed all of the defined groups in /plugin/ontime/rewards.yml, there are no changes to be made to that file, nor is there anything to change in /plugin/ontime/config.yml

Creating Donor Promotion Rewards

First I need to execute some more commands from the console or in-game to create the promotions as follows:
Commands to execute:

    ontime rewards add promotion SilverDonor 2d tag=silverPromo
    ontime rewards add promotion GoldDonor 3d tag=goldPromo

If I were to stop here, then non-donor players would be promoted to SilverDonor and GoldDonor groups after they had put in the required playtime. To prevent this I need to modify these rewards to make them 'exclusive'.

An 'exclusive' reward is granted only to members of certain groups, but not to all groups.

RewardID and 'ontime rewards list'

But before I can fix it so that the non-donors do not get these promotions I need to take a slight tangent in the tutorial, and talk about the RewardsID.

To make modifications to existing alarms, you need to know the RewardID of the reward you want to change. The RewardID is number assigned by the plugin, and is based on the time-sorted order of all rewards.

ontime rewards list command:

\ontime rewards list

For the rewards I have created in this tutorial the list will look like this:

ontime rewards list
The RewardID is the list order number (1 - 5) shown at the front of each line in the above output.

Making Rewards Exclusive

So to stop non-donors from getting these promotions the following commands are executed:

    ontime rewards exclusive 4 add BronzeDonor
    ontime rewards exclusive 5 add SilverDonor

Alternatively I can use the assigned RewardTags, instead of the RewardID for the above commands:

ontime rewards exclusive silverPromo add BronzeDonor

ontime rewards exclusive goldPromo add SilverDonor

The first command above will make the promotion to SilverDonor (RewardID #4) "exclusive" to the BronzeDonor group.

The second command above will make the promotion to GoldDonor (RewardID #5) "exclusive" to the SilverDonor group.

In other words only members of the "BronzeDonor" group will ever receive a promotion to "SilverGroup", and only "SilverGroup" members will ever receive a promotion to "GoldGroup".

Now with this setup, you will have one promotion ladder: default -> builder -> trusted, and another ladder BronzeDonor -> SilverDonor -> GoldDonor.

Because there are no rewards defined that have a 'target' group set as BronzeDonor, moderator, admin, or owner, the only way to get into these groups is through your standard group assignment methods.

Group Demotion (After Purge)

OnTime has a purge function which automatically removes players from the OnTime database if they do not meet a minimum amount of playtime, or have been away from the server for a configurable amount of time. For this latter case where players have not been on for a long time, server owners may not want those players to retain their higher group status, so OnTime provides a special function to demote these players.

For my 'EdgeCraft' server I have the auto purge set for 60 days. Which means all players that have not been on the server for this long, will be automatically removed from the OnTime database. I also want them demoted back to the 'default' group.

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.