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

AcknowledgeBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to acknowledge.
assignment Assignment An updated Assignment of the requested Backfill.

AcknowledgeBackfillResponse

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill The Backfill that was acknowledged.
tickets Ticket repeated All of the Tickets that were successfully assigned

CreateBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill An empty Backfill object.

CreateTicketRequest

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

DeleteBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to delete.

DeleteTicketRequest

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

GetBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to retrieve.

GetTicketRequest

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

UpdateBackfillRequest

UpdateBackfillRequest - update searchFields, extensions and set assignment.

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill A Backfill object with ID set and fields to update.

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.
AcknowledgeBackfill AcknowledgeBackfillRequest AcknowledgeBackfillResponse AcknowledgeBackfill is used to notify OpenMatch about GameServer connection info This triggers an assignment process. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
CreateBackfill CreateBackfillRequest Backfill CreateBackfill creates a new Backfill object. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
DeleteBackfill DeleteBackfillRequest .google.protobuf.Empty DeleteBackfill receives a backfill ID and deletes its resource. Any tickets waiting for this backfill will be returned to the active pool, no longer pending. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
GetBackfill GetBackfillRequest Backfill GetBackfill returns a backfill object by its ID. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
UpdateBackfill UpdateBackfillRequest Backfill UpdateBackfill updates search_fields and extensions for the backfill with the provided id. Any tickets waiting for this backfill will be returned to the active pool, no longer pending. 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/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 satisfy Profile constraints from QueryService, runs matchmaking logic 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

Backfill

Represents a backfill entity which is used to fill partially full matches.

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

Field Type Label Description
id string Id represents an auto-generated Id issued by Open Match.
search_fields SearchFields Search fields are the fields which Open Match is aware of, and can be used when specifying filters.
extensions Backfill.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the Match Function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.
persistent_field Backfill.PersistentFieldEntry repeated Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a backfill. 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.
generation int64 Generation gets incremented on GameServers update operations. Prevents the MMF from overriding a newer version from the game server. Do NOT read or write to this field, it is for internal tracking, and changing the value will cause bugs.

Backfill.ExtensionsEntry

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

Backfill.PersistentFieldEntry

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.
exclude DoubleRangeFilter.Exclude Defines the bounds to apply when filtering tickets by their search_fields.double_args value. BETA FEATURE WARNING: This field and the associated values are not finalized and still subject to possible change or removal.

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.
backfill Backfill Backfill request which contains additional information to the match and contains an association to a GameServer. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal.
allocate_gameserver bool AllocateGameServer signalise Director that Backfill is new and it should allocate a GameServer, this Backfill would be assigned. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal.

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.
persistent_field Ticket.PersistentFieldEntry repeated Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a ticket. 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

Ticket.PersistentFieldEntry

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

DoubleRangeFilter.Exclude

Name Number Description
NONE 0 No bounds should be excluded when evaluating the filter, i.e.: MIN <= x <= MAX
MIN 1 Only the minimum bound should be excluded when evaluating the filter, i.e.: MIN < x <= MAX
MAX 2 Only the maximum bound should be excluded when evaluating the filter, i.e.: MIN <= x < MAX
BOTH 3 Both bounds should be excluded when evaluating the filter, i.e.: MIN < x < MAX

Top

api/query.proto

QueryBackfillsRequest

BETA FEATURE WARNING: This Request messages are not finalized and still subject to possible change or removal.

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

QueryBackfillsResponse

BETA FEATURE WARNING: This Request messages are not finalized and still subject to possible change or removal.

Field Type Label Description
backfills Backfill repeated Backfills that meet all the filtering criteria requested by the pool.

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 minimum 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 minimum of 10 and maximum of 10000.
QueryBackfills QueryBackfillsRequest QueryBackfillsResponse stream QueryBackfills gets a list of Backfills. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.

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)

title: “Open Match API References” linkTitle: “Open Match API References” weight: 2 description: 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

AcknowledgeBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to acknowledge.
assignment Assignment An updated Assignment of the requested Backfill.

AcknowledgeBackfillResponse

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill The Backfill that was acknowledged.
tickets Ticket repeated All of the Tickets that were successfully assigned

CreateBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill An empty Backfill object.

CreateTicketRequest

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

DeleteBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to delete.

DeleteTicketRequest

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

GetBackfillRequest

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill_id string An existing ID of Backfill to retrieve.

GetTicketRequest

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

UpdateBackfillRequest

UpdateBackfillRequest - update searchFields, extensions and set assignment.

BETA FEATURE WARNING: This Request message is not finalized and still subject to possible change or removal.

Field Type Label Description
backfill Backfill A Backfill object with ID set and fields to update.

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.
AcknowledgeBackfill AcknowledgeBackfillRequest AcknowledgeBackfillResponse AcknowledgeBackfill is used to notify OpenMatch about GameServer connection info This triggers an assignment process. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
CreateBackfill CreateBackfillRequest Backfill CreateBackfill creates a new Backfill object. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
DeleteBackfill DeleteBackfillRequest .google.protobuf.Empty DeleteBackfill receives a backfill ID and deletes its resource. Any tickets waiting for this backfill will be returned to the active pool, no longer pending. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
GetBackfill GetBackfillRequest Backfill GetBackfill returns a backfill object by its ID. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.
UpdateBackfill UpdateBackfillRequest Backfill UpdateBackfill updates search_fields and extensions for the backfill with the provided id. Any tickets waiting for this backfill will be returned to the active pool, no longer pending. 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/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 satisfy Profile constraints from QueryService, runs matchmaking logic 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

Backfill

Represents a backfill entity which is used to fill partially full matches.

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

Field Type Label Description
id string Id represents an auto-generated Id issued by Open Match.
search_fields SearchFields Search fields are the fields which Open Match is aware of, and can be used when specifying filters.
extensions Backfill.ExtensionsEntry repeated Customized information not inspected by Open Match, to be used by the Match Function, evaluator, and components making calls to Open Match. Optional, depending on the requirements of the connected systems.
persistent_field Backfill.PersistentFieldEntry repeated Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a backfill. 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.
generation int64 Generation gets incremented on GameServers update operations. Prevents the MMF from overriding a newer version from the game server. Do NOT read or write to this field, it is for internal tracking, and changing the value will cause bugs.

Backfill.ExtensionsEntry

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

Backfill.PersistentFieldEntry

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.
exclude DoubleRangeFilter.Exclude Defines the bounds to apply when filtering tickets by their search_fields.double_args value. BETA FEATURE WARNING: This field and the associated values are not finalized and still subject to possible change or removal.

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.
backfill Backfill Backfill request which contains additional information to the match and contains an association to a GameServer. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal.
allocate_gameserver bool AllocateGameServer signalise Director that Backfill is new and it should allocate a GameServer, this Backfill would be assigned. BETA FEATURE WARNING: This field is not finalized and still subject to possible change or removal.

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.
persistent_field Ticket.PersistentFieldEntry repeated Customized information not inspected by Open Match, to be kept persistent throughout the life-cycle of a ticket. 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

Ticket.PersistentFieldEntry

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

DoubleRangeFilter.Exclude

Name Number Description
NONE 0 No bounds should be excluded when evaluating the filter, i.e.: MIN <= x <= MAX
MIN 1 Only the minimum bound should be excluded when evaluating the filter, i.e.: MIN < x <= MAX
MAX 2 Only the maximum bound should be excluded when evaluating the filter, i.e.: MIN <= x < MAX
BOTH 3 Both bounds should be excluded when evaluating the filter, i.e.: MIN < x < MAX

Top

api/query.proto

QueryBackfillsRequest

BETA FEATURE WARNING: This Request messages are not finalized and still subject to possible change or removal.

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

QueryBackfillsResponse

BETA FEATURE WARNING: This Request messages are not finalized and still subject to possible change or removal.

Field Type Label Description
backfills Backfill repeated Backfills that meet all the filtering criteria requested by the pool.

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 minimum 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 minimum of 10 and maximum of 10000.
QueryBackfills QueryBackfillsRequest QueryBackfillsResponse stream QueryBackfills gets a list of Backfills. BETA FEATURE WARNING: This call and the associated Request and Response messages are not finalized and still subject to possible change or removal.

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 18, 2024