Use X-Ray for custom matchmaking
This article walks you through how to use the AccelByte Gaming Services (AGS) matchmaking X-Ray tool for custom matchmaking in your game.
Prerequisites
- An understanding of Matchmaking customization.
- An environment with AGS version 3.76 or later.
- For the matchmaking X-Ray to be able to track the ticket, add the
"ticket_observability_enable": true
parameter into your matchmaking ruleset.
Send matchmaking process data
To enable the X-Ray feature to scrape the data of matchmaking tickets in your custom matchmaking, your custom matchmaking apps should call this endpoint:
POST <baseURL>/sessionhistory/v2/admin/namespaces/<namespace>/xray/tickets
There are several actions that you can use when sending the matchmaking process data. Each action shares the same payload structure, aside from the action below if the ticket is started, canceled, or expired is already sent to the session history as default.
matchFound
: use this action to track the data of a matched ticket.matchNotFound
: use this action to track the data of a ticket that is still in the queue and not is yet to be matched before the timeout period.flexed
: use this action to track the data of a ticket that is in flexed state.
Matchmaking process
This diagram shows when you should call the POST <baseURL>/sessionhistory/v2/admin/namespaces/<namespace>/xray/tickets
endpoint during the matchmaking process.
Sample code
The following pseudocode shows a common scenario of when the POST <baseURL>/sessionhistory/v2/admin/namespaces/<namespace>/xray/tickets
endpoint is called.
Pseudocode
function MakeMatches():
if isRuleFlexed == "yes":
callEndpoint("Publish ticket observability", "Flexed")
if IsMatched == "yes":
callEndpoint("Publish ticket observability", "matchFound")
else:
callEndpoint("Publish ticket observability", "matchNotFound")
X-Rays only scrape and expose data sent by the custom matchmaking. If there are fields that are not filled, they will not be displayed in the X-Ray.
Ensure that you call the endpoint every time you want to send the ticket data. In each iteration of the matchmaking process (referred to as a "loop"), you can send data multiple times within a single matchmaking ticket since the flexed
and matchNotFound
actions are sent once every loop.
Sample request body template
{
"action": "string",
"activeAllianceRule": {
"max_number": 0,
"min_number": 0,
"player_max_number": 0,
"player_min_number": 0
},
"activeMatchingRule": [
{
"attribute": "string",
"criteria": "string",
"reference": 0
}
],
"function": "string",
"gameMode": "string",
"isBackfillMatch": true,
"isRuleSetFlexed": true,
"iteration": 0,
"matchID": "string",
"namespace": "string",
"partyID": "string",
"remainingPlayersPerTicket": [
0
],
"remainingTickets": 0,
"sessionTickID": "string",
"tickID": 0,
"timeToMatchSec": 0,
"timestamp": "2024-07-23T07:07:56.067Z",
"unbackfillReason": "string",
"unmatchReason": "string"
}
This table describes each field in the request body.
Field name | Field description | Required | Value format |
---|---|---|---|
PartyID | Ticket Party ID | No | Time (Example: "2024-07-23T07:07:56.067Z" ) |
MatchID | Match ID will be filled only when match found | No | String |
Namespace | Ticket current namespace | No | String |
GameMode | Ticket current matchpool | No | String |
ActiveAllianceRule | Current active alliance ruleset | No | JSON (See sample value.) |
ActiveMatchingRule | Current active matching ruleset | No | JSON (See sample value.) |
Function | Name of the function that called the endpoint | No | String |
Iteration | Total iteration before the match found | No | Integer |
TimeToMatchSec | Time to match (in seconds) will be filled only when match found | No | Float64 |
UnmatchReason | Reason when unable to find match | No | String |
RemainingTickets | Remaining ticket when unable to find match | No | Integer |
RemainingPlayersPerTicket | Remaining players when unable to find match | No | Integer |
UnbackfillReason | Reason when unable to backfill | No | String |
IsBackfillMatch | Flag to distinguish between new match and backfill match | No | Boolean |
IsRuleSetFlexed | Flag if ruleset is getting flexed | No | Boolean |
TickID | ID of the matchmaking ticket | No | Int64 |
SessionTickID | Session ticket ID to differentiate session when doing matches | No | String |
You can find the data sent by your custom matchmaking in Multiplayer > Diagnostics and Utilities > Matchmaking X-Ray on the AGS Admin Portal.
Although all of the fields in the request body are optional, they are still captured by the X-Ray. No other fields will be exposed or captured. For example, if you have a matchingRules
field that depends on a specific composition for matching, you will need to inject its value into activeAllianceRule
.
Sample ActiveAllianceRule value
[
{
"max_number": 0,
"min_number": 0,
"player_max_number": 0,
"player_min_number": 0
}
]
Sample ActiveMatchingRule value
[
{
"attribute": "string",
"criteria": "string",
"reference": 0
}
]