Leaderboards – Ylands
Jump to navigation
Jump to search
No edit summary |
Lou Montana (talk | contribs) m (Text replacement - "[[Ylands_" to "[[Ylands:") |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
=Overview= | =Overview= | ||
'''Leaderboards''' is extension of [[Ylands Persistent Storage|'''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''' is extension of [[Ylands:Persistent Storage|'''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 [[Ylands Persistent Storage|'''Persistent storage''']] | *'''Leaderboards''' are variables stored in [[Ylands:Persistent Storage|'''Persistent storage''']] | ||
**Leaderboard variables can be either '''Game''' or [[Ylands Game set|'''Game set''']] specific. | **Leaderboard variables can be either '''Game''' or [[Ylands:Game set|'''Game set''']] specific. | ||
**Leaderboard variables are limited to 3 decimal '''float''' type. | **Leaderboard variables are limited to 3 decimal '''float''' type. | ||
**Current '''maximum''' ranked leaderboard length is '''500'''. | **Current '''maximum''' ranked leaderboard length is '''500'''. | ||
=== New leaderboard variable === | === New leaderboard variable === | ||
'''Leaderboard''' variables are defined in similar manner as [[Ylands Persistent Storage|'''Game or Game set variables''']] and '''same rules''' apply here. | '''Leaderboard''' variables are defined in similar manner as [[Ylands:Persistent Storage|'''Game or Game set variables''']] and '''same rules''' apply here. | ||
*Use editor '''toolbar''' to open Game or Game set storage. | *Use editor '''toolbar''' to open Game or Game set storage. | ||
*Click '''Add new leaderboard''' button to add new variable to storage. | *Click '''Add new leaderboard''' button to add new variable to storage. | ||
| Line 29: | Line 29: | ||
===== Time period ===== | ===== Time period ===== | ||
*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. | *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 [[Ylands Tile - Leaderboard - get-set score|'''update''']] instruction, it is '''automatically propagated''' in all time periods. | *Whenever a '''new value''' is stored using [[Ylands:Tile - Leaderboard - get-set score|'''update''']] instruction, it is '''automatically propagated''' in all time periods. | ||
*Daily, weekly and monthly leaderboards are periodically reset according to their time scope. | *Daily, weekly and monthly leaderboards are periodically reset according to their time scope. | ||
===== Instructions ===== | ===== Instructions ===== | ||
*[[Ylands Tile - Leaderboard - get-set score|'''Update score''']] - will '''automatically''' update the score in '''all''' time '''periods'''. | *[[Ylands:Tile - Leaderboard - get-set score|'''Update score''']] - will '''automatically''' update the score in '''all''' time '''periods'''. | ||
*[[Ylands Tile - Leaderboard - get-set score|'''Set score''']] - allows to set a '''specific''' '''score''' value for '''given time''' period. | *[[Ylands:Tile - Leaderboard - get-set score|'''Set score''']] - allows to set a '''specific''' '''score''' value for '''given time''' period. | ||
| Line 40: | Line 40: | ||
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. | 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. | ||
*[[Ylands Tile - Leaderboard - get position|'''Get position''']] - will return a specific [[ | *[[Ylands:Tile - Leaderboard - get position|'''Get position''']] - will return a specific [[Ylands:Tile_-_Leaderboard_-_player_info|'''player info''']] object, which can be then parsed for more data. | ||
*[[ | *[[Ylands:Tile_-_Leaderboard_-_player_info|'''Player info''']] | ||
**'''Get name''' - returns name of target player. | **'''Get name''' - returns name of target player. | ||
**'''Get score''' - returns current score value. | **'''Get score''' - returns current score value. | ||
**'''Get ranking''' - returns current score rank (max 500). | **'''Get ranking''' - returns current score rank (max 500). | ||
**'''Get update time''' - returns when score was last updated ([[Ylands Tile - Get UTC date|UTC format]]) | **'''Get update time''' - returns when score was last updated ([[Ylands:Tile - Get UTC date|UTC format]]) | ||
*[[Ylands Tile - Leaderboard - get segment|'''Get segment''']] - will return a segment object containing given leaderboard range. Segment object can be then parsed for individual player info objects. | *[[Ylands:Tile - Leaderboard - get segment|'''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 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) | **'''Get Max rank''' - returns current highest rank achieved (max 500) | ||
*'''Important''' | *'''Important''' | ||
**If there are '''no''' valid leaderboard '''entries''', both instructions will return [[Ylands Tile - Null literal|'''null''']] object. | **If there are '''no''' valid leaderboard '''entries''', both instructions will return [[Ylands:Tile - Null literal|'''null''']] object. | ||
**'''Lowest''' leaderboard rank is '''1''', which applies '''also''' for '''segment''' query. | **'''Lowest''' leaderboard rank is '''1''', which applies '''also''' for '''segment''' query. | ||
Latest revision as of 16:36, 16 November 2022
Overview
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.
- Important
- 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).
Game storage
- 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.
Time period
- 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.
Instructions
- 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)
- Important
- If there are no valid leaderboard entries, both instructions will return null object.
- Lowest leaderboard rank is 1, which applies also for segment query.
Example
