Use X-Ray for custom matchmaking

Last updated on August 5, 2024

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")

note

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.

note

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
  }
]