Breeding Competition on Atomix
- By nature, Atomix is a competitive server with a heavy emphasis placed on player achievement and rivalry.
- The purpose of the web leaderboards was to further emphasize that competition and encourage players to get on their grind and climb the rankings.
- Through the collaboration with a freelancing web developer, we successfully developed a variety of leaderboards that encompassed 10 stats that players could compete on.
- These leaderboards successfully broke down stats into hourly, daily, weekly, and monthly timeframes by linking to our leaderboards software and utilizing an API.
How the Leaderboards Pipeline Works
Every number on the website and every reward paid out comes from one place: the leaderboards database kept by the ajLeaderboards plugin. Our proprietary plugin sits on top of ajLeaderboards, reads that database through its API, and feeds the same ranked values to two consumers: the public web page and the timed reward draws.
%placeholder%alltime, hourly, daily, weekly, monthlyTopManagerConsumer A: the leaderboards web page
The plugin passes the ranked values for 10 stats to the website, which shows each one by hour, day, week and month. Because the web page and the in-game menus read the same database, a player sees the same standings in both places.
Consumer B: timed reward draws
On daily, weekly and monthly schedules, the plugin reads the finished period's standings from the database, picks the winners, hands out the rewards and notifies the players. The board then resets and the next period starts accumulating.
What ajLeaderboards provides (from its wiki)
Boards come from placeholders
A board is created from any PlaceholderAPI placeholder that returns a plain number, registered with /ajlb add. The plugin records that value per player and sorts it, so a stat only needs to be exposed as a number to be ranked.
Timed boards reset on their own
Each board is tracked as alltime, hourly, daily, weekly, monthly and yearly. Timed boards reset automatically at each interval without touching the all-time totals.
Only cumulative stats can be timed
The wiki warns that timed boards only make sense for stats that keep adding up, such as kills or votes. A high-score style stat belongs on the all-time board only, so the stats that get timeframes have to be cumulative ones.
Display placeholders for menus
Positions are readable as %ajlb_lb_<board>_<number>_<type>_name% and _value%, and %ajlb_reset_<type>% shows the time until a timeframe resets. These feed the in-game menus and countdowns.
The API calls that map to this system
Taken from the ajLeaderboards Javadoc for its TopManager class. These are the documented read calls that correspond to what the website and the reward draws each need.
| API call | Returns | Why it matters here |
|---|---|---|
getStat(position, board, type) | The entry at a rank | Fills each row of a web leaderboard and identifies who holds first, second and third place for a reward draw. |
getStatEntry(player, board, type) | One player's entry | Looks up a single player's standing for menus and personal stats. |
getBoardSize(board) | Number of players on a board | Tells you how many ranks exist, which sizes the table. |
getLastReset(board, type) | Time of the last reset | Marks the period boundary, which is what a reward draw has to line up with. |
getCachedStat(...) variants | A cached entry | Serves repeated reads without hitting the database each time. |
Timed rewards: daily, weekly and monthly
Daily draw
- Stats accumulate in the daily board all day.
- At the period end the plugin reads the top positions.
- Rewards are given and the winner is notified.
- The board resets for the next day.
Weekly draw
- The same stat accumulates across the whole week.
- At the period end the plugin reads the top positions.
- Rewards are given and the winner is notified.
- The board resets for the next week.
Monthly draw
- The same stat accumulates across the whole month.
- At the period end the plugin reads the top positions.
- Rewards are given and the winner is notified.
- The board resets for the next month.
Details that took care
Draw timing
Timed boards reset on a schedule, so when the winners are drawn matters. Rewards were once not being given, and the change log pins it on timing: “fixed leaderboard rewards not being given (it had to do with the timing of when the winners were drawn)”.
Ties in the top three
Two players can finish with identical totals. Rewards were updated to cover players who tie in a top-three position instead of picking one arbitrarily.
Countdowns for players
Placeholders show when the next reward drawing happens, so the draw is visible and predictable rather than a surprise. A notification tells players when they win.
Fresher numbers
The update method behind the boards was changed to give more real-time stats. Player heads were removed from the leaderboard menus to speed up how quickly they load.
Website accuracy
The web page is only trustworthy if its numbers are right, so a wrong mob kills stat on the site was fixed, and incorrect values in the Leaderboard Hub menu were corrected.
One source of truth
Menus, web page and rewards read the same database. That keeps the site and the game from disagreeing about who is winning.
How it evolved (from the change log)
- July 2023: leaderboard rewards are announced, then implemented a few days later. The /leaderboards menu is edited to show the rewards for top players in several categories.
- October 2023 to February 2024: placeholders added that show when the next reward drawing is, rewards extended to ties in the top three, the update method changed for more real-time stats, and the menus changed to show daily, weekly and monthly top competitors.
- Late February 2024: a notification added for reward winners, and the draw timing bug fixed.
The Atomix plugin's source is proprietary and not shown here. This section describes how it connects to the documented ajLeaderboards API and database.
Reference documentation: ajLeaderboards setup · Placeholders · TopManager API