Get started with matchmaking customization

Last updated on May 3, 2024
info

Extend is in Open Beta for AGS Premium Clients! This means that the Extend add-on is available for you to try in your development environment. You can submit your feedback via our Extend Open Beta feedback form.

Overview​

AccelByte Gaming Services (AGS) has the capability to provide custom logic for matchmaking. In this guide, we will go through the workflow of creating and using a simple custom matchmaker for AGS.

If you wish to use an advanced matchmaker, or learn how to customize one, use the Advanced Sample App in the appropriate section below.

Prerequisites​

  1. Windows 11 WSL2 or Linux Ubuntu 22.04 with the following tools installed:
    • Bash
    • Make
    • Docker v23.x
    • Python 3.10
    • ngrok

  1. Access to AccelByte Gaming Services environment.

    • Base URL: <your environment's domain URL>
      • Example for AGS Starter customer: https://spaceshooter.prod.gamingservices.accelbyte.io
      • Example for AGS Premium customer: https://dev.customer.accelbyte.io
    • Create a Game Namespace if you don't have one yet. Keep the Namespace ID.
    • Create an OAuth Client with confidential client type. Keep the Client ID and Client Secret.

  2. You have set up a network proxy for local testing. We recommend using ngrok.

    • If you're using ngrok, ensure that you follow the installation guide and set up the `ngrok authtoken``.
    • ngrok install guide

  3. You have downloaded and set up the extend-helper-cli. Download here.

    • To use this tool, refer to its documentation on GitHub.

  4. Access to the AGS Admin Portal.

Download the Simple or Advanced Sample App​

First, we will need to clone a Sample App. Click here for the Simple MatchMaker Sample App repository.

git clone https://github.com/AccelByte/matchmaking-function-grpc-plugin-server-python.git

If you'd like to modify the Simple Sample App, you can follow along in the Advanced Sample App guide to learn how, or you can download the Advanced Sample App.

git clone https://github.com/AccelByte/example-advanced-sample-app-grpc-golang.git
note

There is no advanced sample app for Python and C# yet. We're working on it!

Follow the Setup, Building, and Running sections of the repository README. Alternatively, you can use the following python command from the sample app root directory to run the server:

make build
PYTHONPATH=src python -m src.app
note

Ensure that the server is running locally before moving onto the next section.

Start ngrok and expose the port specified within the Sample App. The following command assumes you have not changed the port in the Simple or Advanced Sample App:

ngrok tcp localhost:6565

Example rules and Session Template for Simple MatchMaker​

The following can be used when creating a Ruleset and Session Template for the MatchPool that the Simple MatchMaker will be set in.

More detailed instructions on this process can be found in Configuring match rulesets and Configuring session templates with the Admin Portal.

Ruleset​

{
    "alliance": {
        "min_number": 2,
        "max_number": 2,
        "player_min_number": 1,
        "player_max_number": 1
    },
    "matching_rule": []
}

Session Template​

Session Type: None
Requested Regions: <choose one, or any>
Min Players: 2
Max Players: 2
Invite Timeout: 60
Inactive Timeout: 60
Joinability: Open

Test your local gRPC plugin server​

Next, we will test the Sample App locally before creating a service. To do so, we'll use ngrok to expose our port locally and use that address for the Match Function URL. Lastly, we'll use the mmtool-cli to mimic a client (or clients) creating matchmaking requests.

Register a local custom function​

Copy the forwarding address from ngrok. An example of this will look like:

<number>.tcp.ngrok.io:<port>

Go to your AGS Admin Portal and use the namespace you wish to use when creating your custom function. On the left pane, click on Game Management, then New Matchmaking, and then Custom Function. Next, click the Register Function button and select the Locally hosted for testing purpose. Use the ngrok forwarding address for the URL. Once both fields are filled in, click Create.

registering local custom matchmaking configuration

Next, set the match function to the match pool configuration you want to use. To do this, click on Game Management, then New Matchmaking, and then Match Configurations. Click the Match Pools tab and either create a match pool or edit an existing one. Scroll near the bottom and choose your Custom Function from the drop-down menu.

set custom function

Test using gRPCurl​

Testing with gRPCurl is optional, but it will ensure that your proxy is working correctly.

Download and install grpcurl and run the command below.

The following will printout the list of gRPC services served by the forwarded local sample app. Use your ngrok TCP forwarding address below.

grpcurl -plaintext <number>.tcp.ngrok.io:<port> list

Test using MMTool CLI (local)​

mmtool-cli repo mmtool-cli releases

The mmtool-cli simulates game client behaviors and will be used to fully test your Sample App. If you have not done so, please follow the Setup portion of the README before continuing and ensure you're using the latest release for the platform of your choice. After your setup is complete, if you are using the the Simple Sample App (and have not changed any configurations), run the following command (replacing namespace and matchpool with your targeted namespace and matchpool, respectively).

 mmtool-cli tickets create solo -n <namespace> -m <matchpool> -u 2

Create an Extend App​

Go to the Admin Portal and use the namespace in which you wish to create your gRPC plugin. On the left pane, hover over Extend and click Overridable Features. Click Create New to create a new Extend App.

click create new overridable features

Type in the App Name and the Description. Then, click Create.

create new app

You will be redirected back to Overridable Features app list page with the newly created app with a status of Provisioning in Progress.

newly created app listed

Wait until the status says UNDEPLOYED and click the app name in the list to see the details page.

newly created app details

note

Please take note of the Namespace, App Name, and the App Repository URI since we're going to use it in the next section.

Package and push the Extend App image​

The extend-helper-cli is required to get the temporary docker credentials for uploading your docker image.

Run the following extend-helper-cli command. Replace the namespace and app name with what you used to create your Extend app.

extend-helper-cli dockerlogin --namespace <game namespace> --app <app name> --login

For your convenience, the above extend-helper-cli command can also be copied from Repository Authentication Command under the corresponding app detail page.

Image showing repository authentication command under admin portal

info

Create an OAuth Client with confidential client type with the following permission. Keep the Client ID and Client Secret.

  • For AGS Premium customers:
    • ADMIN:NAMESPACE:{namespace}:EXTEND:REPOCREDENTIALS [READ]
  • For AGS Starter customers:
    • Extend > Extend app image repository access (Read)

If you use extend-helper-cli v0.0.3 or lower, create a user if you don't have any with the following permission. Keep the Username and Password.

Go to the extend-helper-cli README for more details.

To directly build and push the sample app Docker image, you can use the provided make script. Inside the sample app directory, run the following:

make imagex_push IMAGE_TAG=v0.0.1 REPO_URL=<app-repo-url>
info

Note that the REPO_URL can be copied from the app detail page App Repository URI.

Deploy the Extend App​

Return to the Admin Portal and, inside the Extend App Details page, click Deploy Latest Image. Wait until the deployment is successful.

app details - deploy latest image

Important

If your Extend Override app is based on sample apps before release v2024.02.13: Make sure to set PLUGIN_GRPC_SERVER_AUTH_ENABLED environment variable to true. Otherwise, the access token validation in the Extend app is disabled and your Extend app may be accessed without a valid access token.

Since release v2024.02.13: PLUGIN_GRPC_SERVER_AUTH_ENABLED in Extend Override sample apps is set to true by default. The access token validation can only be disabled when PLUGIN_GRPC_SERVER_AUTH_ENABLED is explicitly set to false. To align with this, all new Extend apps created through the Admin Portal will not have PLUGIN_GRPC_SERVER_AUTH_ENABLED enviroment variable set by default. Previously, PLUGIN_GRPC_SERVER_AUTH_ENABLED=false is added on all new Extend apps created through admin portal.

Test the Extend App​

Update the custom function with the Extend App​

Go back to the Admin Portal and update the Custom Function URL previously used by selecting the AccelByte Hosted option. Choose the Extend App name you created and click Save.

AccelByte hosted custom configuration

Test using MMTool CLI (Extend)​

Reuse the command from the previous steps to test the Extend App.

 mmtool-cli tickets create solo -n <namespace> -m <matchpool> -u 2

A note on Extend App behavior​

important

In the deployment setup, there's a timeout mechanism for the gRPC Extend app managed by Envoy. This timeout occurs when there's no incoming/outgoing data or request, allowing the system to free up resources. By default, the timeout duration is 300s for streamIdleTimeout and 30s for routeTimeout.

Last updated on

On this page