Unity - Demo

Using the Catena Unity SDK

As a companion to the Unity SDK, there is a Catena Networking Demo that shows an example of how to integrate Catena into a Unity project. The base of the project is Unity's Galactic Kittens demo, with changes to add Authentication & Login, Matchmaking, and dedicated server support through Catena, along with examples for other Catena services. The following sections are guides on how to use the demo, in order to demonstrate what integrating the SDK into a game project would look like.

Prerequisites

In order to use the Catena Unity SDK, you must be running Catena, either locally or deployed elsewhere.

As the first step to working with most other services in Catena, the player must first log in. In the demo, the other online Catena functions are hidden until the player has logged in.

First, start by opening the Catena Galactic Kittens Demo project. Once open, if you navigate to the scene Assets/Scenes/Menu.unity you will see the gameobjects CatenaEntrypoint and CatenaPlayer, which have their respective components added - the key components required for logging in to Catena.

On the MenuController gameobject, you will see the Menu Manager component, which has a few changes made for logging in/out, as well as matchmaking and entitlements (with entitlements being behind a feature flag).

In order to test the authentication and login flow, complete the following steps:

Ensure that Catena is up and running. Instructions for doing so can be found here.
Navigate to the scene Assets/Scenes/Bootstrap.unity - going forward, whenever you want to run the game in the editor, start from this scene.
Find the CatenaEntrypoint, and in the CatenaEntrypoint component, configure the Catena Endpoint URL to point to your running instance of Catena. If you don't yet have a running instance of Catena, refer to the How to Run Catena documentation. (If you are running Catena locally, the default Endpoint Url should be the same.)
Click play, then on the menu screen, type in a username - it can be anything in the format of test#, replacing the # with any number.

Why the test# username?

The testXX pattern is a specially recognized development username. By passing in test01 to the CompleteLogin function, we perform a low-friction UNSAFE login for development environments. You may update this username to be any variation of testXX to login to different accounts.

At this point, you should be logging in! You will see the text in the bottom left update - first to display your session ID after completing the authentication, and then displaying your entered username and your account ID after logging in. You should also see the menu controls change to show the 'online' controls.

To see the steps of how to integrate authentication in to your project, check out the Unity Quickstart Guide and the Unity Authentication Guide.

Matchmaking

Once the player is logged in, they are able to use the matchmaking system to enter a game through CatenaPlayer. There are two options for how to handle matchmaking - either peer to peer, or a dedicated server. The Peer to Peer Guide can be found here, and the Dedicated Server guide can be found here.

Peer to Peer

Before being able to start matchmaking, you must ensure that the backend is configured to have the queues and hooks that you require. This config file can be found in the appsettings.Development.json file in catena-tools-core. For peer to peer matchmaking in the demo, ensure that you have a Matchmaking Queue with the name team_of_2 with teams set to 1 and player per team set to 2, as well as the custom hook of SimpleP2PMatchmakingHooks - it should look something like this:

{
  "Catena": {
    ...
    "Matchmaker": {
      "MatchmakingQueues": {
        "team_of_2": {
          "QueueName": "team_of_2",
          "Teams": 1,
          "PlayersPerTeam": 2,
          "TicketExpirationSeconds": 180,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
      },
      "StatusExpirationMinutes": 15
    }
    ...
  }
}

In the Galactic Kittens sample, the default mode for matches is peer-to-peer, with one of the clients hosting the game, and another client joining. In order to matchmake into a peer-to-peer session, open two instances of the game (creating a build and opening multiple instances of the game is an easy way to accomplish this). Once logged in, the player can click the Find button, which will start the matchmaking process - and once both players are matchmaking, they should find eachother and load into the character select screen.

Dedicated Server

In order to have a dedicated server for the game, you must build one for the demo - to do so, in the build settings, change the platform to Dedicated Server and then build.

You will also need to make sure the config is set up in such a way to enable matchmaking into a dedicated server. This involves two parts of the config: The matchmaking queues, and the match broker. To set up the queues, add a queue similar to the one above, but omitting the custom hook:

{
  "Catena": {
    ...
    "Matchmaker": {
      "MatchmakingQueues": {
        "team_of_2": {
          "QueueName": "team_of_2",
          "Teams": 1,
          "PlayersPerTeam": 2,
          "TicketExpirationSeconds": 180
        },
      },
      "StatusExpirationMinutes": 15
    }
    ...
  }
}

You will also need to set up a match broker. For our case, we will not need an allocator, as the server itself will poll for available matches - so the config should only need the following:

{
  "Catena": {
    ...
    "MatchBroker": {
      "FastSchedule": 1,
      "ServerMaxLifetimeMinutes": 10,
      "MatchPickupTimeSeconds": 90,
      "MatchReadyTimeSeconds": 30,
      "MatchMaxRunTimeMinutes": 120,
      "ScheduleFrequencySeconds": 30,
      "DelayAllocationSeconds": 30,
      "Allocators": []
    }
    ...
  }
}

For more information on the different methods for setting up a match broker, see the Matchmaking Into Dedicated Game Servers guide here.

In the Catena Galactic Kittens demo, there are a few changes made to allow dedicated server support. When running the server build, it will register itself with Catena, making it open to have players connect for matches. To see where this is done, you may navigate to the scene Assets/Scenes/CharacterSelection.unity, where you will see the added gameobject/component for CatenaSingleMatchGameServer.

For ending the match, there is a prefab located at Assets//Prefabs//EndGameManager.prefab, which handles the end of the match in both the Victory and Defeat scenes. For the dedicated server, it waits until the clients disconnect before shutting down, seen in EndGameManager.cs. In this example, the function is called from the Unity Network Manager's OnClientDisconnectCallback event, and m_connectedClients containing the list of connected client Id's:

To see the dedicated server matchmaking in action, perform the steps in the following order:

Ensure Catena is running, and is properly configured with the matchmaking and match broker settings.
Run the executable for the Galactic Kittens server build.
Open 2 instances of the game Galactic Kittens, and log in with both to different test accounts (test1 and test2 will suffice)
Click find match on both game instances, and watch as they are placed into a match hosted by the server!

Gamelift Allocated Server

In addition to using your dedicated server with Catena, you can use Gamelift to allocate your server while using Catena to perform the matchmaking. In the demo, we have an example set up so that you can run your dedicated server locally, but have it register with a gamelift fleet to be allocated when Catena requests a game session.

To set up Gamelift so that Catena can use it to allocate servers, More information can be found here. For our example, ensure that your Gamelift fleet is an Anywhere fleet, with a custom location set. With your Gamelift fleet configured, set the Catena config so that it will use Gamelift as your match broker:

{
  "Catena": {
    ...
    "MatchBroker": {
      "FastSchedule": 1,
      "ServerMaxLifetimeMinutes": 10,
      "MatchPickupTimeSeconds": 90,
      "MatchReadyTimeSeconds": 30,
      "MatchMaxRunTimeMinutes": 120,
      "ScheduleFrequencySeconds": 30,
      "DelayAllocationSeconds": 30,
      "Allocators": [
        {
          "Allocator": "CatenaGameLiftAllocator",
          "AllocatorDescription": "GameLift allocator",
          "Configuration": {
            "Profile": "my-gamelift-profile",
            "Region": "(your region, such as us-east-1)",
            "ReadyDeadlineSeconds": 30,
            "FleetArn": "(Copy Fleet ARN from your own fleet)",
            "FleetLocation": "(Copy fleet location from your own fleet)",
            "AllowFleetGrowth": false,
            "MaxFleetSize": 1,
            "ProxyMatchesToGameLift": true
          }
        }
      ]
    }
    ...
  }
}

Once both Catena and the Gamelift fleet are set up, Head back to the Catena Networking Demo and switch to the branch named gamelift-test-integration. Navigate to the scene Assets/Scenes/CharacterSelection.unity - you will notice that CatenaSingleMatchGameServer is disabled, and there is a new gameobject called GameLiftServer. Select this, and in the inspector fill out the fleet ID and location (which should come from GameLift), the Process name (this can be anything), and the IP address that you will host the server on. If you wish to run the server and connect to it from the same location, this should be your local IP 127.0.0.1 - if the server is hosted seperately from the connecting client, instead use the public IP of the server.

Once done, Using your dedicated server requires the same steps as before - build and run your dedicated server, which should register itself with the Gamelift fleet. Then, with Catena running, open two instances of the game Galactic Kittens, and find a match! Catena will handle creating a session in the gamelift fleet, and sending the connection information over to the players once the session has been made. (Note: At this point, the session will remain active until the server becomes available and the session times out - in a real scenario, the server should inform gamelift when to terminate the fleet.)

Entitlements

While not integrated into the game itself, the main menu of the Galactic Kittens demo has functionality to display entitlements information, as well as debug functionality to prepare and execute offers - something that should normally only be done from a trusted game server.

In order to enable the entitlements functionality in the demo, you will need to go to Project Settings > Player > Scripting Define Symbols and add a defintion for ENABLE_CATENA_ENTITLEMENTS. This will allow the UI for entitlements to appear on the main menu screen - but for actual information to be shown, entitlements and offers need to be created. The items and offers need to be configured outside - for more information on how to configure items and offers, refer to the Entitlements documentation.

Once items and offers are set up, in order to see their functionality in game, you must make some calls through Catena itself - giving the player items, and getting an API key for preparing/executing offers.

Client Entitlements Functionality - Getting Catalog

The demo has the basic functionality of listing all the items that are currently in a players Catalog. Normally, the items would be added to a player's catalog through means outside of their client - whether it be from executing offers, or entitlements given from other outside services. To see an example how a player's inventory would function, log in to Catena with a test account, and get the account ID. Then, using the admin endpoints, give the account some items. Once this is complete, if you return to the game, you should see the list of items appear on the list of player items after clicking Get Catalog.

Server Entitlements Functionality - Offers

To see how preparing and executing offers would function, you first need to set up an API key with the proper permissions for offers - information on how to do this can be found in the API key documentation. Once you have an API key, if you navigate to the bootstrap scene and locate the CatenaEntrypoint object, you should see a section in the CatenaEntrypoint component for the Catena Server Api Test Key. This field is intended to only be used for debug purposes - in normal circumstances, only trusted sources should have API keys, and those API keys should be retrieved from elsewhere - but for now, pasting an API key in this field allows for easier testing of the server entitlements functionality.

At this point, when launching into the main menu, you should be able to click Prepare Offers - and after doing so, a list of all the offers you have configured should appear. You can then click on any of the offers to attempt to execute them!

To see the steps of how to integrate entitlements in to your project, check out the Unity Entitlements Guide.

Parties

Similar to Entitlements, the Unity demo does have the ability to display Parties functionality, although it's not integrated into the game itself - and is only for appearance in the UI. In order to enable the parties functionality in the demo, you will need to go to Project Settings > Player > Scripting Define Symbols and add a defintion for ENABLE_CATENA_PARTIES. This will allow the Party UI to appear after completing login in the main menu.

Testing the parties functionality does not require any setup - the only configuration required in the Catena backend is to make sure that the parties service is enabled, and a Connection String is defined for the parties database. To learn more about setting up Parties in Catena, refer to the Parties documentation.

Once Catena is up and running, to test the parties functionality, you must first run at least 2 instances of the game (but more than 2 are supported, if you desire). Log in to each game instance, and pick one of the game instances to be the 'host'. For this game instance, click Create Party - and you should soon see the active party UI. You can then copy the Invite code displayed on the UI, and paste that code into the other game instances and click Join Party.

At this point, you should see all of the players connected to the same party. From each instance, you can select a character - which demonstrates the functionality for creating and updating metadata of party members. Each instance can also click to ready up, and unready - which will be reflected in the UI for all players. The host will also have controls displayed next to each other party member - one button for kicking the player, and another for setting the player as host. Using all these options, you should be able to test the various endpoints that are available for parties.

To see the steps of how to integrate parties in to your project, check out the Unity Parties Guide.

Party Matchmaking

After you've set up parties and solo matchmaking, the only step needed to start party matchmaking is to adjust the Catena config file appsettings.Development.json. You will want to make sure the queues configured in this file match what is defined in the game. If you want to enable all of the possible queues already set up in the demo, you can add the following queues to your config file. Note that these all use the custom hook SimpleP2PMatchmakingHooks as they are set up for P2P matchmaking - to use dedicated server matchmaking, remove this hook:

{
  "Catena": {
    ...
    "Matchmaker": {
      "MatchmakingQueues": {
        "solo": {
          "QueueName": "solo",
          "Teams": 1,
          "PlayersPerTeam": 1,
          "TicketExpirationSeconds": 180,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "private": {
          "QueueName": "Private",
          "Teams": 1,
          "PlayersPerTeam": 4,
          "TicketExpirationSeconds": 1,
          "ExpirationAction": "drop",
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "team-of-2": {
          "QueueName": "Team of 2",
          "Teams": 1,
          "PlayersPerTeam": 2,
          "TicketExpirationSeconds": 180,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "team-of-3": {
          "QueueName": "Team of 3",
          "Teams": 1,
          "PlayersPerTeam": 3,
          "TicketExpirationSeconds": 180,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "team-of-4": {
          "QueueName": "Team of 4",
          "Teams": 1,
          "PlayersPerTeam": 4,
          "TicketExpirationSeconds": 180,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "up-to-3": {
          "QueueName": "Up to 3",
          "Teams": 1,
          "PlayersPerTeam": 3,
          "MinPlayersPerTeam": 1,
          "TicketExpirationSeconds": 120,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        },
        "up-to-4": {
          "QueueName": "Up to 4",
          "Teams": 1,
          "PlayersPerTeam": 4,
          "MinPlayersPerTeam": 1,
          "TicketExpirationSeconds": 120,
          "CustomHooks": "SimpleP2PMatchmakingHooks"
        }
      },
      "StatusExpirationMinutes": 15
    }
    ...
  }
}

This config should enable you to party matchmake. To do so, run two or more instances of the game, and have them join a party. Once all instances are ready, the leader can pick a queue from the dropdown list and start matchmaking.

If you wish to adjust the queues listed in the dropdown, you can do so by modifying them in the inspector. Navigate to the scene Assets/Scenes/Menu.unity and select the gameobject Canvas -> OnlineControls -> Parties, and in the inspector under the Matchmaking Queues section, you should see a list of queues that you can add/remove from, or edit existing queues.