Open Match – Matchmaking using Open Match

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