New Rank - Internal

Related Resources

Introduction to Historical Data Storage Modules

Data Storage Module

Provides detailed information in the above resource. Here’s a brief overview of the Data Storage Module.Data Storage is an optional module. When enabled, it allows map developers to utilize server-based data tables for data storage. It is primarily used for cross-map and cross-match data synchronization, Rank, and similar features. This article focuses on the new data storage tables specifically for Rank functionality.

Access

Load the Data Storage module from the module list to begin configuring the column information for four types of data tables:

New Table Introduction

Like all data tables, each table requires you to specify a “Key” column, which serves as the primary key. Key column data must be unique and acts as the index for the entire table. By querying the Key, you can identify a specific data row within the table. When editing multiple rows with the same Key using a block, subsequent edits will always overwrite previous data.

Rank Datasheet

A rank datasheet is a specialized multi-column table where you can define additional columns to store supplementary information such as points, survival time, total game duration, etc. However, a rank datasheet must include one column (the Value column) used for ascending or descending sorting.

Selecting UID as Key will automatically convert the Rank column into player cards:

Table Example

Ranking datasheet1

Multi-column Data Table

Multi-column tables support storing multiple data columns (unlike previous single-column data tables). You can store various data types under a single Key. In the block script, APIs are provided to edit both Rank tables and associated multi-column data tables. When Keys match (e.g., both are player UUIDs), specific blocks can simultaneously edit both Rank tables and multi-column data tables.

Table Example

Multi-column Data Table1

Rank Feature

Enabling the Feature

To enable the rank feature, you must activate the Data Storage module in your project and create at least one rank data table.

Once ready, edit the map you intend to publish in the Creator Center map publishing UI to access Rank settings:

Enabling this feature will display a Rank button on your map’s details UI, allowing players to view the rank information you’ve edited:

Rank Editor

In the rank editor UI for published maps, you can currently select only one data table to display rank information. (Although you may use multiple tables to store data within the project)

You can edit other aspects of the leaderboard: whether to display it outside the game, which columns to use for the leaderboard layout, and their order.

Selecting multiple languages allows you to manually edit the leaderboard title’s multilingual information:

Languages not filled in will use the default table column names.

After editing, the map information page will display a preview of your current Rank. Multilingual text will not appear in this preview:

block

Use the block at appropriate times—such as when a player scores points or at the end of each match—to store data in the Rank data table.

Note: The SheetName parameter must reference a leaderboard data sheet block for the created leaderboard data sheet to be read.

To simplify editing the two multi-list tables introduced in this tutorial, a special Tuple data type has been added. This is a unique list format. The Tuple type automatically identifies values from specified data sheets or Rank data sheets to form a special list with elements of the designated data type.

The block primitive automatically reads all tables and uses the data type of each table’s columns as the data type for its list items:

For Rank data tables, once a custom data column is created, the value will actually contain N columns of data, thus forming a tuple:

Therefore, in practical usage, tuples may become nested:

Tuple blocks do not automatically update table column names or other information. Therefore, any changes require manually refreshing the tuple block.

Code

Code example:

1. Write

   WriteDBLeaderboardAssociationValue(``“rank”``, ``‘test_uid_1’``, {``60``, ``“1:00”``}, ``“”``, out var c, out var d)
   go

2. Read

   ReadDBLeaderboardAssociationValue(“rank”, ‘test_uid_1’, out var data, “”, out var a, out var b)
   var data_normal List<object> = data[2] as List<object>
   LogWarning(data_normal[1])
   go

Related API List

1. SetTuple
2. GetTuple
3. WriteDBLeaderboardAssociationValue
4. RemoveFromLeaderboardDataStoreByKey
5. ReadDBLeaderboardAssociationValue
6. WriteToLeaderboardDataStore
7. RemoveFromLeaderboardDataStoreByKey
8. ReadFromLeaderboardDataStore

Specifically, for the function: ReadDBLeaderboardAssociationValue, its return value is a tuple:

Result: The type is {rankname_value}Tuple

• {rank, key, value}
• rank: int
• key: string
• value: tuple
• {value, GameCompletionTime}

For the function: WriteDBLeaderboardAssociationValue, the Key and Value parameters:

• Key: It is recommended to convert the player’s UID into a string as the key, so that the player’s callsign can be displayed in Craftland
• Value: The type is {rankname} Tuple. After selecting SheetName, double-click Value to quickly add the corresponding block
  For more API parameters and documentation, refer to: Official Documentation

Local Debugging

During map editing, online player data is unavailable. However, Craftland Studio PC allows viewing debug-stored data via local JSON files.

After data is stored during debugging, clicking the option shown in the image will navigate to the local JSON folder. Data table information is saved in JSON format, allowing developers to verify the correctness of the logic.