Difference between revisions of "Ylands Leaderboards"

From Bohemia Interactive Community
Jump to navigation Jump to search
(Created page with "=Overview= Leaderboards is extension of '''Persistent storage''' allowing to store a specific value per player in a automatically sorted database...")
 
 
(3 intermediate revisions by 2 users 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 segment of the 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.
*Set variable name and sorting method. Confirm.
+
*Set variable '''name''' and '''sorting''' method.
 
*'''Important'''
 
*'''Important'''
**New variable is committed to Game storage right after variable settings are confirmed.
+
**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 committed, storage variables '''cannot be deleted''', only marked as "obsolete" (to assure continuous game compatibility).
  
  
Line 22: Line 22:
  
  
*Once declared, leaderboard variables can be then utilized by instructions found in Visual scripting under Game -> Leaderboard category.
+
*Once declared, leaderboard variables can be then utilized by instructions found in Visual scripting under '''Game''' -> '''Leaderboard''' category.
  
===Setting a score===
+
=== 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 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=====
+
===== 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 regardless the period.
+
*[[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.
  
  
===Player information query===
+
=== 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.
+
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_-_player_info|'''player info''']] object, which can be then parsed for more data.
 
*[[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.
Line 48: Line 48:
  
 
*[[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.
  
 
<gallery>
 
<gallery>
 
Image:Ylands-Editor-leaderboard_2.png|Example
 
Image:Ylands-Editor-leaderboard_2.png|Example
 
</gallery>
 
</gallery>
 +
  
  
 
----
 
----
 
{{Navbox/Ylands}}
 
{{Navbox/Ylands}}
 +
{{DEFAULTSORT:{{#sub:{{PAGENAME}}|7}}}}
  
[[Category: Ylands: How To]]
+
[[Category: Script: How To]]

Latest revision as of 19:33, 17 November 2021

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).



  • 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.