Federated Game Server

Game Server Federation allows you to integrate with 3rd Party Game Server Orchestrator (such as Hathora or Agones) as well as running arbitrary server-authoritative code before a "found match" notifies its players.

The interface you implement looks like this:

public async Promise<ServerInfo> CreateGameServer(Lobby lobby);

There are 3 Federation Calls to this function:

• Matchmaking Match Found: This is an Out-of-Band Call where the Beamable Backend will call the CreateGameServer function for each match produced by its matchmaking tick. To have your locally microservice process these requests, you need to configure a content type as a filter for the traffic (see Federation tab of the Microservice).
• Provision Game Server for Lobby: This is an In-Band call where Lobby's Host Player asks Beamable to provision a Game Server for their Lobby.
• Beam PIE's Fake Lobby: This is an In-Band call made by Beam PIE's Fake Lobby setup. You can read more about this in our Real Time Multiplayer Guides.

Configuring a Game Server Federation to be Called

Beamable's Backend leverages a Content called UBeamGameTypeContent (game_types). A GameType is essentially a set of rules for how Beamable's Matchmaking should produce matches of this game type (including the federation).

1. Implement IFederatedGameServer federation in your microservice with a particular Federation Id.
2. Set up that Federation Id in any UBeamGameTypeContent's federation field.
3. Publish the Content.

The Create Game Server function is a blocking call with a long default timeout. This means Beamable's Backend waits on a response before notifying the users they were put into the lobby. However, implementing this correctly for all cases, can be challenging --- as such, we provide a few utilities:

public async Promise<ServerInfo> CreateGameServer(Api.Autogenerated.Models.Lobby lobby)
{
    var serverInfo = new ServerInfo();

    // Use this function to parallelize: 
    //  - Creating the lobby in your Orchestrator;
    //  - Preparing your lobby's Global Data;
    //  - Preparing each player's PlayerData dictionaries.    
    await lobby.PrepareLobbyAsDedicatedServer(serverInfo,

        // The first function is where you'll provision the game server.

        async l =>
        {            
            var connInfo = new ServerInfo();

            // IF the lobby is NOT a fake lobby from PIE/Playmode, you should be provisioning a server.
            // Lobbies that are created via BeamPIE are flagged as such so you can avoid asking your Orchestrator for a server.
            if (!l.IsLobbyFromEditorPlayMode())
            {
                // This means we actually need to providion a server and then set its connection information in the lobby.
                connInfo.SetConnectionString("my orchestrator's conn host", "my orchestrator's port");
            }            

            return connInfo;
        },
        // This second function is where you should get your game-specific data and set it into the lobby's Global Data; which map player's will be playing in, for example.                        
        l =>
        {            
            return Task.FromResult(new ServerInfo());
        },
        // The last function runs ONCE PER LOBBY PLAYER --- here you'll usually be reading from stats, inventory and the lobby itself to validate and fill out what your game server and clients need. 
        lp =>
        {   
            return Task.FromResult(new Dictionary<string, string>());
        });

    // Because we want Clients to start connecting AFTER the Game Server is ready to accept them, we make this call.
    await lobby.WaitForGameServerReady(Provider.GetService<IBeamLobbyApi>());

    return serverInfo;
}

You can check out our Beamball Demo for more information on how to leverage this CreateGameServer function.

Developing with your Local Microservice and PIE

For the In-Band calls (Provision Game Server for Lobby and BeamPIE's Fake Lobby), as long as your local microservice is running, your PIE clients will invoke it and that's that.

When testing this from the actual matchmaking queue (as opposed to using BeamPIE to start the gameplay level directly), you'll need to set a content-based filter for which queues you want your locally running microservice to handle when it's running.

You can do this via the Federation tab of the Microservice window or by using the following Beam CLI commands:

# Gets the current content filter for the this Service, FederationType and Federation Id.
dotnet beam federation local-settings get IFederatedGameServer --beamo-id MyService --fed-id myid

# Sets the content ids filter for the IFederatedGameServer
dotnet beam federation local-settings set IFederatedGameServer --beamo-id HathoraDemo --fed-id hathora --content-ids game_types.my_queue

Provision Game Server for Custom Lobby (non-Matchmaking)

Certain games allow players to create custom lobbies manually. If those games also require invoking the federation endpoint to provision a server or run some arbitrary code, they can do so via the following steps:

1. Create a Lobby with the UBeamGameTypeContent's id.
   1. Closed/Open lobbies both work with federation.
2. Players will join the lobby and eventually become ready.
   1. Most custom lobby implementations use UBeamLobbySubsystem's UpdatePlayerTags function to update each individual player's ready state.
3. Once all players are ready, the lobby host can invoke the UBeamLobbySubsystem's ProvisionGameServerForLobby function.
4. This function requests that the configured federation on the UBeamGameTypeContent's be run.
5. Once it does, it'll trigger UBeamLobbyState's OnLobbyUpdated callback for the lobby each particular player is in.
   1. You can then use Local State - Lobby - Open Level and, if you've set the connection information in the lobby's data (ULobby::Data), this node will connect and travel accordingly.

While we don't have a sample showcasing this exact case, you can still learn a lot about this from our Beamball Demo. sample.