Open Match – How to build a basic Matchmaker

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