Open Match API References

This document provides API references for Open Match services.

Protocol Documentation

Table of Contents

Top

api/backend.proto

AssignTicketsRequest

Field Type Label Description
assignments AssignmentGroup repeated Assignments is a list of assignment groups that contain assignment and the Tickets to which they should be applied.

AssignTicketsResponse

Field Type Label Description
failures AssignmentFailure repeated Failures is a list of all the Tickets that failed assignment along with the cause of failure.

AssignmentFailure

AssignmentFailure contains the id of the Ticket that failed the Assignment and the failure status.

Field Type Label Description
ticket_id string
cause AssignmentFailure.Cause

AssignmentGroup

AssignmentGroup contains an Assignment and the Tickets to which it should be applied.

Field Type Label Description
ticket_ids string repeated TicketIds is a list of strings representing Open Match generated Ids which apply to an Assignment.
assignment Assignment An Assignment specifies game connection related information to be associated with the TicketIds.

FetchMatchesRequest

Field Type Label Description
config FunctionConfig A configuration for the MatchFunction server of this FetchMatches call.
profile MatchProfile A MatchProfile that will be sent to the MatchFunction server of this FetchMatches call.

FetchMatchesResponse

Field Type Label Description
match Match A Match generated by the user-defined MMF with the specified MatchProfiles. A valid Match response will contain at least one ticket.

FunctionConfig

FunctionConfig specifies a MMF address and client type for Backend to establish connections with the MMF

Field Type Label Description
host string
port int32
type FunctionConfig.Type

ReleaseAllTicketsRequest

ReleaseAllTicketsResponse

ReleaseTicketsRequest

Field Type Label Description
ticket_ids string repeated TicketIds is a list of string representing Open Match generated Ids to be re-enabled for MMF querying because they are no longer awaiting assignment from a previous match result

ReleaseTicketsResponse

AssignmentFailure.Cause

Name Number Description
UNKNOWN 0
TICKET_NOT_FOUND 1

FunctionConfig.Type

Name Number Description
GRPC 0
REST 1

BackendService

The BackendService implements APIs to generate matches and handle ticket assignments.

Method Name Request Type Response Type Description
FetchMatches FetchMatchesRequest FetchMatchesResponse stream FetchMatches triggers a MatchFunction with the specified MatchProfile and returns a set of matches generated by the Match Making Function, and accepted by the evaluator. Tickets in matches returned by FetchMatches are moved from active to pending, and will not be returned by query.
AssignTickets AssignTicketsRequest AssignTicketsResponse AssignTickets overwrites the Assignment field of the input TicketIds.
ReleaseTickets ReleaseTicketsRequest ReleaseTicketsResponse ReleaseTickets moves tickets from the pending state, to the active state. This enables them to be returned by query, and find different matches.

BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. | | ReleaseAllTickets | ReleaseAllTicketsRequest | ReleaseAllTicketsResponse | ReleaseAllTickets moves all tickets from the pending state, to the active state. This enables them to be returned by query, and find different matches.

BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal. |

Top

api/evaluator.proto

EvaluateRequest

Field Type Label Description
match Match A Matches proposed by the Match Function representing a candidate of the final results.

EvaluateResponse

Field Type Label Description
match_id string A Match ID representing a shortlisted match returned by the evaluator as the final result.

Evaluator

The Evaluator service implements APIs used to evaluate and shortlist matches proposed by MMFs.

Method Name Request Type Response Type Description
Evaluate EvaluateRequest stream EvaluateResponse stream Evaluate evaluates a list of proposed matches based on quality, collision status, and etc, then shortlist the matches and returns the final results.

Top

api/extensions.proto

DefaultEvaluationCriteria

A DefaultEvaluationCriteria is used for a match's evaluation_input when using the default evaluator.

Field Type Label Description
score double

Top

api/frontend.proto

CreateTicketRequest

Field Type Label Description
ticket Ticket A Ticket object with SearchFields defined.

DeleteTicketRequest

Field Type Label Description
ticket_id string A TicketId of a generated Ticket to be deleted.

GetTicketRequest

Field Type Label Description
ticket_id string A TicketId of a generated Ticket.

WatchAssignmentsRequest

Field Type Label Description
ticket_id string A TicketId of a generated Ticket to get updates on.

WatchAssignmentsResponse

Field Type Label Description
assignment Assignment An updated Assignment of the requested Ticket.

FrontendService

The FrontendService implements APIs to manage and query status of a Tickets.

Method Name Request Type Response Type Description
CreateTicket CreateTicketRequest Ticket CreateTicket assigns an unique TicketId to the input Ticket and record it in state storage. A ticket is considered as ready for matchmaking once it is created. - If a TicketId exists in a Ticket request, an auto-generated TicketId will override this field. - If SearchFields exist in a Ticket, CreateTicket will also index these fields such that one can query the ticket with query.QueryTickets function.
DeleteTicket DeleteTicketRequest .google.protobuf.Empty DeleteTicket immediately stops Open Match from using the Ticket for matchmaking and removes the Ticket from state storage. The client should delete the Ticket when finished matchmaking with it.
GetTicket GetTicketRequest Ticket GetTicket get the Ticket associated with the specified TicketId.
WatchAssignments WatchAssignmentsRequest WatchAssignmentsResponse stream WatchAssignments stream back Assignment of the specified TicketId if it is updated. - If the Assignment is not updated, GetAssignment will retry using the configured backoff strategy.

Top

api/matchfunction.proto

RunRequest

Field Type Label Description
profile MatchProfile A MatchProfile defines constraints of Tickets in a Match and shapes the Match proposed by the MatchFunction.

RunResponse

Field Type Label Description
proposal Match A Proposal represents a Match candidate that satifies the constraints defined in the input Profile. A valid Proposal response will contain at least one ticket.

MatchFunction

The MatchFunction service implements APIs to run user-defined matchmaking logics.

Method Name Request Type Response Type Description
Run RunRequest RunResponse stream DO NOT CALL THIS FUNCTION MANUALLY. USE backend.FetchMatches INSTEAD. Run pulls Tickets that satisify Profile constraints from QueryService, runs matchmaking logics against them, then constructs and streams back match candidates to the Backend service.

Top

api/messages.proto

Assignment

An Assignment represents a game server assignment associated with a Ticket. Open Match does not require or inspect any fields on assignment.

Field Type Label Description
connection string Connection information for this Assignment.
extensions Assignment.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.

Assignment.ExtensionsEntry

Field Type Label Description
key string
value google.protobuf.Any

DoubleRangeFilter

Filters numerical values to only those within a range. double_arg: "foo" max: 10 min: 5 matches: {"foo": 5} {"foo": 7.5} {"foo": 10} does not match: {"foo": 4} {"foo": 10.01} {"foo": "7.5"} {}

Field Type Label Description
double_arg string Name of the ticket's search_fields.double_args this Filter operates on.
max double Maximum value.
min double Minimum value.

Match

A Match is used to represent a completed match object. It can be generated by a MatchFunction as a proposal or can be returned by OpenMatch as a result in response to the FetchMatches call. When a match is returned by the FetchMatches call, it should contain at least one ticket to be considered as valid.

Field Type Label Description
match_id string A Match ID that should be passed through the stack for tracing.
match_profile string Name of the match profile that generated this Match.
match_function string Name of the match function that generated this Match.
tickets Ticket repeated Tickets belonging to this match.
extensions Match.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.

Match.ExtensionsEntry

Field Type Label Description
key string
value google.protobuf.Any

MatchProfile

A MatchProfile is Open Match's representation of a Match specification. It is used to indicate the criteria for selecting players for a match. A MatchProfile is the input to the API to get matches and is passed to the MatchFunction. It contains all the information required by the MatchFunction to generate match proposals.

Field Type Label Description
name string Name of this match profile.
pools Pool repeated Set of pools to be queried when generating a match for this MatchProfile.
extensions MatchProfile.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.

MatchProfile.ExtensionsEntry

Field Type Label Description
key string
value google.protobuf.Any

Pool

Pool specfies a set of criteria that are used to select a subset of Tickets that meet all the criteria.

Field Type Label Description
name string A developer-chosen human-readable name for this Pool.
double_range_filters DoubleRangeFilter repeated Set of Filters indicating the filtering criteria. Selected tickets must match every Filter.
string_equals_filters StringEqualsFilter repeated
tag_present_filters TagPresentFilter repeated
created_before google.protobuf.Timestamp If specified, only Tickets created before the specified time are selected.
created_after google.protobuf.Timestamp If specified, only Tickets created after the specified time are selected.

SearchFields

Search fields are the fields which Open Match is aware of, and can be used when specifying filters.

Field Type Label Description
double_args SearchFields.DoubleArgsEntry repeated Float arguments. Filterable on ranges.
string_args SearchFields.StringArgsEntry repeated String arguments. Filterable on equality.
tags string repeated Filterable on presence or absence of given value.

SearchFields.DoubleArgsEntry

Field Type Label Description
key string
value double

SearchFields.StringArgsEntry

Field Type Label Description
key string
value string

StringEqualsFilter

Filters strings exactly equaling a value. string_arg: "foo" value: "bar" matches: {"foo": "bar"} does not match: {"foo": "baz"} {"bar": "foo"} {}

Field Type Label Description
string_arg string Name of the ticket's search_fields.string_args this Filter operates on.
value string

TagPresentFilter

Filters to the tag being present on the search_fields. tag: "foo" matches: ["foo"] ["bar","foo"] does not match: ["bar"] []

Field Type Label Description
tag string

Ticket

A Ticket is a basic matchmaking entity in Open Match. A Ticket may represent an individual 'Player', a 'Group' of players, or any other concepts unique to your use case. Open Match will not interpret what the Ticket represents but just treat it as a matchmaking unit with a set of SearchFields. Open Match stores the Ticket in state storage and enables an Assignment to be set on the Ticket.

Field Type Label Description
id string Id represents an auto-generated Id issued by Open Match.
assignment Assignment An Assignment represents a game server assignment associated with a Ticket, or whatever finalized matched state means for your use case. Open Match does not require or inspect any fields on Assignment.
search_fields SearchFields Search fields are the fields which Open Match is aware of, and can be used when specifying filters.
extensions Ticket.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the match making function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.
create_time google.protobuf.Timestamp Create time is the time the Ticket was created. It is populated by Open Match at the time of Ticket creation.

Ticket.ExtensionsEntry

Field Type Label Description
key string
value google.protobuf.Any

Top

api/query.proto

QueryTicketIdsRequest

Field Type Label Description
pool Pool The Pool representing the set of Filters to be queried.

QueryTicketIdsResponse

Field Type Label Description
ids string repeated TicketIDs that meet all the filtering criteria requested by the pool.

QueryTicketsRequest

Field Type Label Description
pool Pool The Pool representing the set of Filters to be queried.

QueryTicketsResponse

Field Type Label Description
tickets Ticket repeated Tickets that meet all the filtering criteria requested by the pool.

QueryService

The QueryService service implements helper APIs for Match Function to query Tickets from state storage.

Method Name Request Type Response Type Description
QueryTickets QueryTicketsRequest QueryTicketsResponse stream QueryTickets gets a list of Tickets that match all Filters of the input Pool. - If the Pool contains no Filters, QueryTickets will return all Tickets in the state storage. QueryTickets pages the Tickets by queryPageSize and stream back responses. - queryPageSize is default to 1000 if not set, and has a mininum of 10 and maximum of 10000.
QueryTicketIds QueryTicketIdsRequest QueryTicketIdsResponse stream QueryTicketIds gets the list of TicketIDs that meet all the filtering criteria requested by the pool. - If the Pool contains no Filters, QueryTicketIds will return all TicketIDs in the state storage. QueryTicketIds pages the TicketIDs by queryPageSize and stream back responses. - queryPageSize is default to 1000 if not set, and has a mininum of 10 and maximum of 10000.

Scalar Value Types

| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby | | ———– | —– | — | —- | —— | – | – | — | —- | | double | | double | double | float | float64 | double | float | Float | | float | | float | float | float | float32 | float | float | Float | | int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum | | uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) | | uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) | | sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum | | fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) | | fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum | | sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) | | sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum | | bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | | string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) | | bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |


Last modified January 1, 0001