Open Match – Open Match Documentation

Docs: Game Frontend

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

Overview

The Game Frontend receives the matchmaking request from the Player’s Game Client. It can authenticate the player and fetch the player data from some backend storage (or Platform Services if required). It submits the matchmaking request to Open Match by creating a Ticket. Once an Assignment is set for this Ticket, the Game Frontend communicates the Assignment back to the Game Client. Game Frontend may handle creating lobbies, groups, etc.

Open Match Interactions

Here are the key interactions the Game Frontend has with Open Match:

Creating a Ticket

The Game Frontend adds a new matchmaking request to Open Match by creating a Ticket using the following API on Open Match Frontend:

rpc CreateTicket(CreateTicketRequest) returns (Ticket) {
  option (google.api.http) = {
    post: "/v1/frontendservice/tickets"
    body: "*"
  };
}

Ticket

A Ticket represents a single matchmaking request in Open Match. It can represent a single Player or a group of Players. Here is a proto for the Ticket:

message Ticket {
  // Id represents an auto-generated Id issued by Open Match.
  string id = 1;

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

  // Search fields are the fields which Open Match is aware of, and can be used
  // when specifying filters.
  SearchFields search_fields = 4;

  // 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.
  map<string, google.protobuf.Any> extensions = 5;

  // Create time represents the time at which this Ticket was created. It is
  // populated by Open Match at the time of Ticket creation.
  google.protobuf.Timestamp create_time = 6;
}

SearchFields

When creating a Ticket, the Open Match frontend populates SearchFields which specify the properties for the Ticket that can be used for filtering the Tickets. SearchFields can be of different types (double, string, tag) and an appropriate one should be chosen based on the nature of the property and filtering requirements. Here is a sample SearchField specifying the MMR, role and game mode.

SearchFields: &pb.SearchFields{
  DoubleArgs: map[string]float64{"attribute.mmr": 50},
  StringArgs: map[string]string{"attribute.role": "warrior"},
  Tags: []string{"mode.demo"},
}

Fetching the Assignment

The Game Frontend can get the current Ticket from Open Match and check if the Ticket has Assignment information populated. Here are the APIs to get a Ticket and to get Assignment information respectively :

rpc GetTicket(GetTicketRequest) returns (Ticket) {
  option (google.api.http) = {
    get: "/v1/frontendservice/tickets/{ticket_id}"
  };
}

rpc WatchAssignments(WatchAssignmentsRequest)
    returns (stream WatchAssignmentsResponse) {
  option (google.api.http) = {
    get: "/v1/frontendservice/tickets/{ticket_id}/assignments"
  };
}

Note

Open Match does not guarantee persistent storage and hence should not be used as the authoritative source for Game Client Assignment information. Once the Assignment for a Ticket is fetched, the Game Frontent should (if necessary) persist this information in its own persistent storage for future lookup.

Deleting a Ticket

Once the player Assignment has been stored & communicated to the Game Client, the Game Frontend may delete the Ticket from Open Match. Here is the API exposed on Open Match Frontend to delete a Ticket:

rpc DeleteTicket(DeleteTicketRequest) returns (google.protobuf.Empty) {
  option (google.api.http) = {
    delete: "/v1/frontendservice/tickets/{ticket_id}"
  };
}

Docs: Install with YAML

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

Prerequisites

Kubernetes cluster, tested on Kubernetes version 1.27+

Install Core Open Match

Open Match comprises of a set of core services hosted in a Kubernetes cluster. The simplest way to install Open Match core is to use the 01-open-match-core.yaml for the latest release. This installs Open Match with the default configuration.

The 01-open-match-core.yaml contains:

Core Open Match service deployments.
A Redis deployment as Open Match’s state storage system.
HorizontalAutoScalars to auto-scale Open Match based on pods' average CPU utilization.

Here is the command to install the Open Match core in your cluster:

# Install the core Open Match services.
kubectl apply --namespace open-match \
  -f https://open-match.dev/install/v1.8.0/yaml/01-open-match-core.yaml

Note

The flag --namespace open-match is Required. Open Match may not work as expected without this flag.

After installing Open Match core services, here is the expected state for the pods for these services:

kubectl get -n open-match pod

Output:

NAME                                        READY   STATUS              RESTARTS   AGE
open-match-backend-76d8d76c96-fmhmn         0/1     ContainerCreating   0          3m53s
open-match-frontend-57fc9f6b66-86hxj        0/1     ContainerCreating   0          3m53s
open-match-query-799d8549d4-5qpgx           0/1     ContainerCreating   0          3m53s
open-match-swaggerui-867d79b885-m9q6x       0/1     ContainerCreating   0          3m54s
open-match-synchronizer-7f48f84dfd-j8swx    0/1     ContainerCreating   0          3m54s

Note

Open Match needs to be customized to run as a Matchmaker. This custom configuration is provided to the Open Match components via a ConfigMap (open-match-configmap-override).

Thus, starting the core service pods will remain in ContainerCreating until this config map is available.

If you are proceeding with the Getting Started, or following the Tutorials, proceed with this guide to install the default Evaluator and configure Open Match to use it.
If you finished reading the tutorials and are building your own custom matchmaker and need to deploy a custom evaluator, then skip the next step and instead use the Customization Guide for steps to customize your Open Match installation.

Install the Default Evaluator

Run the below command to install the default Evaluator in the open-match namespace and to configure Open Match to use it.

kubectl apply --namespace open-match \
  -f https://open-match.dev/install/v1.8.0/yaml/06-open-match-override-configmap.yaml \
  -f https://open-match.dev/install/v1.8.0/yaml/07-open-match-default-evaluator.yaml

Delete Open Match

To delete Open Match and the corresponding sample components from this cluster, simply run:

kubectl delete namespace open-match

What’s Next

Follow the Getting Started guide to see Open Match in action.

Docs: Step 1 - Build your own Game Frontend

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

Overview

The Game Frontend serves as a layer that transfers players' matchmaking requests from players' Game Client to proto messages that Open Match can understand. The Game Frontend typically performs the following tasks:

Fetches the player data from some backend storage (or Platform Services if required) and authenticates players.
Submits the matchmaking requests to Open Match by creating a Ticket.
Communicates the Assignment result back to the Game Client once Open Match found an Assignment for this Ticket.

This tutorial provides a very basic Game Frontend scaffold ($TUTORIALROOT/frontend) that periodically generates batches of fake Tickets, adds them to Open Match, and polls these Tickets for Assignment. Once an Assignment is received it emits a log with the Assignment details (as a proxy for returning the Assignment to the Player) and deletes the Ticket from Open Match.

Note

Under production environment, polling each Ticket for Assignment is not recommended. We recommend using event handlers/listeners to communicate Assignments result to the Game Frontend.

Links to API Definitions for this tutorial

pb.Ticket	frontend.CreateTicket	frontend.GetTicket	frontend.DeleteTicket

Make Changes

The Game Frontend uses a helper function makeTicket() in $TUTORIALROOT/frontend/ticket.go to generate a fake Ticket. Any property that is intended to be used for Matchmaking (for instance, game mode in this case) is set as a SearchField on the Ticket. For this tutorial, we create a Ticket that has a game mode specified as a Tag SearchField. The below code snippet picks a random game mode and sets it as a Tag on a fake Ticket.

func makeTicket() *pb.Ticket {
  modes := []string{"mode.demo", "mode.ctf", "mode.battleroyale"}
  ticket := &pb.Ticket{
    SearchFields: &pb.SearchFields{
      Tags: []string{
        modes[rand.Intn(len(modes))],
      },
    },
  }

  return ticket
}

Please copy the above helper or add your own fake Ticket creation logic to $TUTORIALROOT/frontend/ticket.go. Also, you may tweak the size of the Ticket creation batches, polling interval, etc. in $TUTORIALROOT/frontend/main.go.

Configuring

The following values need to be changed if your setup is different from the default in the $TUTORIALROOT/frontend/main.go. The default value assumes you have Open Match deployed under open-match namespace and the Game Frontend under mm101-tutorial namespace in the same cluster:

omFrontendEndpoint - Open Match Frontend endpoint

Build and Push

Now that you have customized the Game Frontend, please run the below commands from $TUTORIALROOT to build a new image and push it to your configured image registry.

# Build the Frontend image.
docker build -t $REGISTRY/mm101-tutorial-frontend frontend/

# Push the Frontend image to the configured Registry.
docker push $REGISTRY/mm101-tutorial-frontend

What’s Next

Let’s proceed to build the Director.

Docs: Director

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

Overview

The Director fetches Matches from Open Match for a set of MatchProfiles. For these matches, it fetches Game Server from a DGS allocation system. It can then communicate the Assignments back to the Game Frontend.

Open Match Interactions

Here are the key interactions the Director has with Open Match:

Fetching Matches

The Director can fetch matches for one or more MatchProfiles using the following API on Open Match Backend:

rpc FetchMatches(FetchMatchesRequest) returns (stream FetchMatchesResponse) {
  option (google.api.http) = {
    post: "/v1/backendservice/matches:fetch"
    body: "*"
  };
}

The request to fetch matches provides a FunctionConfig and one or more MatchProfile.

FunctionConfig

For every FetchMatches call, the Director can specify the details of which Match Function to trigger. It can do so by providing the configuration for the Match function, giving the host, port and the type of function endpoint to call.

message FunctionConfig {
  string host = 1;
  int32 port = 2;
  Type type = 3;
  enum Type {
    GRPC = 0;
    REST = 1;
  }
}

MatchProfile

MatchProfile is a representation of a Match specification. It bears the following information:

Profile name that is then specified in the generated matches to identify which profile a Match belongs to.
Pools of Tickets to be considered for the Match (each pool has the search criteria to filter players belonging to that Pool)
Roster (Optional) specifies a named grouping of Ticket Ids, primarily used in Backfill scenarios.

Here is a sample MatchProfile that specifies two different Pools of Tickets with tank and dps roles for a CTF game mode. The director could query concurrently for another MatchProfile that specifies the same roles but for a battle-royale game mode.

MatchProfile{
  Name:  "test_profile_name",
  Pools: {
    {
      Name: "pool_ctf_tank",
      TagPresentFilters: []*pb.TagPresentFilter{{Tag: "mode.ctf"}},
      StringEqualsFilters: []*pb.StringEqualsFilter{{
        StringArg: "attributes.role",
        Value:     "tank",
      }}
    },
    {
      Name: "pool_ctf_dps",
      TagPresentFilters: []*pb.TagPresentFilter{{Tag: "mode.ctf"}},
      StringEqualsFilters: []*pb.StringEqualsFilter{{
        StringArg: "attributes.role",
        Value:     "dps",
      }}
    },
  }
}

Assigning Tickets

Once a Match is generated, the Director can fetch a Game Server for this Match from the DGS (Dedicated Game Server) allocation system and then set that as an Assignment on all the Tickets of this Match. Here is the API on Open Match Backend to do this:

rpc AssignTickets(AssignTicketsRequest) returns (AssignTicketsResponse) {
  option (google.api.http) = {
    post: "/v1/backendservice/tickets:assign"
    body: "*"
};

The API takes a list of AssignmentGroups to make the Assignment and returns the AssignmentFailures if any.

Assignment

Here are the protos for the Assignment:

message AssignmentGroup{
  // TicketIds is a list of strings representing Open Match generated Ids which apply to an Assignment.
  repeated string ticket_ids = 1;

  // An Assignment specifies game connection related information to be associated with the TicketIds.
  Assignment assignment = 2;
}

message AssignmentFailure {
  enum Cause {
    UNKNOWN = 0;
    TICKET_NOT_FOUND = 1;
  }

  string ticket_id = 1;
  Cause cause = 2;
}

It comprises of the connection string, and a set of extension blobs that Open Match passes through.

Docs: Grafana: Go Processes

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

Here is a raintank snapshot to what you will see after navigating to the Go Processes dashboard.

Metric Name	Description
`CPU Usage Limit Percentage`	Current CPU usage to CPU resource limit ratio per pod (%)
`Go Routines`	Average number of Go routines by deployment
`Process Memory`	Average number of resident/virtual memory by deployment
`Process Memory Derivative`	Derivative of the average number of resident/virtual memory by deployment
`Go Memstats`	Average number of `bytes allocated`/`allocation rate`/`stack inuse`/`heap inuse` by deployment
`Go Memstats Derivative`	Derivative of the average number of `bytes allocated`/`allocation rate`/`stack inuse`/`heap inuse` by deployment
`Open File Descriptors`	Average number of currently opened file descriptors by deployment
`Open File Descriptors Derivative`	Derivative of the average number of currently opened file descriptors by deployment
`GC Duration Quantiles`	Average number of garbage collection time by deployment and quantile

Docs: Grafana: gRPC

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

Here is a raintank snapshot to what you will see after navigating to the gRPC dashboard.

Metric Name	Description
`Client Request Rate`	Average gRPC client side request per second by Open Match API methods
`Server Request Rate`	Average gRPC server side request per second by Open Match API methods
`gRPC Error Rate`	Ratio of gRPC calls that returned an non-OK status code by Open Match methods
`Network IO per second`	Total network I/O rate per second
`Bytes Sent per Call: openmatch.{Component}/{MethodName}`	Average bytes sent per call by quantile
`Bytes Received per Call: openmatch.{Component}/{MethodName}`	Average bytes received per call by quantile
`Client RTT: openmatch.{Component}/{MethodName}`	Average roundtrip latency by quantile

Docs: Grafana: Redis

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

Here is a raintank snapshot to what you will see after navigating to the Redis dashboard.

Metric Name	Description
`Uptime`	Redis uptime
`Memory Usage`	Redis memory usage in percentage
`Total DB Items`	Total Redis DB keys in Redis master
`CPU Usage Percentage of Limit`	Current CPU usage to CPU resource limit ratio per pod (%)
`Total Memory Usage`	Current and maximum Redis memory usage by Redis instances
`Hits / Misses per Sec`	Cache hits/misses per second by Redis instances
`Commands Executed / sec`	Executed Redis commands per second by Redis instances (excludes Redis sync calls)
`Network I/O`	Total network I/O per second by Redis instances
`Clients`	Number of currently connected Redis clients by Redis instances

Docs: Install with Helm

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

Prerequisites

Helm package manager, tested on version 3.12.3+
Kubernetes cluster, tested on Kubernetes version 1.27+

Install the Open Match helm chart

Note

If you don’t have Helm installed, read the Using Helm documentation to get started. The Open Match helm chart only installs the core services by default, please override default helm configs if you need to install telemetry support.

Open Match has various deployment options. Depending on your needs you can choose one of the available deployment options below:

Install Open Match using stable Helm repository

To install the chart with the release name open-match using our stable helm repository:

helm repo add open-match https://open-match.dev/chart/stable
helm install open-match --create-namespace --namespace open-match open-match/open-match

Install Open Match using a specific version

Helm install the latest stable version of Open Match v1.8.0 by default. To view the available helm chart versions and install a specific Open Match version:

# View available Open Match helm chart versions
helm search repo --versions open-match/open-match
# Install a specific Open Match helm chart version
helm install open-match --create-namespace --namespace open-match open-match/open-match --version=CHART_VERSION

Note

Open Match needs to be customized to run as a Matchmaker. This custom configuration is provided to the Open Match components via a ConfigMap (om-configmap-override).

Thus, starting the core service pods will remain in ContainerCreating until this config map is available.

Install Open Match with the Default Evaluator

Run the command below to install the default Evaluator and configure Open Match to use it.

# Install the Default Evaluator
# Install ConfigMap `om-configmap-override`, this ConfigMap configures Open Match to talk to the Default Evaluator 
helm install open-match --create-namespace --namespace open-match open-match/open-match \
  --set open-match-customize.enabled=true \
  --set open-match-customize.evaluator.enabled=true \
  --set open-match-override.enabled=true

To install Open Match with the Default Evaluator and another version of Open Match, you can run this command below

# Install the Default Evaluator with specific version of Open Match
# Install ConfigMap `om-configmap-override`, this ConfigMap configures Open Match to talk to the Default Evaluator 
helm install open-match --create-namespace --namespace open-match open-match/open-match --version=CHART_VERSION \
  --set open-match-customize.enabled=true \
  --set open-match-customize.evaluator.enabled=true \
  --set open-match-override.enabled=true

Uninstalling the Chart

To uninstall/delete the open-match deployment:

helm uninstall -n open-match open-match && \ 
kubectl delete namespace open-match

The command removes all the Kubernetes components associated with the chart and deletes the release.

Configuration

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

helm install --name open-match --namespace open-match open-match/open-match \
  --set open-match-telemetry.enabled=true

The above command sets the namespace where Open Match is deployed to open-match, and turns on the telemetry exporters along with installing Open Match core services.

The following tables lists the configurable parameters of the Open Match chart and their default values.

Parameter	Description	Default
`query.portType`	Defines Kubernetes ServiceTypes for the QueryService	`ClusterIP`
`query.replicas`	Defines the number of pod replicas for QueryService’s Kubernetes deployment	`3`
`frontend.portType`	Defines Kubernetes ServiceTypes for the FrontendService	`ClusterIP`
`frontend.replicas`	Defines the number of pod replicas for FrontendService’s Kubernetes deployment	`3`
`backend.portType`	Defines Kubernetes ServiceTypes for the BackendService	`ClusterIP`
`backend.replicas`	Defines the number of pod replicas for BackendService’s Kubernetes deployment	`3`
`image.pullPolicy`	Global `imagePullPolicy` for all Open Match service deployments	`Always`
`image.tag`	Global Docker image tag for all Open Match service deployments	`1.8.0`
`open-match-core.enabled`	Turn on/off the installation of Open Match core services	`true`
`open-match-core.registrationInterval`	Duration of registration window for evaluation/synchronization cycle.	`250ms`
`open-match-core.proposalCollectionInterval`	Length of time after match function has started before it will be canceled.	`20s`
`open-match-core.pendingReleaseTimeout`	Defines the time before a ticket returns to the pool after it was fetched.	`1m`
`open-match-core.assignedDeleteTimeout`	Time after a ticket has been assigned before it is automatically deleted.	`10m`
`open-match-core.backfillLockTimeout`	Defines the time of keeping a lock on a single backfill.	`1m`
`open-match-override.enabled`	Turn on/off the installation of `om-override-configmap`	`false`
`open-match-telemetry.enabled`	Turn on/off the installation of Open Match telemetry services	`false`
`open-match-scale.enabled`	Turn on/off the installation of Open Match scale testing setups	`false`
`global.kubernetes.serviceAccount`	Service account name for the Open Match core services	`open-match-unprivileged-service`
`global.kubernetes.service.portType`	Overrides the ServiceTypes for all Open Match core services	``
`global.gcpProjectId`	Overrides the default gcp project id for use with stackdriver	`replace_with_your_project_id`
`global.tls.enabled`	Turn on/off TLS encryption for all Open Match traffics	`false`
`global.tls.server.mountPath`	The VolumeMount path for TLS server	`/app/secrets/tls/server`
`global.tls.rootca.mountPath`	The VolumeMount path for TLS CA	`/app/secrets/tls/rootca`
`global.logging.rpc.enabled`	Turn on/off RPC payload logging for all Open Match core services	`false`
`global.telemetry.zpages.enabled`	Turn on/off Open Match zPages instrument.	`true`
`global.telemetry.prometheus.enabled`	Turn on/off Open Match Prometheus exporter. Also install Prometheus if `open-match-telemetry.enabled` is set to true	`false`
`global.telemetry.prometheus.endpoint`	Bind the Prometheus exporters to the specified endpoint handler, also configures the `prometheus.io/path` k8s scraping annotations	`/metrics`
`global.telemetry.prometheus.serviceDiscovery`	If Prometheus is enabled and `serviceDiscover: true`, add the Prometheus scraping annotations to each Pod of the Open Match core services	`true`
`global.telemetry.stackdriverMetrics.enabled`	Turn on/off Open Match Stackdriver Metrics exporter.	`false`
`global.telemetry.stackdriverMetrics.prefix`	MetricPrefix overrides the prefix of a Stackdriver metric display names to help you better identifies your metrics	`open_match`
`global.telemetry.grafana.enabled`	Turn on/off Open Match Grafana exporter. Also install Grafana if `open-match-telemetry.enabled` is set to true	`false`
`global.telemetry.reportingPeriod`	Overrides the reporting periods of Open Match telemetry exporters	`1m`
`open-match-telemetry.grafana`	Inherits the values from Grafana helm chart
`open-match-telemetry.prometheus`	Inherits the values from Prometheus helm chart
`redis`	Inherits the values from the Bitnami Redis Helm chart

What’s Next

Follow the Getting Started guide to see Open Match in action.

Docs: Open Match API References

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

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

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: Step 2 - Build your own Director

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

Overview

The Director is a backend component in the Online Game Service that typically performs the following tasks:

Fetch Matches from Open Match for each MatchProfile.
Fetch game allocations from a DGS (Dedicated Game Server) system.
Establish connections from players to game servers and set Assignments based on connections in Open Match.

The tutorial provides a very basic Director scaffold $TUTORIALROOT/director that generates some MatchProfiles and then call FetchMatches for these profiles from Open Match. The director then sets Assignment to a fake connection string to simulate a DGS allocation for every Ticket in a generated match.

Links to API Definitions for this tutorial

pb.Match	pb.MatchProfile	pb.FunctionConfig	backend.AssignTickets	backend.FetchMatches

Make Changes

The Director uses a helper function generateProfiles() in $TUTORIALROOT/director/profile.go to generate MatchProfiles. For this tutorial, we will generate a MatchProfile for each game-mode. The MatchProfile will have a single Pool that has a single filtering criterion searching for the desired game-mode. Director will call FetchMatches for each of the generated Profiles. Below is a sample snippet to achieve this:

func generateProfiles() []*pb.MatchProfile {
  var profiles []*pb.MatchProfile
  modes := []string{"mode.demo", "mode.ctf", "mode.battleroyale"}
  for _, mode := range modes {
    profiles = append(profiles, &pb.MatchProfile{
      Name: "mode_based_profile_" + mode,
      Pools: []*pb.Pool{
        {
          Name: "pool_mode_" + mode,
          TagPresentFilters: []*pb.TagPresentFilter{
            {
              Tag: mode,
            },
          },
        },
      },
    })
  }

  return profiles
}

Please copy the above helper or add your own profile generation logic to $TUTORIALROOT/director/profiles.go. Also, you may tweak the profile polling interval, Assignment logic, etc. in $TUTORIALROOT/director/main.go.

Configuring

The following values need to be changed if your setup is different from the default in the TUTORIALROOT/director/main.go. The default value assumes you have Open Match deployed under open-match namespace and the Game Frontend under mm101-tutorial namespace in the same cluster:

omBackendEndpoint - Open Match Backend endpoint

functionHostName - Kubernetes Internal Hostname of your Match Function

functionPort - Port Number that you host your Match Function service on

Build and Push

Now that you have customized the Director, please run the below commands from $TUTORIALROOT to build a new image and push it to your configured image registry.

# Build the Director image.
docker build -t $REGISTRY/mm101-tutorial-director director/

# Push the Director image to the configured Registry.
docker push $REGISTRY/mm101-tutorial-director

What’s Next

Let’s proceed to build the Match Function.

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: Match Function

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

Overview

The Match Function is the component that implements the core matchmaking logic. A Match Function receives a MatchProfile as input should return matches for this MatchProfile.

Details

A Match Function is a GRPC or HTTP service that implements the Match Function definition prescribed by Open Match.

Definition

rpc Run(RunRequest) returns (stream RunResponse) {
  option (google.api.http) = {
    post: "/v1/matchfunction:run"
    body: "*"
  };
}

message RunRequest {
  MatchProfile profile = 1;
}

message RunResponse {
  Match proposal = 1;
}

This method is triggered at runtime whenever a FetchMatches call is received by Open Match Backend for a MatchProfile. At a high level, here is what a Match Function typically should do:

Query Tickets

The MatchProfile that the Match Function receives has a set of Pools specified. Typically, the Match Function will call into Open Match to fetch all the Tickets belonging to each of the pools in the Match function. This can be done using the following API exposed by the Open Match QueryService:

rpc QueryTickets(QueryTicketsRequest) returns (stream QueryTicketsResponse) {
  option (google.api.http) = {
    post: "/v1/queryservice/tickets:query"
    body: "*"
  };
}

Given that this functionality will be most commonly required for Match Functions, Open Match provides a golang library (“open-match.dev/open-match/pkg/matchfunction”) to abstract this logic:

func QueryPools(ctx context.Context, mml pb.QueryServiceClient, pools []*pb.Pool) (map[string][]*pb.Ticket, error)

Generate Match Proposals

Now that we have the Tickets belonging to each pool, the Match Function can group them into matches as per the game’s requirements. Note that each Ticket with all its SearchFields and extensions are available to the Match Function. Once the proposals are generated, they are streamed back to Open Match.

Docs: Step 3 - Build your own Match Function

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

Overview

The MatchFunction is a service that implements the core matchmaking logic. A MatchFunction accepts a MatchProfile and should return Match proposals for this MatchProfile. The MatchFunction typically performs the following tasks:

Queries Tickets for each Pool in the MatchProfile (Open Match provides a helper library for this).
Uses these Tickets to generate Proposals (The MatchProfile can also describe the shape of a match using the Roster Field).
Streams the Proposals back to Open Match.

The tutorial provides a very basic MatchFunction scaffold $TUTORIALROOT/matchfunction that simply groups the filtered tickets into Proposals of a configurable number of players.

Links to API Definitions for this tutorial

pb.Pool	pb.MatchProfile	pb.Match	matchfunction.Run

Make Changes

The MatchFunction scaffolding creates a gRPC service that implements the interface prescribed by Open Match for MatchFunctions. It integrates with Open Match library to Query the Tickets for the given MatchProfile and has logic to stream proposals back to Open Match. It uses a helper function makeMatches() that accepts a map of Pool names to Tickets in that Pool and returns Match proposals. For this tutorial, the MatchProfile passed into the MatchFunction has a single Pool that filters Tickets for a game-mode. Thus the makeMatches() receives a Pool with Tickets belonging to a game-mode and groups these Tickets into matches till it runs out of Tickets. Below is a sample snippet to achieve this:

func makeMatches(p *pb.MatchProfile, poolTickets map[string][]*pb.Ticket) ([]*pb.Match, error) {
  var matches []*pb.Match
  count := 0
  for {
    insufficientTickets := false
    matchTickets := []*pb.Ticket{}
    for pool, tickets := range poolTickets {
      if len(tickets) < ticketsPerPoolPerMatch {
        // This pool is completely drained out. Stop creating matches.
        insufficientTickets = true
        break
      }

      // Remove the Tickets from this pool and add to the match proposal.
      matchTickets = append(matchTickets, tickets[0:ticketsPerPoolPerMatch]...)
      poolTickets[pool] = tickets[ticketsPerPoolPerMatch:]
    }

    if insufficientTickets {
      break
    }

    matches = append(matches, &pb.Match{
      MatchId:       fmt.Sprintf("profile-%v-time-%v-%v", p.GetName(), time.Now().Format("2006-01-02T15:04:05.00"), count),
      MatchProfile:  p.GetName(),
      MatchFunction: matchName,
      Tickets:       matchTickets,
    })

    count++
  }

  return matches, nil
}

Please copy the above helper or add your own matchmaking logic to $TUTORIALROOT/matchfunction/mmf/matchfunction.go. Also, you may change the number of Tickets per match to observe its impact on the matchmaker run.

Configuring

queryServiceAddress - Open Match QueryService endpoint

serverPort - Port Number that you host your Match Function service on, needs to be consistent with functionPort in the director. The current value uses the port specified in deployment YAML (covered later in the Deploy and Run step)

Build and Push

Now that you have customized the MatchFunction, please run the below commands from $TUTORIALROOT to build a new image and push it to your configured image registry.

# Build the MatchFunction image.
docker build -t $REGISTRY/mm101-tutorial-matchfunction matchfunction/

# Push the MatchFunction image to the configured Registry.
docker push $REGISTRY/mm101-tutorial-matchfunction

Let’s proceed to the next step to Deploy and Run the Matchmaker.

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.

Docs: Step 4 - Deploy and Run

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

This step assumes that you have completed the Tutorial prerequisites and all prior steps and have the Game Frontend, Director and Match Function built and pushed to your configured image registry. If you have done all of this, let’s proceed.

Deploy the Match Function, Game Frontend, Director

The next step is to deploy the Match Function, the Game Frontend and the Director to the same cluster as Open Match deployment but to a different namespace. The $TUTORIALROOT/matchmaker.yaml deploys these components to a mm101-tutorial namespace. Run the below command in the $TUTORIALROOT path to apply this YAML:

For GKE users, run:

sed "s|REGISTRY_PLACEHOLDER|$REGISTRY|g" matchmaker.yaml | kubectl apply -f -

For Minikube users, run:

# Instructs Minikube to use local images
# https://kubernetes.io/docs/setup/learning-environment/minikube/#use-local-images-by-re-using-the-docker-daemon
eval $(minikube docker-env)
sed "s|REGISTRY_PLACEHOLDER|$REGISTRY|g" matchmaker.yaml | sed "s|Always|Never|g" | kubectl apply -f -

Matchmaking ever after

All the components authored in this tutorial simply log their progress. Thus to see the progress, please check the logs for the below pods. Below are the commands and the expected output:

Game Frontend

kubectl logs -n mm101-tutorial pod/mm101-tutorial-frontend

# Sample Expected Output
2019/11/07 17:44:45 Ticket created successfully, id: bn25g39sm0mrm8pkpssg
2019/11/07 17:44:45 Ticket created successfully, id: bn25g39sm0mrm8pkpst0
2019/11/07 17:44:45 Ticket bn25g0psm0mrm8pkpr70 got assignment connection:"3.195.34.194:2222"
2019/11/07 17:44:45 Ticket bn25g0psm0mrm8pkpr7g got assignment connection:"207.123.239.153:2222"

Director

kubectl logs -n mm101-tutorial pod/mm101-tutorial-director

# Output
2019/11/07 17:45:15 Generated 16 matches for profile mode_based_profile
2019/11/07 17:45:15 Assigned server 217.7.41.62:2222 to match profile-mode_based_profile-time-2019-11-07T17:45:10.53-0
2019/11/07 17:45:15 Assigned server 210.183.191.233:2222 to match profile-mode_based_profile-time-2019-11-07T17:45:10.53-1

Match Function

kubectl logs -n mm101-tutorial pod/mm101-tutorial-matchfunction

# Output
2019/11/07 17:45:45 Generating proposals for function mode_based_profile
2019/11/07 17:45:45 Streaming 5 proposals to Open Match

Cleanup

To remove the tutorial and its custom components, here is the command you need to run:

kubectl delete namespace mm101-tutorial

This will delete all the components deployed in this tutorial. Open Match core in open-match namespace can then be reused for other exercises but you will need to re-customize it.

What’s Next

Now that you have created your own basic Matchmaker, lets run the next tutorial to add new matchmaking criteria to this Matchmaker.

Docs: Documentation Editing and Contribution

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

Editing the documentation is pretty simple if you are familiar with Markdown.

Simple Edits

If you want to make simple edits to a page (changes that do not require formatting or images) and you’re not an approver.

Click the Edit this page link at the top right of the documentation page you want to edit.
You’ll be redirected to an editor, make your changes there and click Propose file change.
Your changes will be reviewed, make any adjustments and submit.

Advanced Edits

If you’re adding a new page, changing the landing page, or making substantial changes.

Check out the repository.
Create a branch via git checkout -b mychange upstream/master.
Run make run-site to start the webserver. It’ll be hosted on http://localhost:8080/.
Open your favorite editor and navigate to the documentation which is stored at $(REPOSITORY_ROOT)/site/content/en/.
Make your changes and run git commit -m and git push
Follow the GitHub Pull Request workflow to submit your changes.

Platform

This site and documentation are built with a combination of Hugo, static site generator, with the Docsy theme for open source documentation.

Open Match – Open Match Documentation

Docs: Game Frontend

Overview

Open Match Interactions

Creating a Ticket

Ticket

SearchFields

Fetching the Assignment

Note

Deleting a Ticket

Docs: Install with YAML

Prerequisites

Install Core Open Match

Note

Note

Install the Default Evaluator

Delete Open Match

What’s Next

Docs: Step 1 - Build your own Game Frontend

Overview

Note

Links to API Definitions for this tutorial

Make Changes

Configuring

Build and Push

What’s Next

Docs: Director

Overview

Open Match Interactions

Fetching Matches

FunctionConfig

MatchProfile

Assigning Tickets

Assignment

Docs: Grafana: Go Processes

Docs: Grafana: gRPC

Docs: Grafana: Redis

Docs: Install with Helm

Prerequisites

Install the Open Match helm chart

Note

Install Open Match using stable Helm repository

Install Open Match using a specific version

Note

Install Open Match with the Default Evaluator

Uninstalling the Chart

Configuration

What’s Next

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