5. Ranking

5.1. Ranking Workflow

Basic ranking uses the following workflow.

  1. Log in to the game server.
  2. Initialize the service client (5.3).
  3. Upload common user data (5.4).
  4. Register scores (5.5).
  5. Get rankings (5.6).
  6. Finalize the service client, and log out from the game server.

5.2. Information Saved on the Game Server

For ranking, data sets as shown in the following figure are saved on the game server for each principal ID.

_images/Fig_Ranking_Server_Data.png

Figure 5.1 Information Saved on the Game Server

Each user has common user data (for example, a user name) that is shared across categories, in addition to score data that is unique to each category. The following score data can be registered: the actual score achieved by the user, and the group 0, group 1, and parameter attributes that are associated with the score. The group 0 and group 1 attributes can be used to filter the rankings. (For more information, see Section 5.6.2.)

When multiple scores are uploaded to the same category, a history of the past scores is saved, and the highest score among them is used for ranking purposes. (For more information, see Section 5.6.1.)

Comments

By using a NEX unique ID, you can use multiple datasets with a single principal ID. For more information, see Using NEX Unique IDs for Rankings.

5.3. Initializing and Finalizing a Service Client

Initialization and finalization of the RankingClient object works the same as it does for the matchmaking service client. (For more information, see 4.3. Initializing and Finalizing a Service Client.)

5.4. Registering Common User Data

Use the RankingClient::UploadCommonData function to register or modify common user data for the local host.

Any binary data can be registered as common user data. The maximum size that can be registered for common user data is 255 bytes.

Use the RankingClient::GetCommonData function to get common user data for the local host. Use the RankingClient::DeleteCommonData function to delete common user data. These functions can only be used to get or modify common user data that has the same principal ID as the local host.

Common user data for other users can be obtained from the RankingRankData object that is returned when getting rankings.

Warning

Follow the UGC guidelines when registering common user data that includes UGC.

5.5. Registering Scores

Use the RankingClient::UploadScore function to register or modify scores. This API can only be used to upload or modify scores that have the same principal ID as the local one. The parameters in Table 5.1 must be given in a RankingScoreData object as the score registration information.

By specifying a NEX unique ID as an argument, you can register scores at a more granular level than the principal ID. (See Section 11.1.)

Table 5.1. RankingScoreData Parameters
Name Description Initial Value Settings Function
Category Specifies the category number to register the score to. Specify an integer value between 0 and 4,294,967,295. 0 SetCategory
Score Specifies the score. Specify an integer value between 0 and 4,294,967,295. 0 SetScore
Group 0 Specifies a group value to use as a filtering condition. Specify an integer value between 0 and 255. 0 SetGroup0
Group 1 Specifies a group value to use as a filtering condition. Specify an integer value between 0 and 255. 0 SetGroup1
Parameter
Specifies a parameter as data to associate with each score. Non-negative integer values of up to 64 bits can be specified.
This parameter is used to store information such as the character number and data ID of data associated with a score uploaded to the data store (for example, replay data).
0 SetParam
Score order
Specifies the order in which to arrange scores uploaded to a category.
If RankingConstants::ORDER_BY_DESC is specified, the scores are arranged in descending order. If RankingConstants::ORDER_BY_ASC is specified, the scores are arranged in ascending order.
When rankings are retrieved, they are returned in the order specified here.
RankingConstants::ORDER_BY_DESC SetOrderBy
Score update mode
Specifies whether a history of past scores is saved when new scores are uploaded to the same category.
If RankingConstants::UPDATE_MODE_NORMAL (the default value) is specified, past scores are saved.
If RankingConstants::UPDATE_MODE_DELETE_OLD is specified, the previous score in the category is deleted and the new score is uploaded.
RankingConstants::UPDATE_MODE_NORMAL SetUpdateMode

You can use the ranking management tool (Section 5.12) to set upper and lower limits on scores and set a restriction so that invalid scores are not registered to the ranking. When a score that is outside of the set range is uploaded, it is registered as an invalid score that is isolated from the rankings that are referenced by clients. The list of invalid scores can be referenced from the ranking management tool.

Warning

Always specify the same sort order for the same category for score sort orders. If a score sort order different from the one usually used for a category is specified for a RankingScoreData object and the object is then uploaded, the order of scores may be incorrect when rankings are retrieved.

5.6. Getting Rankings

Use the RankingClient::GetRanking function to get rankings. This function can get rankings by category. You can use this function to get the types of rankings listed in Table 5.2 by specifying a value for the RankingMode argument. You can also specify the ranking calculation method and filter conditions with RankingOrderParam, the order calculation parameter. For more information, see Table 5.3.

Ranking results are stored in a RankingResult object. The RankingResult object includes the total number of scores matching the specified conditions, the start date and time of the rankings that were calculated, and a list of ranking data (qVector<RankingRankData>). For a list of the items available from a RankingRankData object, see Table 5.4.

Table 5.2 Ranking Types
Type RankingMode Value Description
Bounded rankings RANKING_MODE_RANGE
Specifies an offset from the range of rankings from first place to RankingConstants::MAX_RANGE_RANKING_ORDER place, and the length of the list of scores to get, and gets that list of scores.
The specified offset cannot be larger than RankingConstants::MAX_RANGE_RANKING_ORDER – 1.
Neighboring rankings RANKING_MODE_NEAR
Gets a list of rankings in which the specified user comes in the middle of the list. (The specified user may not be in the middle of the list if the user was near first or last place.)
There are no restrictions on getting rankings that are not in the range of rankings. Nearby rankings can still be obtained even if the specified user's ranking is lower than RankingConstants::MAX_RANGE_RANKING_ORDER.
Friend rankings RANKING_MODE_FRIEND_RANGE Gets the rankings of friends of the local host. If a player does not have any friends, this gets only that player's data.
Rankings near friends RANKING_MODE_FRIEND_NEAR Gets rankings of friends that are near to the rankings of the local host.
Individual ranking data RANKING_MODE_USER Gets the ranking data for the specified user.
Table 5.3 RankingOrderParam Parameters
Name Description Initial Value Settings Function
Order calculation method Specifies how rankings are ordered. This can specify whether to use the same rank for multiple identical scores. RankingConstants::ORDER_CALCULATION_113 SetOrderCalculation
Time scope Specifies the time scope to use when filtering by period. (For more information, see Section 5.6.1.) RankingConstants::TIME_SCOPE_ALL SetTimeScope
Group filtering conditions Specifies the group index to use for filtering by group. (For more information, see Section 5.6.2.) RankingConstants::FILTER_GROUP_INDEX_NONE SetFilterGroupIndex
Group number to filter on Specifies the number to filter on when filtering by group. 0 SetFilterGroupNum
Offset Specifies the place from which to begin getting rankings (for example, list starting in 1st, 2nd, 3rd… place). This can only be used when getting a range of rankings. 0 SetOffset
Length Specifies the maximum number of records to retrieve. 10 SetLength
Table 5.4 Items Available From RankingRankData
Name Get Function
Principal ID GetPrincipalId
The NEX unique ID GetUniqueId
Category GetCategory
Rank GetOrder
Score GetScore
Group 0 GetGroup0
Group 1 GetGroup1
Parameter GetParam
Common user data GetCommonData

Note

The order in which scores are arranged (ascending or descending) when rankings are retrieved depends on the order specified for the category with RankingScoreData::SetOrderBy when the scores were uploaded. The order of scores cannot be changed when rankings are retrieved.

Note

If there are several identical scores in the rankings, the older score is ranked higher in the ranking calculations. If identical scores have the same update time, the score with the smaller principal ID is ranked higher.

Warning

When nearby rankings or individual user ranking data is retrieved and the ranking obtained is lower than RankingConstants::MAX_ACCURATE_ORDER, small ranking calculation errors may occur when the ranking is obtained with the RankingRankData::GetOrder function.

To reduce the load on the game server, a special process is used when a ranking lower than RankingConstants::MAX_ACCURATE_ORDER is calculated. In rare cases, this process may cause small ranking calculation errors to occur. The calculation errors are periodically revised, but they are not guaranteed to be accurate when retrieved in real time.

The score corresponding to a ranking lower than RankingConstants::MAX_ACCURATE_ORDER, however, can be obtained accurately in real time.

5.6.1. Filtering by Period

You can specify a time scope to filter rankings by a period of time.

As shown in Figure 5.2, the highest score among the scores uploaded by each user during the specified period of time is used for ranking purposes. The standards for determining whether a particular score is lower or higher than another score depends on the score sort order specified when the scores are uploaded. (For more information, see Section 5.5.)

_images/Fig_Ranking_Update_Mode.png

Figure 5.2 Scores Used for a User's Score History and Ranking

The time scope specified in the RankingOrderParam::SetTimeScope function can have any of the following values: RankingConstants::TIME_SCOPE_CUSTOM_0, RankingConstants::TIME_SCOPE_CUSTOM_1, or RankingConstants::TIME_SCOPE_ALL.

If RankingConstants::TIME_SCOPE_ALL is specified, there is no filtering based on time. If either RankingConstants::TIME_SCOPE_CUSTOM_0 or RankingConstants::TIME_SCOPE_CUSTOM_1 is specified, scores and rankings are filtered according to the filter type (time scope type) set beforehand in the ranking management tool. (For more information, see Section 5.12.)

The following time scope types can be used. Set "X" to the value of your choice with the management tool.

  • Filter on the periodically reset times (rankings appear to reset when the time enters the next period):
    • Every day at X time (UTC ±X) to the present
    • Every week on X day at X time (UTC ±X) to the present
    • On the X day of every month at X time (UTC ±X) to the present
    • On the first X day of the week of every month at X time (UTC ±X) to the present
  • Filter from a relative time to the present:
    • 24 hours earlier to the present
    • From X time (UTC ±X) 7 days ago to the present

By default the following types are set. Use the ranking management tool to change the settings. The server for the sample demo is also set as shown.

You can get information about what time the ranking results you have obtained were filtered from with the RankingResult::GetSinceTime function. When there is no time-based filtering (when RankingConstants::TIME_SCOPE_ALL is specified), the function returns January 1, 2000 0:00 (GMT).

Note

The default time zone is UTC+0. If the ranking management tool is used to change settings, the same value set for the time zone in OMAS personal settings is used for the time zone.

Note

The time scope type settings are common to all categories. It is not possible to set them differently by category.

Warning

If the type of time scope is changed after the scores have already been uploaded to the game server, the ranking results may contain errors. When changing the type of time scope, make sure to also initialize the scores.

5.6.2. Filtering by Group

You can filter scores in the rankings by group.

Both group 0 and group 1 group values can be specified when scores are uploaded, but only one group can be specified when filtering scores by group. Specify the group index of the group to filter by with the RankingOrderParam::SetFilterGroupIndex function, and specify the value in the group to filter by with the RankingOrderParam::SetFilterGroupNum function.

Depending on the values that you put in each group, you can filter scores in many ways. For example, if you store numbers that represent gender in group 0 and numbers that represent region in group 1 when scores are uploaded, you can filter the scores in the following ways.

Warning

When scores are filtered by group, each user's high score during the specified time scope is chosen first, and then the scores are filtered by group. The high scores for each user are chosen in advance for each time scope to reduce the load on the game server when retrieving rankings in which the scores are filtered by time.

If the values of a group are changed and the scores are uploaded multiple times within the same time scope, those scores do not appear in the rankings when the scores are filtered except when filtered by the group values of the high score during that period.

5.6.3 Acquiring Cached Top Ranking

A developer may choose to use the cached top ranking (using the RankingClient::GetCachedTopXRanking or RankingClient::GetCachedTopXRankings functions) to get the top ranking. The cached top ranking acquisition API can be used in higher frequency than the standard ranking acquisition API. This API is cached for a maximum of five minutes on the server, and in return is counted separately from the other ranking APIs in the guideline check access count.

A different cache is built for each combination of category and RankingOrderParam. Up to a maximum of 200 caches can be used across a game.

Rankings for communities that are user-generated or that have an uncertain number of users may increase. They do not benefit greatly from caching. Refrain from using this function with those communities.

The length acquired, from the top position to the nth place, can be set in NMAS. The default value is to the 20th place, and alternate values of 10, 20, 50, and 100 may be used.

Ranking results are stored in a RankingCachedResult object.The RankingCachedResult object includes the total number of scores matching the specified conditions, the start date and time of the rankings that were calculated, and a list of ranking data (qVector<RankingRankData>). For a list of the items available from a RankingRankData object, see Table 5.4.

The RankingClient::GetCachedTopXRankings function can specify several categories. Up a maximum of 100 combinations of length specified in NMAS and categories may be acquired. By default, up to five different categories may be specified.

Data acquired by the RankingClient::GetCachedTopXRanking and RankingClient::GetCachedTopXRankings functions does not enter new scores until the scheduled update, even if new scores are uploaded to target the update. Instead, the RankingCachedResult::LocalUpdate function may be used to insert the score into the already acquired local ranking cache, to make it seem as if the global rankings are being updated. For the limitations, see the reference.

5.7. Changing Score Attributes

Use the RankingClient::ChangeAttributes function to change a score's attributes. You can change the group and parameter attributes associated with scores. This function can only be used to modify scores uploaded with the same principal ID as the local one.

Note

Changes to score attributes are also applied to scores uploaded in the past.

5.8. Deleting Scores

Use the RankingClient::DeleteScore function to delete scores. This function can only be used to delete scores uploaded with the same principal ID as the local one.

Note

Deleting a score also deletes past scores. It is not possible to specify only scores uploaded at a specific time to be deleted.

5.9. Getting Approximate Rankings Based on Scores

Use the RankingClient::GetApproxOrder function before uploading scores to get an approximate ranking for the score. The score is not actually registered in the rankings by using this function.

Warning

As in Section 5.6 Getting Rankings, rankings lower than RankingConstants::MAX_ACCURATE_ORDER may not necessarily be calculated accurately.

5.10. Getting Statistical Values for Scores

Use the RankingClient::GetStats function to get statistics such as the total score, the highest value, and the lowest value in each category. Set the argument to the bitwise OR of the order calculation parameter and the flag for the desired statistical value. The statistic flags that can be obtained are shown in Table 5.5.

Table 5.5 Statistic Flags
RankingConstants::StatsFlag Description
STATS_FLAG_TOTAL Total score.
STATS_FLAG_SUM Sum of scores.
STATS_FLAG_MIN Minimum score.
STATS_FLAG_MAX Maximum score.
STATS_FLAG_AVERAGE Average score.

Warning

Caching is used for the following statistics.

  • STATS_FLAG_TOTAL (Total number of scores)
  • STATS_FLAG_SUM (Sum of all scores)
  • STATS_FLAG_AVERAGE (Average score)

When the scores to be tabulated exceed a certain number, a cache is created when RankingClient::GetStats is called and remains for around 30 minutes. The cached value is returned if the cache exists, so the statistics are not necessarily the latest value.

5.11. Error Handling

5.11.1. Errors During Function Calls

If you call a function and it returns an error without starting asynchronous processing, there may have been a programming error. Check whether the NEX library has been successfully initialized, whether you have logged in to the game server, and so on.

5.11.2. Asynchronous Processing Errors

Error handling is the same as for matchmaking. For more information, see Section 4.25 Error Handling. The following table lists errors that may occur with rankings. This table excludes NEX communication errors and other processes.

Table 5.6 Ranking Errors
ReturnCode Value Description
QERROR(Ranking, InvalidArgument) An invalid argument was specified. This error is a programming error, so correct it accordingly.
QERROR(Ranking, RegistrationError) Data failed to be registered. It is very likely that server operations are unstable.
QERROR(Ranking, NotFound) Data not found. There is no data that matches the request. When this error occurs, handle it by ignoring it, notifying the user that data could not be found, or taking other similar steps.
QERROR(Ranking, InvalidDataSize) Invalid data size. The size of the common user data is invalid. This error is a programming error, so correct it accordingly.
QERROR(Ranking, PermissionDenied) No access rights. There was an attempt to change another person's score or common user data. This error is a programming error, so correct it accordingly.
QERROR(StorageBase, Unknown) Unknown error occurred. The server configuration is atypical. Please contact Nintendo if this error occurs.

5.12 NEX Server Management System (NMAS)

You can use the ranking management features of the NEX Server Management System (NMAS) to view and download the scores uploaded to the ranking, and configure the timescope. The tool supports both the development environment and the actual production environment.

5.12.1. How to Access the Management Tool

Access this management tool from the following URL.

https://nmas.app.nintendowifi.net/nmas/

Use the same login ID and password that you use for OMAS.

5.13. Warnings About Using the Ranking Functions

5.13.1. Expected Ranking Registration Volume

The number of scores expected to be registered using the NEX ranking function is less than 10,000,000 scores. Additional scores may cause effects such as reduced responsiveness. If you are using multiple categories, make sure to design it so that the total number of registered scores is less than 10,000,000. Please contact Nintendo for titles that will exceed 10,000,000 scores.

5.13.2. Registering Dummy Data for Debugging

Part of the ranking APIs limit the range of scores acquired to the top 1000. Use the Register Dummy Data function in NMAS to register dummy data for debugging. We suggest adding at least 1500 scores to the dummy data.


CONFIDENTIAL