4. Tips and Tricks

4.1. Rankings

This section provides a variety of tips and tricks for using the ranking features.

Using a Large Number of Ranking Categories

The RankingClient::GetRanking() function only allows you to specify one category at a time. If you are using a large number of categories, this function has to be called at least as many times as there are categories. However, ranking functions are subject to a call frequency limitation of 15 times per 5 minutes. This means that it is only possible to get the rankings for a maximum of 15 categories every 5 minutes.

To work around this issue, you can use cached rankings, although there are also some restrictions on this method as well. Use the RankingClient::GetCachedTopXRanking() function to get cached rankings. This function can get a total of 100 top rankings across multiple categories. For example, this function can get the top 5 rankings for 20 categories.

Cached rankings can also be accessed more frequently than when using the other ranking-related functions, up to 20 times per 5 minutes. This function can get the top 5 rankings for 400 categories over the course of 5 minutes, for example.

However, when using cached rankings, it may take up to 5 minutes for a newly uploaded score to appear in the rankings (even if the local user uploads the score). Therefore, the local user's score may not appear in the rankings if the top rankings are retrieved immediately after the score is uploaded. The RankingCachedResult::LocalUpdate() function was created to solve this problem. This function sets the local user's score and then merges rankings with the local user's ranking when the rankings are retrieved.

The number of categories that use cached rankings can be configured on NMAS. This setting cannot be configured from the client side.

Accessing Rankings with a High Frequency

If the call frequency limitations on the RankingClient::GetCachedTopXRanking() function are still too restrictive or you want to retrieve rankings other than the top rankings at a very high frequency, consider using the Ranking2 module.
In the Ranking2 module, the function for getting rankings (Ranking2Client::GetRanking()) can be called up to 20 times per minute. In addition, the numbers of calls to each API function are counted independently.
However, the Ranking2 module is designed somewhat differently from the normal ranking module and has its own limitations. For example, the Ranking2 module does not allow you to filter scores by groups.

Uploading a Large Number of Dummy Scores to a Ranking Category for Debugging

Nintendo strongly recommends uploading dummy data when debugging your implementation of a ranking feature. Some of the NEX ranking API functions have a restriction on the number of ranked scores that can be retrieved and may behave differently depending on the total number of ranked scores. In particular, these functions only support offset values (a value set to get a range of ranked scores starting from the offset) less than 1000. These functions will return an error if an offset greater than or equal to 1000 is specified when they are called. Uploading dummy data allows you to test different workflows for getting rankings based on the total number of ranked scores.

Dummy data can be uploaded using NMAS. Nintendo recommends uploading at least 1500 dummy scores. However, do not upload more than 1 million dummy scores in total because doing so may cause an extremely high server load. Furthermore, uploading dummy data takes a non-negligible amount of time. Nintendo recommends starting from a lower number of dummy scores and gradually increasing the number to obtain the desired number of dummy scores.

Breaking Ranking Compatibility in Application Updates

If you want to prevent the intermingling of ranked scores from the pre- and post-updated versions of an application, Nintendo recommends changing the ranking categories as well as the categories to which scores are uploaded in order to break ranking compatibility.

While it is possible to make the application update mandatory and reset ranking data, this requires careful organization when the update is released, when the server will be reset, and when all of the users will be disconnected from the server in order to do so. Furthermore, titles that are available in several regions use the same game server. Breaking compatibility using the latter method would therefore require releasing the update simultaneously in all regions worldwide. Nintendo recommends using the former method of reconfiguring categories to break ranking compatibility whenever possible.

Separating Rankings by Region

The game server itself cannot be partitioned for each region. To separate rankings by region, use different categories for each region.

Linking with Data Stores

If you want to include information about the user when uploading a score to the rankings, upload that user data to a data store and associate it with the ranked score.

To perform this, upload the desired user information to the data store in advance and associate a data ID with that data. Then, when calling the RankingClient::UploadScore() function, set the data store data ID as one of the parameters in the RankingScoreData object. Doing this allows you to download the data associated with that data ID on the data store when the user retrieves the rankings.

4.2. Matchmaking

This section provides a variety of tips and tricks for using the matchmaking features.

Disabling Matchmaking Between Clients Using the Pre- and Post-Updated Versions of an Application After an Application Update

If you want to disable matchmaking between clients using the pre- and post-updated versions of an application before or after an application update, Nintendo recommends changing the game modes as well as search conditions.

While it is possible to make the application update mandatory after the update is released for all users to access the server, this requires carefully organizing when the update is released, when the server will be reset, and when all of the users will be disconnected from the server in order to do so. Furthermore, titles that are available in several regions use the same game server. Breaking compatibility using the latter method would therefore require releasing the update simultaneously in all regions worldwide. Therefore, Nintendo recommends the former method of simply changing the game modes accordingly.

Modifying game modes to support release of an application update may have the unwanted side effect of decreasing the matchmaking success rate due to the increased number of game modes. To prevent users from being distributed across several game modes, Nintendo recommends rejecting authentication of clients using the old version of the application. Rejecting authentication of clients using the old version of the application on the account server and the authentication server after the patch is released, makes it possible to guarantee that users who successfully log into the game server have installed the latest patch. For more information on guaranteeing that clients have installed the latest patch, see the Releasing Patches section in 2. Development/Usage Overview.

 

4.3. Data Stores

This section provides a variety of tips and tricks for using the data store features.

 

Using Both a Storage Server and the Game Server

When using the data store feature to save data, that data can be saved on a storage server or on the game server.

The table below details some of the advantages and disadvantages of each method.

  Storage Server Game Server
Maximum size for a single piece of data. 10 MB 1024 bytes
Number of pieces of data that can be downloaded/uploaded at once. 1 100
Specifying a data ID when uploading data. No Yes
Processing speed. Slower than when using the game server. -

However, by using both a storage server and the game server in combination, you can take full advantage of each. For example, you could store replay data on the storage server and the thumbnails for that data on the game server, and then just get all of the thumbnails and only get the actual replay data from the storage server when necessary.

 

Using Data Stores as a Counter

Data stores can be used to store data that functions as a counter for actions taken by game players or ratings submitted by game players.

For example, you could implement a voting feature by having clients evaluate some piece of data that was uploaded in advance, and then totaling the submitted user values. For instance, you could set the possible values for users to submit to 0 and 1 and allow users to change their votes, but also implement a lock on duplicate votes to only allow each user to submit a single vote to let users vote on some condition for a given period of time.

To use data stores as a counter across the entire game, someone has to upload the data. In this case, you can enable specification of a data ID when data is uploaded to ensure that data is only uploaded when data with that data ID has not been already been uploaded. In this case, the system attempts to upload the user value/rating but only succeeds in doing so if the corresponding data does not already exist.

Negative values can also be specified and used freely as global variables for game participants, for example.

However, relative comparison of these values is not supported, so you cannot filter data by values greater than or equal to a certain value.

Getting Random Data

To retrieve uploaded data at random, specify RESULTRANGE_ANY_OFFSET as the offset for the data to retrieve. This makes the server return pseudo-randomly selected data. Doing this makes it possible to prevent getting the same data every time.

Breaking Data Compatibility with an Application Update

If you want to prevent intermingling of data from the pre- and post-updated versions of an application in a data store before or after an application update, Nintendo recommends changing the data types as well as the locations to which data is uploaded in order to break data store compatibility.

While it is possible to make the application update mandatory after the update is released, this requires carefully organizing when the update is released, when the server will be reset, and when all of the users will be disconnected from the server in order to do so. Furthermore, titles that are available in several regions use the same game server. Breaking compatibility using the latter method would therefore require releasing the update simultaneously in all regions worldwide. Nintendo recommends using the former method of simply changing the data types whenever possible.

Distributing Pseudo-StreetPass Communications Over a Network

Pseudo-StreetPass communications can be implemented by using data stores to categorize data by received and unreceived data. For example, you can specify a data type of 1 when uploading data that you want to use for StreetPass, and then later get one of the pieces of data with a data type of 1 by specifying the appropriate search conditions. Once a user has obtained this data, the data type can be changed to 0 to ensure that that user does not receive the same data again. This also allows the user that uploaded the data to see which data was downloaded later.

This type of data could also potentially be categorized and searched using tags. However, this implementation is not recommended because as described in 3.4. Data Stores, NEX data stores are not designed to handle searching through extremely large numbers of similarly tagged pieces of data. The server load increases proportionally to the total number of pieces of data, and this implementation may degrade the service and the user experience.

Linking with SpotPass

Data can be uploaded and downloaded to and from a data store server via SpotPass. For more information, see the Programming Manual - SpotPass.

It is also possible to use the NEX library in combination with SpotPass, such as to upload data to a data store server using the NEX library and then use SpotPass to download that data, for example.


CONFIDENTIAL