Version: en

Command-Line Interface

warning

This documentation is now deprecated. If you are using Matchmaker Self Serve though UDash, please use the documentation here.

CLI download link#

The download link has moved to the downloads page

Overview#

The Unity Cloud command-line interface (CLI), mmbeta, is a tool for managing and operating Multiplay matchmaking.

This guide assumes familiarity with matchmaking logic configuration, and instead focuses on how to run and manage the configuration files through the CLI. For information on configuring matchmaking logic, see Matchmaking How-To and Matchmaking-Logic Tutorial.

Internally, the CLI uses the REST endpoints that are provided by the matchmaking service. Developers can also directly use the REST interface. For information on calling the REST endpoints directly, see Matchmaker beta API Documentation.

Initializing configuration#

All of the endpoints that matchmaking commands hit require auth to access. This authorization happens against a specific project ID. Accordingly, to get authenticated, you must set a project ID.

The quickest way to get local configuration running is to get your project ID and then run the following command:

$ mmbeta config set -n project -v <my project uuid>

Config command#

Use the config command to get and set values from the local config file. A config file is created when the config command is first used. The main commands that are supported by the config command are get and set.

You can invoke the config command by using the following code:

$ mmbeta config

To get a description of what subcommands are available and what arguments are supported, pass --help.

Config get command#

Use the get command to view the values of the current local config file.

For example, to view a setting by name, run the following command:

$ mmbeta config get --name project

This returns the project ID, or an empty string if one has not yet been configured.

To get a detailed list of supported arguments and supported get target names, run the help command:

$ mmbeta config get --help

Config set command#

Use the set command to set values for the local configuration file.

For example, run the following command to set the project setting to the value \<my project uuid\>.

$ mmbeta config set -n project -v <my project uuid>

Authorization#

The CLI performs authorization checks and logins on-demand by using a single sign-on flow. After you set the project ID, the first command that is run that requires authentication results in being redirected to the Unity website with a prompt to log in.

Matchmaking commands#

Use matchmaking commands to use create, ready, update, and delete functionality for match config and functions.

Matchmaking config command#

Use the matchmaking config command to manage the matchmaking configuration.

Matchmaking config upload command#

Use the matchmaking config upload command to upload a local file to the configuration store. You invoke this command by using the following code:

$ mmbeta matchmaking config upload --name "dm config prod" --path /localpath/matchConfig.json
Created config with id: 'dm config prod'

The name can contain most characters that you would expect to see in a file system file name.

If a config with the specified name already exists, it is updated.
If the specified config does not exist, it is created.

If there are any errors when validating the configuration, they display as an array of validation failure messages with the following structure:

$ mmbeta matchmaking config upload --name "dm config prod" --path /localpath/matchConfig.json
Error: modifying config: Config Validation failed:
[
  {
    "resultCode": "NullMatchGeneratorName",
    "message": "'Matchmaking.Name' a config name must be specified.",
    "detailLink": null
  }
]

note

The mmbeta matchmaking config create --path /localpath/matchConfig.json command has been deprecated from the CLI. Instead, it is recommended that you use the upload command to specify a name instead of a random guide being created for you. For compatibility purposes, the API still supports the previous version of the CLI.

Matchmaking config modify command#

Use the matchmaking config modify command to upload a local file to the configuration store. This process replaces the previous version of the file. Note that the config ID is a required parameter.

$ mmbeta matchmaking config modify --id <config guid>--path /localpath/matchConfig.json

Any validation errors are returned as JSON and use the same structure as the create command.

Matchmaking config delete command#

Use the matchmaking config delete command to remove an existing config. Note that you must specify the id argument.

$ mmbeta matchmaking config delete --id <config uuid>

Matchmaking config get command#

Use the matchmaking config get command to return the JSON body of the config that is associated with the specified ID:

$ mmbeta matchmaking config get --id <config uuid>

Matchmaking config list command#

Use the matchmaking config list command to get all configurations and then return them as JSON text. By default, results are sorted by the config name in ascending order.

$ mmbeta matchmaking config list

The results use the format of a JSON dictionary, in which each key is a config name, and the value is the JSON object that represents a full valid config file:

{
    "<config 1 uuid>": {
        /*  config json */
    },
    "<config 2 uuid>": {
        /*  config json */
    },
    . . .
}

Matchmaking function commands#

Use the matchmaking function command to create and manage the lifecycle and debugging of match functions.

You can access the match function section of the Unity Cloud CLI by issuing the matchmaking function subcommand.

$ mmbeta matchmaking function

note

The matchmaking function commands are documented here, but are only used when managing custom match functions.

Matchmaking function delete command#

Use the matchmaking function delete command to delete an uploaded match function. After a successful deletion, any running function with the provided name is shut down and is removed from the project deployment. In addition, the function archive is removed from cloud storage. This includes the removal of all logs.

$ mmbeta matchmaking function delete testfunc1
deleted

After you delete the match function and archive file, the command responds with the message "deleted".

Matchmaking function get command#

Use the matchmaking function get command to get the current status of a deployed match function. The output is a JSON object that contains the following properties:

Property	Type	Value
name	String	Name of the match function
md5Hash	String	Base64-encoded MD5 hash of the uploaded match function archive
created	String	Date and time the match function archive was created (uploaded) in RFC 3339 format
updated	String	Date and time the match function was last uploaded (replaced) in RFC 3339 format
status	Object	State and status of the match function and any running instances

The status JSON object contains the following properties:

Property	Type	Value
state	String	Current overall state of the function. Can be one of the following states: `Unknown`: Internal error `NotRunning`: Function is deployed but is not currently running `Pending`: Function is deployed and is in the process of starting `Running`: Function is deployed and is running `Failed`: Function attempted to deploy but failed, or was running but failed and cannot restart For states that indicate an error, you can see more details by downloading the logs, if they are available.
instances	Array	The state of each running instance of the function. There are as many items in this array as there are instances of the match function that is running.

Each element of the instances array contains an object with the following properties:

Property	Type	Value
state	String	Current state of the function instance. This is similar to the overall function status state. For each instance, the value is one from the following states: `Unknown`: Internal error `Waiting`: Instance is in the processing of deploying or starting `Running`: Instance is running `Terminated`: Instance is deployed, but was terminated (for example, as a precursor to deploying an updated version, or due to an error that prevents restarting). For states that indicate an error, you can see more details by downloading the logs, if they are available.
name	String	Name of the specific function instance. This name is unique for each instance.

The overall function state is an umbrella designation that might cover specific instances in other states. If there is at least one running instance, the overall function state is running, even if some other instances are in other states. For example, for the running function testfunc1, the output might look similar to the following code snippet:

$ mmbeta matchmaking function get testfunc1
{
    "name": "testfunc1",
    "md5Hash": "DG0UUW8fX/fwdaXW4MqedA==",
    "created": "2019-10-15T20:42:50.574+00:00",
    "updated": "2019-10-15T20:42:50.574+00:00",
    "status": {
        "state": "Running",
        "instances": [
            {
                "state": "Running",
                "name": "testfunc1-987fb8f97-lcbgp"
            },
            {
                "state": "Waiting",
                "name": "testfunc1-830ec7b0a-krvxs"
            }
        ]
    }
}

Note that the second instance is Waiting, but because there is at least one running instance, the overall function state is Running. The order of precedence is Running, Pending, Failed, NotRunning, Unknown. The most prominent state that any instance has reached sets the state for the entire function. For example, the only way the overall function status can be Unknown is if every instance is also Unknown.

Matchmaking function list command#

Use the matchmaking function list command to get the status of all deployed match functions. The output is a JSON array of function statuses called "functions". Each object matches the structure that is used in the get command, which is outlined in the Matchmaking function get command section. For example, if there are two running functions, testfunc1 and testfunc2, the output should look similar to the following code snippet:

$ mmbeta matchmaking function list
{
    "functions": [
        {
            "name": "testfunc1",
            "md5Hash": "DG0UUW8fX/fwdaXW4MqedA==",
            "created": "2019-10-15T20:42:50.574+00:00",
            "updated": "2019-10-15T20:42:50.574+00:00",
            "status": {
                "state": "Running",
                "instances": [
                    {
                        "state": "Running",
                        "name": "testfunc1-987fb8f97-lcbgp"
                    },
                    {
                        "state": "Waiting",
                        "name": "testfunc1-830ec7b0a-krvxs"
                    }
                ]
            }
        },
        {
            "name": "testfunc2",
            "md5Hash": "J4/3RR9OhwLz7PEOBNk5XQ==",
            "created": "2019-10-15T20:43:01.193+00:00",
            "updated": "2019-10-15T20:43:01.193+00:00",
            "status": {
                "state": "Running",
                "instances": [
                    {
                        "state": "Running",
                        "name": "testfunc2-576b47b6f9-q6dff"
                    }
                ]
            }
        }
    ]
}

Matchmaking function upload command#

Use the matchmaking function upload command to create or replace a match function by uploading a .zip archive that contains the compiled match function and any other assemblies that are required to run that function.

If the function is new, it is deployed and started in the target project ID.
If the function is intended to replace an existing function, the currently deployed function is shut down and is replaced with the uploaded function binary.

note

After a function has been replaced, you can no longer access old logs. Before you upload the replacement function, ensure that you download any previous logs that you might need for future reference.

This user guide does not detail the process of creating and building match functions, and the instructions from this point assume that the function has already been built and the function assembly (along with all assemblies required to run the function) are located in a single folder hierarchy. For more details on writing and building match functions, see the document referenced in the overview.

Creating the match function archive#

There is currently no automatic packaging tool for preparing match functions for upload. Developers must create a .zip archive with all of the necessary data that is required to run the match function.

After the match function is built, locate the output folder where the match function and all of the other assemblies that it relies on are placed (for example, in the bin/Debug/netcoreapp3.0 folder under the function directory). You can include the entire output folder in the .zip archive with any number of sub-folders, but as a minimum requirement, all of the assemblies that are required to run the match function must be present in the same directory as the match function. This means that if the match function is nested several directories deep in the archive file, it can still be found and run if all of its dependencies are located in the same directory.

The .zip archive should be no more than 50MiB in size. If the resulting archive is more than 50MiB, ensure that any unnecessary files, such as PDB or other debugging files, are removed. In general, only the DLL files are necessary, and any other files are ignored.

Uploading the match function#

After you create the .zip archive that contains the match function, use the CLI to upload that match function and give it a name that will be used to identify it later. This name can be independent of the name given to the specific IMatchFunction implementation. In addition, the name must be a RFC 1123-compliant string that consists of lowercase alphanumeric characters, '-' or '.', and it must start and end with an alphanumeric character. The regex that is used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*'.

For example, consider the IMatchFunction implementation, "BestMatchFunction." You create a .zip archive of the build folder called BestMatchFunction.zip, and give it a name that will pass validation (for example, "bestfunction"). You then upload and deploy the function from the CLI by using the following code:

$ mmbeta matchmaking function upload bestfunction BestMatchFunction.zip
{
    "uri": "https://example.com/path/to/function/archive"
}

If successful, the response is a JSON object that contains a single property:

Property	Type	Value
uri	String	URI to access the uploaded archive file from cloud storage

After the function is uploaded, it is automatically deployed to the project’s running matchmaker. Use the matchmaking function get command or the matchmaking function list command to get the status of the deployed function.

By default, deploying the match function runs the first IMatchFunction implementation that it finds in the archive. If there are multiple implementations in the archive, the first one that is found is the one that runs. The search order is non-deterministic. If more than one IMatchFunction implementation exists inside of the archive, use the optional --implementation flag to specify the named instance to use. In this scenario, "BestMatchFunction" is the name of the class that implements IMatchFunction:

$ mmbeta matchmaking function upload bestfunction ManyFunctions.zip -i BestMatchFunction
{
    "uri": "https://example.com/path/to/function/archive"
}

Matchmaking function logs command#

Use the matchmaking function logs command to retrieve a user-defined portion of the logs that are generated by the given match function. By default, the last 30 minutes of logs are retrieved from each running instance of the match function. This time range can be adjusted on the command line.

For example, for the match function "bestfunction", you can retrieve the last 30 minutes of logs by using the following command:

$ mmbeta matchmaking logs --name bestfunction
{
    "logs": {
        "bestfunction-d6c7bd777-vbjff": "...",
        "bestfunction-b7420f454-veupd": "..."
    }
}

The response is a JSON object called "logs" that contains the raw logs from each instance of the running function for the given (or default) time range. The top-level object has the following format:

Property	Type	Value
logs	Object	List of properties where each property is the name of a match function instance and the logs for that instance.

The properties inside of the logs object have the following format:

Property	Type	Value
instance-name	String	Name of the specific instance of the match function with a `string` of log values.

The log entries can contain serialized JSON objects, but the format is ultimately developer-defined. The string can also contain formatting characters, such as tabs and new lines.

To specify a different time range, use the --time parameter to specify how many seconds of logs to include. Time is always counted back from the current time, so --time 60 would get the logs from one minute ago until now. For example, to get the logs from the past hour, use the following command:

$ mmbeta matchmaking logs --name bestfunction --time 3600

Logs lifecycle#

Match function logs are ephemeral. Deleting, replacing, or restarting a match function also removes the logs that are associated with that function.

Additionally, the space available for match function logs is limited. If the matchmaking logs command is returning less history than requested there are either no logs extending to that time, or the log buffer is full. In the latter case, you will receive all logs from the current time extending as far back as the log buffer allows.

To extend the time range of available logs, consider reducing the amount of data logged in your match function.