12.2. Matchmaking

12.2.1. General Information

Module name matchmake
API version 2

12.2.2. API for Range Broadening Auto-Matchmaking Feature

These functions are used when using the auto-matchmaking feature with range broadening. For more information on about this feature, see the descriptions for when MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE and MATCHMAKE_SELECTION_METHOD_BROADEN_RANGE_WITH_PROGRESS_SCORE are specified in 4.8.1. How to select the matchmaking session. The values that can be retrieved and modified with these functions are copied from the development environment when deploying to the Lotcheck and production environments.

12.2.2.1. Getting Range Settings

Gets the range settings.

12.2.2.1.1. Request

GET /nex/matchmake/v2/range/(name)

Gets the range settings specified under name.

Parameters:

Name Details
name Specifies the range settings to get. For more information, see the table below.Required

Request Examples:

GET /nex/matchmake/v2/range/threashold HTTP/1.1

name

Value Details
threshold Specifies the range threshold.

12.2.2.1.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <ranges length="13">
      <range>
        <threshold>0</threshold>
      </range>
      <range>
        <threshold>1100</threshold>
      </range>
      <range>
        <threshold>1240</threshold>
      </range>
      <range>
        <threshold>1400</threshold>
      </range>
      <range>
        <threshold>1520</threshold>
      </range>
      <range>
        <threshold>1620</threshold>
      </range>
      <range>
        <threshold>1720</threshold>
      </range>
      <range>
        <threshold>1815</threshold>
      </range>
      <range>
        <threshold>1925</threshold>
      </range>
      <range>
        <threshold>2040</threshold>
      </range>
      <range>
        <threshold>2180</threshold>
      </range>
      <range>
        <threshold>2300</threshold>
      </range>
      <range>
        <threshold>10000</threshold>
      </range>
    </ranges>
  </matchmake>
</nex>

12.2.2.2. Getting All Range Settings and Auto-Matchmaking Results

Gets all range settings and auto-matchmaking results.

12.2.2.2.1. Request

GET /nex/matchmake/v2/ranges

Request Examples:

GET /nex/matchmake/v2/ranges HTTP/1.1

12.2.2.2.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <ranges length="13">
      <range>
        <threshold>0</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1100</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1240</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1400</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1520</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1620</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1720</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1815</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>1925</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>2040</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>2180</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>2300</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
      <range>
        <threshold>10000</threshold>
        <result1>0</result1>
        <result2>0</result2>
        <result3>0</result3>
      </range>
    </ranges>
  </matchmake>
</nex>
Element New Elements Details
ranges   Root element.
range ranges Container for range settings and auto-matchmaking results, which are child elements.
threshold range Specifies the threshold. The range is defined as the threshold value of the previous range plus one, up to this value. In the response example above, if this value is 1520, the corresponding range would be 1401 to 1520. However, you do not add one to the smallest threshold value. In the response example above, if this value is 1100, the corresponding range would be 0 to 1100, not 1 to 1100. When this value is set to the smallest threshold, there are no applicable ranges and the results 1 through 3 are always 0.
result1 range Specifies the first result. The number of matchmaking sessions that match the search criteria and are within the same range.
result2 range Specifies the second result. The number of matchmaking sessions that match the search criteria and were found within the broadened range but not within the same range.
result3 range Specifies the third result. The number of matchmaking sessions that match the search criteria but were not found in the same or broadened range.

12.2.2.3. Getting Out-of-Range Error Count

Gets the number of times an out-of-range value was sent to the server by a client. The value is the attribute value in the MATCHMAKE_SESSION_BROADEN_RANGE_ATTRIBUTE_INDEX index of the MatchmakeSession object. When this occurs, QERROR(RendezVous, OutOfRatingRange) is returned to the client.

12.2.2.3.1. Request

GET /nex/matchmake/v2/range_error

Request Examples:

GET /nex/matchmake/v2/range_error HTTP/1.1

12.2.2.3.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <range_error>
      <under_min_threshold>0</under_min_threshold>
      <over_max_threshold>0</over_max_threshold>
    </range_error>
  </matchmake>
</nex>
Element New Elements Details
range_error   Root element.
under_min_threshold range_error Number of times a value smaller than the minimum threshold was sent.
over_max_threshold range_error Number of times a value larger than the maximum threshold was sent.

12.2.2.4. Changing Range Settings

Changes the range settings. When these functions are used, the auto-matchmaking results from 12.2.2.2 Getting All Range Settings and Auto-Matchmaking Results and the out-of-range count from 12.2.2.3 Getting Out-of-Range Error Count are reset to zero.

12.2.2.4.1. Request

PUT /nex/matchmake/v2/range
POST /nex/matchmake/v2/range/put

Request body

Element New Elements Details
change   Root element.Required
thresholds change The container for threshold values, which are child elements.Required
threshold thresholds Specifies the threshold. Specify two or more elements with values of 0 or higher and no duplicates.Required

Request Examples:

PUT /nex/matchmake/v2/range HTTP/1.1

<change>
  <thresholds>
    <threshold>0</threshold>
    <threshold>1500</threshold>
    <threshold>3000</threshold>
    <threshold>5000</threshold>
    <threshold>9000</threshold>
    <threshold>20000</threshold>
    <threshold>100000</threshold>
  </thresholds>
</change>

12.2.2.4.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <ranges>
      <changed length="7"/>
    </ranges>
  </matchmake>
</nex>

length is the number of changed threshold values.

12.2.2.5. Resetting Auto-Matchmaking Results

Resets the auto-matchmaking results. The auto-matchmaking results from 12.2.2.2 Getting All Range Settings and Auto-Matchmaking Results and the out-of-range count from 12.2.2.3 Getting Out-of-Range Error Count are reset to zero.

12.2.2.5.1. Request

DELETE /nex/matchmake/v2/range
POST /nex/matchmake/v2/range/delete

Request Examples:

DELETE /nex/matchmake/v2/range HTTP/1.1

12.2.2.5.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <ranges>
      <reset length="7"/>
    </ranges>
  </matchmake>
</nex>

length is the number of auto-matchmaking results that were reset.

12.2.2.6. Resetting Range Settings

Resets the range settings.

12.2.2.6.1. Request

DELETE /nex/matchmake/v2/range/(name)
POST /nex/matchmake/v2/range/(name)/delete

Resets the range settings specified under name.

Parameters:

Name Details
name Specifies the range settings to reset. For more information, see the table below. Required

Request Examples:

DELETE /nex/matchmake/v2/range/results HTTP/1.1

name

Value Details
results Auto-matchmaking result. Zero (0) after reset. The number of the out-of-range count from Section 11.2.2.3 Getting the Out-of Range Error Count is also reset to zero. The functionality is the same as Section 12.2.2.5 Resetting the Auto-matchmaking Result.

12.2.2.6.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <ranges>
      <reset length="7"/>
    </ranges>
  </matchmake>
</nex>

length is the number of range settings to reset.

12.2.2.7. Getting Matchmaking Session Settings

Gets the matchmaking session settings.

12.2.2.7.1. Request

GET /nex/matchmake/v2/session_setting/(name)

Gets the settings of one matchmaking session.

Parameters:

Name Details
name Specifies the matchmaking session settings to get. For more information, see the table below.Required

Request Examples:

GET /nex/matchmake/v2/session_setting/broaden_range_upper HTTP/1.1
GET /nex/matchmake/v2/session_setting/

Gets multiple matchmaking session settings.

Parameters:

Name Details
names Specifies the matchmaking session settings to get. You can specify multiple values, delimited by commas. For more information, see the table below.Required

Request Examples:

GET /nex/matchmake/v2/session_setting?names=broaden_range_upper,broaden_range_lower HTTP/1.1

name, names

Value Details
broaden_range_upper When broadening the range, the number of ranges to broaden upward.
broaden_range_lower When broadening the range, the number of ranges to broaden downward.
enable_maintenance_notification Whether a maintenance start notification event is sent to the client device. (1: maintenance start notification events are enabled; 0: maintenance start notification events are disabled.)

12.2.2.7.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <session_settings length="1">
      <session_setting>
        <name>broaden_range_upper</name>
        <value>2</value>
      </session_setting>
      <session_setting>
        <name>broaden_range_lower</name>
        <value>2</value>
      </session_setting>
    </session_settings>
  </matchmake>
</nex>

12.2.2.8. Getting All Matchmaking Session Settings

Gets all matchmaking session settings.

12.2.2.8.1. Request

GET /nex/matchmake/v2/session_settings

Request Examples:

GET /nex/matchmake/v2/session_settings HTTP/1.1

12.2.2.8.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <session_settings length="3">
      <session_setting>
        <name>broaden_range_lower</name>
        <value>2</value>
      </session_setting>
      <session_setting>
        <name>broaden_range_upper</name>
        <value>2</value>
      </session_setting>
      <session_setting>
        <name>enable_maintenance_notification</name>
        <value>0</value>
      </session_setting>
    </session_settings>
  </matchmake>
</nex>

12.2.2.9. Changing Matchmaking Session Settings

Changes the matchmaking session settings.

12.2.2.9.1. Request

PUT /nex/matchmake/v2/session_setting
POST /nex/matchmake/v2/session_setting/put

Request body

Element New Elements Details
change   Root element.Required
param change Specifies the data to change. Multiple users can be specified.Required
name param Specifies the matchmaking session settings. For more information, see the table below. Required
value param Specifies the value.Required

Request Examples:

PUT /nex/matchmake/v2/session_setting/ HTTP/1.1

<change>
  <param>
    <name>broaden_range_upper</name>
    <value>1</value>
  </param>
  <param>
    <name>broaden_range_lower</name>
    <value>1</value>
  </param>
  <param>
    <name>enable_maintenance_notification</name>
    <value>1</value>
  </param>
</change>

name

Value Details
broaden_range_upper When broadening the range, the number of ranges to broaden upward.
broaden_range_lower When broadening the range, the number of ranges to broaden downward.
enable_maintenance_notification Whether a maintenance start notification event is sent to the client device. (1: maintenance start notification events are enabled; 0: maintenance start notification events are disabled.)

12.2.2.9.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <session_settings>
      <changed length="3"/>
    </session_settings>
  </matchmake>
</nex>

length is the number of changed matchmaking session settings.

12.2.3. API for the Auto-Matchmaking by Scoring Feature

These functions are used when using the auto-matchmaking feature with scoring. For more information about this feature, see the descriptions for when MATCHMAKE_SELECTION_METHOD_SCORE_BASED is specified in Section 4.8.1 How to Select the Matchmaking Session. The values that can be retrieved and set with these functions are copied from the development environment when deploying to the Lotcheck and production environments.

12.2.3.1. Setting the Score Conversion Settings

Setting the score conversion settings. The score conversion settings are determined from values for each type such as rating value difference and distance from the other player. Multiple settings can be configured using setting_index, and which settings to use can be set from the client. Scores are specified corresponding to a value range set by specifying begin and end. For example the score could be 100 if the rating values differ by from 0 to 100, and 50 if they differ by from 100 to 200. If the value is not included in any of the configured ranges, the default score is used. The default score can be set by specifying -1 for both begin and end. If the default score is not set, zero is used for the default score. The sum of the scores calculated for each type is the total score. The matchmaking session with the highest total score is selected. By setting SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE, a matchmaking session is selected only if it exceeds a specified total score.

12.2.3.1.1. Request

PUT /nex/matchmake/v2/score_settings
POST /nex/matchmake/v2/score_settings/put

Request body

Element Name Parent Element Details
score_settings   Root element. Required
score_setting score_settings Score setting. Multiple settings can be specified, up to a maximum of 200. However, a maximum of 16 settings can be specified for a particular setting_index and type. Specify 0 to make the setting empty.
setting_index score_setting Setting index. You can specify a value greater than or equal to 0 and less than or equal to 0xffffffff. Required
type score_setting The type of parameters for score conversions. For more information, see the following table. You can specify a value from 1 to 9. Required
begin score_setting The lower bound of the range including this value. Specify -1 when specifying a default score. You can specify a value from 0 to 0x7fffffff or -1. Required
end score_setting The upper bound of the range excluding this value. Specify -1 when specifying a default score. You can specify a value from 0 to 0x7fffffff or -1. Required
score score_setting The score when the value is within the range from begin to end. Specify -1 when specifying a default score. You can specify a value from 0 to 10000. Required

Request Examples:

PUT /nex/matchmake/v2/score_settings HTTP/1.1

<score_settings>
  <score_setting>
    <setting_index>0</setting_index>
    <type>1</type>
    <begin>-1</begin>
    <end>-1</end>
    <score>100</score>
  </score_setting>
  <score_setting>
    <setting_index>0</setting_index>
    <type>2</type>
    <begin>0</begin>
    <end>100</end>
    <score>100</score>
  </score_setting>
  <score_setting>
    <setting_index>0</setting_index>
    <type>2</type>
    <begin>100</begin>
    <end>200</end>
    <score>50</score>
  </score_setting>
  <score_setting>
    <setting_index>0</setting_index>
    <type>3</type>
    <begin>0</begin>
    <end>10</end>
    <score>100</score>
  </score_setting>
  <score_setting>
    <setting_index>0</setting_index>
    <type>3</type>
    <begin>10</begin>
    <end>20</end>
    <score>50</score>
  </score_setting>
</score_settings>

In this example, the minimum score for a match is 100, the score is 100 if the rating value difference is between 0 and 100, and the score is 50 if it is between 100 and 200. If the rating value difference is greater than that, the score is 0. Also, a score of 100 is allocated if the difference in the disconnection rate is between 0 and 10, and a score of 50 is allocated if it is between 10 and 20. If the disconnect rate difference is greater than that, the score is 0.

type

Name Value Description
SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE 1 Minimum score for a match. Any score below this value will not match. Only the default score can be specified.
SCORE_CONVERSION_TYPE_RATING_VALUE_DIFF 2 Conversion of a rating value difference to a score.
SCORE_CONVERSION_TYPE_DISCONNECTION_RATE_DIFF 3 Conversion of a disconnect rate (%) difference to a score.
SCORE_CONVERSION_TYPE_VIOLATION_RATE_DIFF 4 Conversion of a violation rate (%) difference to a score.
SCORE_CONVERSION_TYPE_DISTANCE 5 Conversion of a distance (km) to a score. If the distance cannot be obtained using GeoIP, or false has been specified to the MatchmakeParam::SetUseGeoIp function, the default score is used.
SCORE_CONVERSION_TYPE_MATCH_COUNTRY 6 The score when the countries are the same. A score when the value is 1 is used if the countries match, and a score when the value is 0 is used if they do not match.
SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE 7 The score when there is no distance information, but the countries match. A score when the value is 1 is used if the countries match, and a score when the value is 0 is used if they do not match.
SCORE_CONVERSION_TYPE_MATCHMAKE_SESSION_DURATION 8 Conversion of the matchmaking session duration (in seconds) to a score. By increasing the score value as time elapses, you can prevent the situation where matchmaking players cannot be found.
SCORE_CONVERSION_TYPE_MATCHMAKE_SESSION_PROGRESS 9 Conversion of matchmaking session progress to a score.

As with SCORE_CONVERSION_TYPE_RATING_VALUE_DIFF, SCORE_CONVERSION_TYPE_DISCONNECTION_RATE_DIFF, and SCORE_CONVERSION_TYPE_VIOLATION_RATE_DIFF, it converts the difference in value between the current and other user into a score. There are no particular restrictions on the range of values. Using this to compare the parameters other than disconnection rate and violation rate is not a problem. For distance calculation, the latitude and longitude at the city level are estimated from the IP addresses of the matchmaking session owner and the other player who searches the session, and the distance is calculated from those coordinates, taking the Internet path into consideration. The calculation does not use the path through the North or South Poles, and it is set to be somewhat difficult crossing the Eurasian continent. The reason for this is that communication actually passes through North America between Japan and Europe, and between Europe and Australia. As distances increase, so does RTT. In fact, RTT varies greatly for individual environments, but in typical cases, it is approximately 200 ms for 10,000 km, 300 ms for 20,000 km, and 400 ms for 30,000 km.

Example settings when the maximum score allocated for distance and country set to 1000

Distance's begin Distance's end score
0 1250 750
1250 2500 600
2500 5000 450
5000 10000 300
10000 20000 150

The score is 250 if the countries match, and the score is 500 if the countries match with no distance information.

Typical distances between regions

Region 1 Region 2 Distance (km)
Tokyo London 25000
Tokyo New York 16000
Tokyo San Francisco 11000
Tokyo Sydney 8000
Tokyo Singapore 5500
Tokyo Taipei 2500
London San Francisco 14000
London New York 8500
London Moscow 4500
London Berlin 1500
Sydney London 25500
Sydney New York 17500
Sydney San Francisco 13000
Sydney Singapore 6500
San Francisco New York 5500
San Francisco Vancouver 2000

12.2.3.1.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <score_settings>
      <set length="5" />
    </score_settings>
  </matchmake>
</nex>

length is the number of score_settings set.

12.2.3.1.3. Settings Examples

Settings for auto-matchmaking by scoring may not always produce the intended behavior depending on the value set for the minimum match score (SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE). If you set a minimum match score that is easily exceeded by the overall score, no new matchmaking sessions will be created. Users will end up joining existing matchmaking sessions with vacancies, which cancels out the effect of using auto-matchmaking by scoring in the first place. You must configure the settings such that the match score is low for users who are geographically far apart and have different connection speeds and disconnection rates so that they are not matched together.

12.2.3.1.3.1. Example 1: Distance

Prioritize the geographical distance between users. The following settings allow connections between Japan and the US but do not allow connections between Japan and Europe.

settingIndex type begin end score  
0 1(SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE) -1 -1 20 *1
0 5(SCORE_CONVERSION_TYPE_DISTANCE) -1 -1 0  
0 5 0 1250 90  
0 5 1250 2500 80  
0 5 2500 5000 60  
0 5 5000 10000 40  
0 5 10000 20000 20 *2
0 6(SCORE_CONVERSION_TYPE_MATCH_COUNTRY) 0 1 0  
0 6 1 2 10  
0 7(SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE) 0 1 20 *3
0 7 1 2 40 *4

Note the score for SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE, where the distance cannot be calculated and the countries do not match (the row marked with *2). If this value was set to 0, users would not be matched unless they were in the same country. This value must be increased so that it matches the minimum match score threshold (row *1). To not allow connections between Japan and the US, delete row *2, change the scores in rows *1 and *3 to 40, and change the score in row *4 to 60.

12.2.3.1.3.2. Example 2: Distance + Difference in Ratings

This example adds the difference in ratings to the geographical distance-based scoring method used in the previous example. There are 10 rating levels (0 to 9), and users with a difference of more than 3 between ratings are not matched.

settingIndex type begin end score
0 1(SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE) -1 -1 120
0 5(SCORE_CONVERSION_TYPE_DISTANCE) -1 -1 0
0 5 0 1250 90
0 5 1250 2500 80
0 5 2500 5000 60
0 5 5000 10000 40
0 5 10000 20000 20
0 6(SCORE_CONVERSION_TYPE_MATCH_COUNTRY) 0 1 0
0 6 1 2 10
0 7(SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE) 0 1 20
0 7 1 2 40
0 2(SCORE_CONVERSION_TYPE_RATING_VALUE_DIFF) 0 1 140
0 2 1 2 120
0 2 2 3 100
0 2 3 10 0

Set the scores for matching by differences in ratings to values more than 100, and set the minimum match score to 120. With these settings, if the score due to the ratings parameter is 0, users are not matched regardless of their geographical distance from each other.

12.2.3.1.3.3. Example 3: Distance + Difference in Ratings + Difference in Disconnection Rate

This example adds the difference disconnection rate to the geographical distance plus the difference in the ratings-based scoring method. Users are not matched if their disconnection rates differ by more than 30%.

settingIndex type begin end score
0 1(SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE) -1 -1 220
0 5(SCORE_CONVERSION_TYPE_DISTANCE) -1 -1 0
0 5 0 1250 90
0 5 1250 2500 80
0 5 2500 5000 60
0 5 5000 10000 40
0 5 10000 20000 20
0 6(SCORE_CONVERSION_TYPE_MATCH_COUNTRY) 0 1 0
0 6 1 2 10
0 7(SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE) 0 1 20
0 7 1 2 40
0 2(SCORE_CONVERSION_TYPE_RATING_VALUE_DIFF) 0 1 140
0 2 1 2 120
0 2 2 3 100
0 2 3 10 0
0 3(SCORE_CONVERSION_TYPE_DISCONNECTION_RATE_DIFF) 0 10 140
0 3 10 20 120
0 3 20 30 100
0 3 30 101 0

Similar to the difference in ratings example, this example sets the scores for matching by differences in disconnection rates to values more than 100, and sets the minimum match score to 220. With these settings, if the score due to the disconnection rate parameter is 0, users are not matched regardless of their geographical distance from each other or their ratings.

12.2.3.1.3.4. Example 4: Distance + Difference in Ratings + Difference in Disconnection Rate + Matchmaking Session Duration

In the examples above, there are cases where depending on matchmaking conditions, users may never be matched into a matchmaking session. To avoid this, you can increase the match score according to the duration of the existing matchmaking session. To use this setting, you must either destroy each matchmaking session as soon as the game is over or use the UpdateMatchmakeSessionParam::SetOpenParticipation and UpdateMatchmakeSessionParam::SetStartedTime functions to open the matchmaking session to participation and update the session start time to the current time when you call the MatchmakeExtensionClient::UpdateMatchmakeSession function.

settingIndex type begin end score
0 1(SCORE_CONVERSION_TYPE_MINIMUM_MATCH_SCORE) -1 -1 220
0 5(SCORE_CONVERSION_TYPE_DISTANCE) -1 -1 0
0 5 0 1250 90
0 5 1250 2500 80
0 5 2500 5000 60
0 5 5000 10000 40
0 5 10000 20000 20
0 6(SCORE_CONVERSION_TYPE_MATCH_COUNTRY) 0 1 0
0 6 1 2 10
0 7(SCORE_CONVERSION_TYPE_MATCH_COUNTRY_WITHOUT_DISTANCE) 0 1 20
0 7 1 2 40
0 2(SCORE_CONVERSION_TYPE_RATING_VALUE_DIFF) 0 1 140
0 2 1 2 120
0 2 2 3 100
0 2 3 10 0
0 3(SCORE_CONVERSION_TYPE_DISCONNECTION_RATE_DIFF) 0 10 140
0 3 10 20 120
0 3 20 30 100
0 3 30 101 0
0 8(SCORE_CONVERSION_TYPE_MATCHMAKE_SESSION_DURATION) 0 30 0
0 8 30 60 100
0 8 60 120 200
0 8 120 2147483647 220

With these settings, a value of 100 is added to the match score for the period of time from 30 to 60 seconds after the matchmaking session opens for participation. A value of 200 is added to the match score for the period of time from 60 to 120 seconds after the session opens for participation. After 120 seconds, a value of 220 is added to the match score, which means that even if the match score for all the other parameters is 0, users will still always be matched into a matchmaking session. If you do not want users separated by a geographical distance of more than 20,000 km to be matched even after a long time has elapsed, set the match score value for the period of time starting 120 seconds after the session opens for participation to 200.

Contact SDSG at support@noa.nintendo.com if you have difficulty setting the values for your matchmaking algorithm even after consulting the examples.

12.2.3.1.3.5. Setting Values on NMAS Using a CSV File

You can also set these values on NMAS using a CSV file. To set the values used in example 3 (Distance + Difference in Ratings + Difference in Disconnection Rate), the CSV file would look like the following.

#settingIndex,type,begin,end,score
0,1,-1,-1,220
0,5,-1,-1,0
0,5,0,1250,90
0,5,1250,2500,80
0,5,2500,5000,60
0,5,5000,10000,40
0,5,10000,20000,20
0,6,0,1,0
0,6,1,2,10
0,7,0,1,20
0,7,1,2,40
0,2,0,1,140
0,2,1,2,120
0,2,2,3,100
0,2,3,10,0
0,3,0,10,140
0,3,10,20,120
0,3,20,30,100
0,3,30,101,0

12.2.3.2. Getting the Score Conversion Settings

Gets score conversion settings.

12.2.3.2.1. Request

GET /nex/matchmake/v2/score_settings

Request Examples:

GET /nex/matchmake/v2/score_settings HTTP/1.1

12.2.3.2.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <score_settings length="5">
      <score_setting>
        <setting_index>0</setting_index>
        <type>1</type>
        <begin>-1</begin>
        <end>-1</end>
        <score>100</score>
      </score_setting>
      <score_setting>
        <setting_index>0</setting_index>
        <type>2</type>
        <begin>0</begin>
        <end>100</end>
        <score>100</score>
      </score_setting>
      <score_setting>
        <setting_index>0</setting_index>
        <type>2</type>
        <begin>100</begin>
        <end>200</end>
        <score>50</score>
      </score_setting>
      <score_setting>
        <setting_index>0</setting_index>
        <type>3</type>
        <begin>0</begin>
        <end>10</end>
        <score>100</score>
      </score_setting>
      <score_setting>
        <setting_index>0</setting_index>
        <type>3</type>
        <begin>10</begin>
        <end>20</end>
        <score>50</score>
      </score_setting>
    </score_settings>
  </matchmake>
</nex>

12.2.3.3. Getting Matchmaking Referee Settings

Gets matchmaking referee settings.

12.2.3.3.1. Request

GET /nex/matchmake/v2/referee_setting/(name)

Gets the settings of a single matchmaking referee.

Parameters:

Name Content
name The matchmaking referee settings to get. For more information, see the table below.Required

Request Examples:

GET /nex/matchmake/v2/referee_setting/history_length HTTP/1.1

name

Value Content
history_length The number of entries to leave in the recent history. The valid range is from 1 to 100. The default value is 100.

12.2.3.3.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <referee_settings length="1">
      <referee_setting>
        <name>history_length</name>
        <value>100</value>
      </referee_setting>
    </referee_settings>
  </matchmake>
</nex>

12.2.3.4. Getting All Matchmaking Referee Settings

Gets all matchmaking referee settings.

12.2.3.4.1. Request

GET /nex/matchmake/v2/referee_settings

Request Examples:

GET /nex/matchmake/v2/referee_settings HTTP/1.1

12.3.2.4.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <referee_settings length="1">
      <referee_setting>
        <name>history_length</name>
        <value>100</value>
      </referee_setting>
    </referee_settings>
  </matchmake>
</nex>

12.2.3.5. Changing Matchmaking Referee Settings

Changes the matchmaking referee settings.

12.2.3.5.1. Request

PUT /nex/matchmake/v2/referee_setting
POST /nex/matchmake/v2/referee_setting/put

Request body

Element Parent Element Content
change   Root element.Required
param change Specifies the data to change. Multiple users can be specified.Required
name param Matchmaking referee setting. For more information, see the table below.Required
value param Specifies the value.Required

Request Examples:

PUT /nex/matchmake/v2/referee_setting/ HTTP/1.1

<change>
  <param>
    <name>history_length</name>
    <value>30</value>
  </param>
</change>

name

Value Content
history_length The number of entries to leave in the recent history. The valid range is from 1 to 100. The default value is 100.

12.2.3.5.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <referee_settings>
      <changed length="1"/>
    </referee_settings>
  </matchmake>
</nex>

length is the number of changed matchmaking referee settings.

12.2.4. Common API Functions

The version is not specified in this API function.

12.2.4.1. Getting the Version

Gets the version.

12.2.4.1.1. Request

GET /nex/matchmake/version

Request Examples:

GET /nex/matchmake/version HTTP/1.1

12.2.4.1.2. Response

HTTP/1.1 200 OK
Content-Type:  text/xml;charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<nex>
  <matchmake>
    <api_version>2</api_version>
    <ngs_version>3.6.2.</ngs_version>
  </matchmake>
</nex>

ngs_version

The string showing the NGS version is formatted "(MAJOR VERSION).(MINOR VERSION).(MICRO VERSION).(PATCH VERSION)". The patch version is usually blank. Special versions for specific titles have a game code added.


CONFIDENTIAL