Difference between revisions of "Ylands Leaderboards"
Revision as of 17:12, 11 April 2021
Leaderboards is extension of Persistent storage allowing to store a specific value per player in a automatically sorted database. Whenever a new value is submitted to the database, it is compared with other entries and ranked accordingly. This ranking can be then queried from the database either individually per player or in form of a ranked list. Furthermore its is also possible to constrain the query to a specific time period - day, week, month and all time.
- Leaderboards are variables stored in Persistent storage
- Leaderboard variables can be either Game or Game set specific.
- Leaderboard variables are limited to 3 decimal float type.
- Current maximum ranked leaderboard length is 500.
New leaderboard variable
Leaderboard variables are defined in similar manner as Game or Game set variables and same rules apply here.
- Use editor toolbar to open Game or Game set storage.
- Click Add new leaderboard button to add new variable to storage.
- Set variable name and sorting method.
- New variable is committed to Game storage right after variable settings are confirmed.
- Once committed, storage variables cannot be deleted, only marked as "obsolete" (to assure continuous game compatibility).
- Once declared, leaderboard variables can be then utilized by instructions found in Visual scripting under Game -> Leaderboard category.
Setting a score
In order to provide the leaderboard any relevant data, it is necessary to assign score to one or more players. Each score is then compared to other entries and sorted accordingly.
- In order to be able to create time-specific leaderboards, all values are actually stored and updated in 4 leaderboards - daily, weekly, monthly and all time.
- Whenever a new value is stored using update instruction, it is automatically propagated in all time periods.
- Daily, weekly and monthly leaderboards are periodically reset according to their time scope.
- Update score - will automatically update the score in all time periods.
- Set score - allows to set a specific score value for given time period.
Player information query
Once a score is committed to the database, it is possible to query for player score ranking, either individually or for a segment from the leadeboard.
- Get position - will return a specific player info object, which can be then parsed for more data.
- Player info
- Get name - returns name of target player.
- Get score - returns current score value.
- Get ranking - returns current score rank (max 500).
- Get update time - returns when score was last updated (UTC format)
- Get segment - will return a segment object containing given leaderboard range. Segment object can be then parsed for individual player info objects.
- Get Items - allows to parse the segment in to an array of individual Player info objects.
- Get Max rank - returns current highest rank achieved (max 500)
- If there are no valid leaderboard entries, both instructions will return null object.
- Lowest leaderboard rank is 1, which applies also for segment query.