​

How to run a game server using LocalMultiplayerAgent in Container mode

• Create a [Linux/Windows] Container Build using the Wrapper Sample
• Configure MultiplayerSettings.json
• Docker setup
• Run LocalMultiplayerAgent
• Test your game connection

​

Create a [Linux/Windows] Container Build

​

Linux Container Build

​

Windows Container Build

​

Configure MultiplayerSettings.json

{
    "RunContainer": true, // Set RunContainer to true if you are running LMA in Container mode.
    "OutputFolder": "C:\\output\\LMAContainer", // Path where config files and logs will be generated from LMA at each run
    "NumHeartBeatsForActivateResponse": 10,
    "NumHeartBeatsForTerminateResponse": 60,
    "TitleId": "", // default value
    "BuildId": "00000000-0000-0000-0000-000000000000", // default value
    "Region": "59F84", // default value
    "AgentListeningPort": 56001, // default value
    "ContainerStartParameters": {
        /// replace ImageDetails fields to your own images saved on ACR.
        "ImageDetails": {
            "Registry": "mydockerregistry.io",
            "ImageName": "wrapper",
            "ImageTag": "0.1",
            "Username": "",
            "Password": ""
        }
    },
    "PortMappingsList": [
        [
            {
                "NodePort": 56100,
                "GamePort": {
                    "Name": "game_port", 
                    // The same value of GamePort Name should be also defined in the Wrapper so Wrapper can get a port information while it's running.
                    "Number": 80,
                    "Protocol": "TCP"
                }
            }
        ]
    ],
}

"AssetDetails": [
    {
      "MountPath": "C:\\Assets",  
      // Mount Path should be "C:\\Assets" for Windows Container. 
      "LocalFilePath": "D:\\gameassets.zip" 
      // where your game server is located as an archive format.
    }
  ]

 "ContainerStartParameters": {
    "StartGameCommand": "C:\\Assets\\wrapper.exe -g C:\\Assets\\fakegame.exe arg1 arg2", 
    // Your game assets will be extracted under C:\\Assets (default mount path for Windows Container) and LMA will run your game server with StartGameCommand argument. 
     // Make sure the StartGameCommand provided above is an example of the Wrapper sample. 
    "ImageDetails": {
      "Registry": "mcr.microsoft.com",
      "ImageName": "playfab/multiplayer",
      "ImageTag": "wsc-10.0.17763.973.1",
      "Username": "", 
      "Password": ""
      // username and password are not required to use MCR image.
    }
    // LMA will package an existing game sample (path defined in LocalFilePath) as a Windows container.
 }

• LocalFilePath - Full Local Path (on your workstation) to the game server asset zip file created earlier, for example: D:\gameassets.zip (note that backslashes need to be escaped for JSON formatting). This field is required for Windows Container as LMA needs to locate your game asset and then package it into a container.
• PortMappingsList - These are the ports that are available to your game while running.
  • NodePort is the port that is opened on your workstation and will be mapped to the GamePort.
  • GamePort.Number is the port that your game server needs to bind to when running in a container. For example, here we set port number as 80 which fakegame.exe will be listening to.
  • Set the GamePort.Name to the same value as defined in your game server. You can check the GSDK config at runtime for the value with the key GamePort.Name.
  • GamePort.Protocol - Specify protocol type: TCP or UDP
  Update the GamePort section to match the protocol and port at which your game server is listening for clients. You can add multiple ports.
• ForcePullFromAcrOnLinuxContainersOnWindows - Set true when you want to pull Linux Container Image from Docker Registry and avoid pulling from the local registry. In most cases, you’d want this set to false.
• ContainerStartParameters.ImageDetails - Your game server image can be published on a container registry or can be locally built. If you want to pull Linux Container image from Docker Registry (For example, Azure Registry), you need to set value for username and password and set ForcePullFromAcrOnLinuxContainersOnWindows as true. For Windows Container, username and password aren’t required.
• OutputFolder - Path to a drive or folder where the outputs and config files are generated. Ensure that there’s sufficient space available since the game server will be extracted under this path. If not specified, the agent folder is used.
• AgentListeningPort - This is the port for the LMA to communicate with the game server. Any open port will work, 56001 is a default value. If you have another process binding to 56001, you must change this value or kill the other process on port 56001.
• ResourceLimits (optional) - If specified, docker limits CPU/memory usage. Warning: If your server goes over the allowed memory, it’s killed. ResourceLimits can only be specified in container mode.
• SessionCookie (optional) - Any session cookie that is passed to your game server as part of the RequestMultiplayerServer API call. In the real scenario on MPS, after the connection is established, server will notify the client to load corresponding resources from SessionCookie.

​

Docker set up

• For Linux Container, Run SetupLinuxContainersOnWindows.ps1.
  For Windows Container, Run Setup.ps1. It will pull down the PlayFab docker image from Microsoft/PlayFab-Multiplayer.
  Note that the first time the script runs, it can take a few minutes to download the container image.

  To run this setup successfully, you may have to configure the firewall of any 3rd party antivirus program that you have installed.

​

Run LocalMultiplayerAgent

• In a PowerShell window :
  Navigate to directory under LMA that contains LocalMultiplayerAgent.exe.
• Run LocalMultiplayerAgent.exe for Windows Container.
  Run LocalMultiplayerAgent.exe -lcow for Linux Container.
  (lcow stands for Linux Containers On Windows) At this point, LMA sets up the http listener and run a container. You can run docker ps command to see running containers on your machine.

1. CurrentGameState - Initializing
   (This may not show up if your game server directly calls GSDK::ReadyForPlayers and doesn’t call GSDK::Start)
2. CurrentGameState - StandingBy
3. CurrentGameState - Active
4. CurrentGameState - Terminating

​

Test connection to your game

​

Troubleshooting

• In container mode, if your game server exits immediately with an error similar to “Container … exited with exit code 1”, but it works fine in process mode, make sure that you’ve included all required system DLLs in your asset package.
• All logs are located under OutputFolder that is specified in the MultiplayerSettings.json file. LocalMultiplayerAgent creates a new folder each time it’s started, with the timestamp as folder name. All game server logs emitted via GSDK are located within the GameLogs folder.
  If the game server is running in a container, there might be an additional level of directory hierarchy to shift through.
• The GSDK writes debug logs to the GameLogs folder under the OutputFolder. These logs are located within the GameLogs folder along with the logs output by the game server.
• Ensure firewalls (windows and other anti-virus) are configured to allow the traffic over the ports.
• If you get an error similar to: Docker API responded with status code=InternalServerError, response={"message":"failed to create endpoint <container_name> on network playfab: hnsCall failed in Win32: The specified port already exists". It is likely there is already a container running on the specified port. This can happen if LocalMultiplayerAgent exits prematurely. Use the command docker ps to find the container that is running, and then delete it using docker kill <container_name>.
• If you get an error that contains Failed to find network 'playfab'. Try rerunning Setup.ps1

​

Known Limitations

1. Containers might not terminate at the end of the debugging. If this occurs, run the following PowerShell commands as Administrator. These commands stop and remove all containers, including those weren’t started by LocalMultiplayerAgent.

docker stop $(docker ps -aq)
docker rm $(docker ps -aq)