Open Match – Reference

Docs: Open Match API References

Mon, 01 Jan 0001 00:00:00 +0000

Protocol Documentation

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

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

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

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

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)

Docs: Glossary

Mon, 01 Jan 0001 00:00:00 +0000

Docker Image See in Action

Docker Images are sort of like a zip file that would contain your game binary and assets. It also contains a minimal operating system (~2-10MiB), environment variables, and other contexts.

The intent is that the image is portable between host machines (that can run different host OSes) but the application itself will run the same because all of its dependencies (ex: glibc, DLLs, etc) included without the need for virtualization. Docker Images are stored in Docker Image Repositories and are versioned.

Open Match uses distroless/static:nonroot images that provide just enough Linux OS to run a mostly-static binary. There are other flavors of distroless for popular languages.

Docker

Docker is what generally mean when they say “containers”. It allows you to run Docker Images on a host operating system. Containers provide a thin layer of isolation between the host and the application that makes it think it is running in its environment.

Kubernetes

You give Kubernetes a bunch of servers to run and it’ll figure out how where to run them based on available resources. The machines can be different shapes and sizes. You can declare how much CPU and RAM a container may consume before it’s throttled or killed respectively.

Kubernetes also provides a configurable private network that by default servers cannot communicate outside the network. It’s possible to open up ports through Service definitions.

Lastly, it provides configuration management including secrets (like passwords and auth tokens) and auto-healing (service health monitoring and restart).

Open Match uses Kubernetes to schedule and runs its services. It also uses secrets to hold TLS certificates and Redis passwords.

Helm See in Action

Helm is the Kubernetes package manager. It allows you to create Kubernetes deployments as templates and parameters. Helm deployments are called charts. For example, you can create an Open Match deployment that has 50 frontend servers via --set frontend.replicas=50.

Open Match uses Helm to simplify its Kubernetes deployment. By default, the Helm chart deploys Redis, Open Match, Prometheus, and Grafana.

Helm is not required for Open Match.

Terraform

Terraform provides a way to express your infrastructure-as-code. In other words, you can write a template that says “give me 20 machines each with 4 vCPUs and 32 GiB RAM that live in us-west1-b on the same network in GCP” and Terraform will make that happen. You can then change your configuration to have 25 machines and Terraform will add the additional 5.

Open Match does not use Terraform. We provide an example of a Terraform template that can be used to declare infrastructure you’d need to run it.

Terraform is not required for Open Match.

Docs: Presentations

Mon, 01 Jan 0001 00:00:00 +0000

Connecting Millions with GCP and Open Match in a Google Doodle Multiplayer Game (GDC ‘19)

https://www.youtube.com/watch?v=9Iolrk6GH4w

To celebrate this past Halloween, the Google Doodle team wanted to create their first multiplayer Doodle, which would be accessed by millions of Google search page visitors over 3 days. To achieve this scale, the Doodle team worked closely with GCP and leveraged the Google Cloud and Unity co-founded open source matchmaking framework, Open Match. In this session, they will discuss how they successfully executed this multiplayer experience.

Unity Berlin 2018 - The Future of Matchmaking with Unity and Google

https://www.youtube.com/watch?v=qasAmy_ko2o

Matchmaking is an essential component of today’s most popular multiplayer games. Unity is helping to lead a new open-source project designed to tackle this common and challenging aspect of multiplayer game creation. Learn how it works and how you can get involved.

Matchmaking Innovation & Best Practices with Unity (GDC ‘19)

https://www.youtube.com/watch?v=44gqtGRXmrg

Creating a multiplayer game? You’re going to need matchmaking! Google Cloud and Unity have been leading a new open source matchmaking project that’s extensible and scalable to millions of players. In this session, learn how Open Match works and how to innovate using standard matchmaking techniques, patterns, and best practices. Then, learn how Open Match is even more approachable and useful when combined with Unity’s game server hosting technology.

Open Match – Reference

Docs: Open Match API References

Protocol Documentation

Table of Contents

api/backend.proto

AssignTicketsRequest

AssignTicketsResponse

AssignmentFailure

AssignmentGroup

FetchMatchesRequest

FetchMatchesResponse

FunctionConfig

ReleaseAllTicketsRequest

ReleaseAllTicketsResponse

ReleaseTicketsRequest

ReleaseTicketsResponse

AssignmentFailure.Cause

FunctionConfig.Type

BackendService

api/evaluator.proto

EvaluateRequest

EvaluateResponse

Evaluator

api/extensions.proto

DefaultEvaluationCriteria

api/frontend.proto

AcknowledgeBackfillRequest

AcknowledgeBackfillResponse

CreateBackfillRequest

CreateTicketRequest

DeleteBackfillRequest

DeleteTicketRequest

GetBackfillRequest

GetTicketRequest

UpdateBackfillRequest

WatchAssignmentsRequest

WatchAssignmentsResponse

FrontendService

api/matchfunction.proto

RunRequest

RunResponse

MatchFunction

api/messages.proto

Assignment

Assignment.ExtensionsEntry

Backfill

Backfill.ExtensionsEntry

Backfill.PersistentFieldEntry

DoubleRangeFilter

Match

Match.ExtensionsEntry

MatchProfile

MatchProfile.ExtensionsEntry

Pool

SearchFields

SearchFields.DoubleArgsEntry

SearchFields.StringArgsEntry

StringEqualsFilter

TagPresentFilter

Ticket

Ticket.ExtensionsEntry

Ticket.PersistentFieldEntry

DoubleRangeFilter.Exclude

api/query.proto

QueryBackfillsRequest

QueryBackfillsResponse

QueryTicketIdsRequest

QueryTicketIdsResponse

QueryTicketsRequest

QueryTicketsResponse

QueryService

Scalar Value Types

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

api/backend.proto

AssignTicketsRequest

AssignTicketsResponse

AssignmentFailure

AssignmentGroup