6.5. Basic Features - Random Matchmaking

This section describes random matchmaking.

 

Reference:

Random matchmaking is not supported during local communication.

 

For more information about leaving sessions, see 6.8.. Basic Features - Leaving Sessions.

Random Matchmaking

The random matchmaking feature can be used with Internet communication. Using the random matchmaking feature performs a search with specified conditions. If a session is found that meets those conditions, it is joined. If no session is found that meets those conditions, a session with those conditions is created.

The random matchmaking feature is an asynchronous process. Calling the JoinRandomSessionAsync() function starts the asynchronous process. The end of that process can be detected with the IsCompletedJoinRandomSession() function. GetJoinRandomSessionResult() returns a result of true for IsSuccess() when random matchmaking is successful.

Up to two search conditions can be specified in an array, in which case the searches are done in order, starting with the condition at the beginning of the array.

Code 6-9. Using the Random Matchmaking Feature
// Settings for the session to create.
nn::pia::inet::NexCreateSessionSetting createSessionSetting;
createSessionSetting.SetGameMode(SESSION_GAME_MODE); // Game mode.
createSessionSetting.SetMaxParticipants(SAMPLE_MAX_ENTRY); // Maximum number of participants.
createSessionSetting.SetAttribute(SESSION_ATTR_INDEX, SESSION_ATTR_VAL); // The session attribute.
createSessionSetting.SetOpenParticipation(true); // Create a session that is ready to join immediately.

// Search criteria settings.
const size_t SEARCH_SETTING_NUM = 2; // You can set a maximum of two search criteria.
nn::pia::inet::NexSessionSearchCriteria sessionSearchSettingList[SEARCH_SETTING_NUM];
  
// Specifying a single attribute.
sessionSearchSettingList[0].SetGameMode(SESSION_GAME_MODE); // Game mode.
sessionSearchSettingList[0].SetMaxParticipants(SAMPLE_MAX_ENTRY); // Maximum number of participants.
sessionSearchSettingList[0].SetAttribute(SESSION_ATTR_INDEX, SESSION_ATTR_VAL); // The session attribute.

// Specifying multiple attributes (less strict that the first criteria).
sessionSearchSettingList[1].SetGameMode(SESSION_GAME_MODE); // Game mode.
sessionSearchSettingList[1].SetMaxParticipantsRange(SAMPLE_MIN_ENTRY, SAMPLE_MAX_ENTRY); // Maximum number of participants.
const size_t ARRAY_SIZE = 5;
u32 attributeArray[ARRAY_SIZE] = {2, 4, 6, 11, 72};
sessionSearchSettingList[1].SetAttribute(SESSION_ATTR_INDEX, attributeArray, ARRAY_SIZE); // Specify the range of matchmake attributes.

// Start the asynchronous process for random matchmaking.nn::Result result = nn::pia::session::Session::GetInstance()->JoinRandomSessionAsync(&createSessionSetting, sessionSearchSettingList, SEARCH_SETTING_NUM);
if ( result.IsFailure() )
{
    // Error processing.
}

// If the asynchronous process has started successfully, you must call the dispatch function periodically and wait for the asynchronous process to proceed.
while( nn::pia::session::Session::GetInstance()->IsCompletedJoinRandomSession() == false )
{
    nn::pia::common::Scheduler::GetInstance()->Dispatch();
    // You must call the NEX Scheduler::Dispatchfunction for keep-alive communications with the server.
    nn::nex::Scheduler::GetInstance()->DispatchAll();
}

// Check the result of the asynchronous process.
result = nn::pia::session::Session::GetInstance()->GetJoinRandomSessionResult();
if ( result.IsFailure() )
{
    // Error processing.
}

// If the asynchronous process succeeds, you are either creating or joining a session.

Matchmaking Using Range Broadening + Matchmaking Priority for Session Selection

With Internet communications, for matchmaking, you can use a method that selects the session using a combination of the progress in the game plus the range broadening provided by the auto matchmaking feature of NEX. For more information about matchmaking using range broadening plus game progress, see the Server Services > Matchmaking > Selecting the Matchmaking Session section in the NEX Programming Manual.

For purposes of clarity, in Pia, the term matchmaking priority is used to refer to game progress.

To use range broadening plus matchmaking priority for matchmaking, you must set nn::pia::inet::SELECTION_METHOD_BROADEN_RANGE_WITH_SELECTION_PRIORITY as the session selection method in the settings for the session search conditions, and also do the following.

  • When the settings for the session creation conditions and session search conditions are configured, ratings and other values must be set in the index of matchmaking attributes (inet::SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX).
  • As the game progresses, the matchmaking priority must be updated by calling the Session::UpdateSelectionPriority() function.

If after range broadening, multiple sessions meet the conditions, matchmaking is performed with the session that has the highest matchmaking priority.

If one or the other is not configured, you can select the session for matchmaking by using a priority of only range broadening or only matchmaking.

Code 6-10. Using Range Broadening Plus Matchmaking Priority as the Session Selection Method for Matchmaking
// Settings for the session to create.
nn::pia::inet::NexCreateSessionSetting createSessionSetting;
createSessionSetting.SetAttribute(nn::pia::inet::SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX, SAMPLE_INITIAL_RATING_VALUE); // Rating setting.
createSessionSetting.SetSelectionPriority(SAMPLE_INITIAL_SELECTION_PRIORITY); // Initial settings for matchmaking priority.

// Search criteria settings.
nn::pia::inet::NexSessionSearchCriteria sessionSearchSetting;
sessionSearchSetting.SetAttribute(nn::pia::inet::SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX, SAMPLE_INITIAL_RATING_VALUE); // Rating setting.
sessionSearchSetting.SetRandomSessionSelectionMethod(nn::pia::inet::SELECTION_METHOD_BROADEN_RANGE_WITH_SELECTION_PRIORITY); // Setting to use range broadening plus matchmaking priority as the session selection method.

// During gameplay
// you must call UpdateSelectionPriority() to check whether there are any problems before updating the matchmaking priority.
if (nn::pia::session::Session::GetInstance()->IsUpdatableSelectionPriority(temporaryPriority))
{
    nn::pia::session::Session::GetInstance()->UpdateSelectionPriority(temporaryPriority);
}

Matchmaking Selection Method Based on Scoring

Sessions whose search conditions, based on the following parameters, match the user's upon comparison are converted to a score value. The session with the highest score is selected.

  • Rating value difference
  • Disconnection rate difference
  • Violation rate difference
  • Distance, accounting for the Internet path
  • Country code match
  • Country code match without distance information
  • Matchmaking session duration
  • Matchmaking session matchmaking priority

For more information about the settings used to convert parameters to scores, in the NEX Programming Manual, see Server Services > WebAPI > Matchmaking Sessions > API for Scored Auto-Matchmaking.

In addition to setting these parameters as session creation conditions and search conditions, you must also configure the search conditions as a session selection method with nn::pia::inet::SELECTION_METHOD_SCORE_BASED.

You must also specify the designated settings number as a search condition when configuring score conversion because multiple conversion methods are available to the server.

nn::pia::inet::NexCreateSessionSetting createSessionSetting;
nn::pia::inet::NexSessionSearchCriteria sessionSearchCriteriaList[2];

// The following values are set for matchmaking.
createSessionSetting.SetRatingValue(rating); // Rating value.
createSessionSetting.SetDisconnectionRate(disconnectionRate); // Disconnection rate.
createSessionSetting.SetViolationRate(violationRate); // Violation rate.
createSessionSetting.UseGeoIp(true); // Distance, accounting for the Internet path.
createSessionSetting.SetNintendoCountryCode(cfgCountryCode); // Country code.
// You can specify an IP address for debugging purposes.
createSessionSetting.SetOverrideIpAddress(GEO_IP_LIST[geoIpIndex], wcslen(GEO_IP_LIST[geoIpIndex]));

// Values to use for comparisons when searching.
sessionSearchCriteriaList[0].SetRandomSessionSelectionMethod(nn::pia::inet::SELECTION_METHOD_SCORE_BASED); // Configures the score-based session selection method.
sessionSearchCriteriaList[0].SetScoreSettingIndex(1); // The index of the score conversion settings to use.
sessionSearchCriteriaList[0].SetRatingValue(rating); // Rating value.
sessionSearchCriteriaList[0].SetDisconnectionRate(disconnectionRate); // Disconnection rate.
sessionSearchCriteriaList[0].SetViolationRate(violationRate); // Violation rate.
sessionSearchCriteriaList[0].SetUseGeoIp(true); // Distance, accounting for the Internet path.
sessionSearchCriteriaList[0].SetNintendoCountryCode(cfgCountryCode); // Country code.
// An IP address can be set for debugging purposes.
sessionSearchCriteriaList[0].SetOverrideIpAddress(GEO_IP_LIST[geoIpIndex], wcslen(GEO_IP_LIST[geoIpIndex]));

sessionSearchCriteriaList[1].SetRandomSessionSelectionMethod(nn::pia::inet::SELECTION_METHOD_SCORE_BASED);
sessionSearchCriteriaList[1].SetScoreSettingIndex(2); // Other score conversion settings indices can be set.
// The settings are the same, so they have been omitted below.

// Random matchmaking with the preceding settings.
result = nn::pia::session::Session::GetInstance()->JoinRandomSessionAsync(&createSessionSetting, sessionSearchCriteriaList, 2);