Basic ranking uses the following workflow.
For ranking, data sets as shown in the following figure are saved on the game server for each principal ID.
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.
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.)
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.
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.)
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:: |
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:: |
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.
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.
Type | RankingMode Value |
Description |
---|---|---|
Bounded rankings | RANKING_ |
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_ |
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_ |
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_ |
Gets rankings of friends that are near to the rankings of the local host. |
Individual ranking data | RANKING_ |
Gets the ranking data for the specified user. |
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:: |
SetOrderCalculation |
Time scope | Specifies the time scope to use when filtering by period. (For more information, see Section 5.6.1.) | RankingConstants:: |
SetTimeScope |
Group filtering conditions | Specifies the group index to use for filtering by group. (For more information, see Section 5.6.2.) | RankingConstants:: |
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 |
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.
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.)
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.
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.
RankingConstants::TIME_SCOPE_CUSTOM_0
: Every Tuesday at midnight (UTC +0) to the presentRankingConstants::TIME_SCOPE_CUSTOM_1
: On the 1st day of every month at midnight (UTC +0) to the presentYou 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.
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.
RankingConstants::FILTER_GROUP_INDEX_0
in the RankingOrderParam::SetFilterGroupIndex
function and the number that represents males in RankingOrderParam::SetFilterGroupNum
, you could get rankings that include scores from only male users.RankingConstants::FILTER_GROUP_INDEX_1
in the RankingOrderParam::SetFilterGroupIndex
function and the number that represents Japan in RankingOrderParam::SetFilterGroupNum
, you could get rankings including scores only from users in Japan.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.
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.
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.
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.
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.
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.
RankingConstants::StatsFlag | Description |
---|---|
STATS_ |
Total score. |
STATS_ |
Sum of scores. |
STATS_ |
Minimum score. |
STATS_ |
Maximum score. |
STATS_ |
Average score. |
Warning
Caching is used for the following statistics.
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.
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.
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.
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. |
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.
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.
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.
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