Local DS

1. Overview

To facilitate the rapid deployment of the game on a DS in a non-production environment, PGOS provides a local DS mechanism. This allows you to deploy a game on a local (non-cloud) DS without having to add any additional code to the DS or game client. This type of DS is included in the PGOS work system as an available DS and allocated to the game client, as shown in the figure below:

The local DS mechanism is applicable to the following scenarios:

• Game debugging in the project development stage.
• Small-scale internal playtesting.

2. Overall use process

sequenceDiagram Developer->>Portal: simply create a local placer Portal-->Developer: local placer id Developer->>Portal: associate local placer to match or lobby config Developer->>Local DS: add local placer id to DS config (bind DS to local placer) Developer->>Local DS: launch local DS process instances Developer->>Game Client: launch game client process instances Game Client->>PGOS: start battle with matchmaking or lobby PGOS->>Game Client: place the battle session to the local DS Game Client->>Local DS: connect to local DS, gameplay Local DS-->Game Client: gameplay

3. Detailed user guide

Before learning how to use local DS, we shall first clarify the following concepts:

• Local DS: In contrast to packaging the DS as a build and uploading it to PGOS, local DS can run in any specified environment, not the CVMs provided by PGOS.
• Local Placer: This is the placer dedicated to mounting local DS. Just like Placer, Local Placer can be associated with matchmaking configurations/lobby configurations. Different from Placer, Local Placer does not need to be associated with fleets. You can directly register the local DS with the specified Local Placer. See below for the specific process.

3.1 Create a Local Placer

Log in to the web portal, access your title region, and go to DS & Builds > Placers:

As shown in the figure above, create a local placer named MyPlacer:

• Placer Name: The name can only contain letters and numbers and must start with a letter. The maximum length is 128 characters, and local placer names must be unique.
• Find DS Timeout: This is the maximum wait time when battle session placement requests are sent to the placer. It can be set from 10 to 600 seconds and cannot be modified after creation.

After you create the local placer, you will see the interface shown below:

3.2 Associate to Match/Lobby

You can only modify the match/lobby configs that need to place battle sessions on the local placer (local DS).

Associate Local Placer to Match Config

Go to Battle > Matchmaking, find the match config to be used in your game, and edit it as follows: Change the Placer property to MyPlacer.

Associate Local Placer to Lobby Config

Go to Battle > Lobby, find the lobby config to be used in your game, and edit it as follows: Change the Placer property to MyPlacer.

3.3 Bind DS to Local Placer

When creating a local placer, you can get a local placer ID from the placer information:

Now, you can write this local placer ID to the DS pgos_server_config.ini which binds the DS to the specified local placer. The location of the file:

• If launching the local DS via the UE project, look in the directory: {GameProjectPath}\Saved\PgosRes\
• If launching the local DS from a packaged program, look in the directory: {PackedGamePath}\{GameName}\Binaries\pgos_res

The following is an explanation of the relevant configuration items:

• local_placer_id: This specifies the local placer bound to the DS. If a value is specified, it is Local DS mode.
• local_ds_ip: This specifies the IP address to bind to the local DS (it will be distributed to game clients to establish connections). If it is empty, PGOS will automatically obtain it from the local machine.

3.4 Launch DS Process Instances

After performing the operations above, your DS will be set to Local DS mode. Now, you can directly launch process instances for it on the local device. These instances will be associated with the specified local placer. You can launch multiple process instances, or launch the instance on multiple local devices. From the portal, you can see the current local DS list of the local placer, as shown in the following figure:

MyPlacer has six local DS instances, all in the Idle status. This means they can accept battle sessions.

Generally, the local DS Instance status changes with the DS process and battle session statuses. However, if the local DS process is terminated abnormally, the PGOS backend will have to perform three health checks before judging it to be offline. To avoid having a new battle session allocated to the problematic DS Instance, you can manually delete the DS instance from the local placer details page on the portal. Possible local DS Instance status values:

• Idle: The local DS is ready and can accept a battle session.
• Pending: PGOS has placed a battle session on this local DS, but the local DS has not yet activated the battle session.
• Active: The local DS has activated the battle session.
• Offline: The local DS is offline. If the DS returns FALSE in three consecutive OnHealthCheck callbacks, or if OnHealthCheck is blocked for more than three health check cycles, the local DS is judged to be Offline. When the local DS is in the Offline status, if it returns TRUE in an OnHealthCheck callback within 8 hours, it will recover from the Offline status. Two typical scenarios are described below:
  • The local DS process is suspended by the debugger.
  • The local DS process is terminated abnormally, e.g. it is killed or crashes.

3.5 Launch Game Client Process Instances

Now that the local DS is ready, you can launch the game client and initiate a battle session. The PGOS backend will place the battle session on the local DS. The following takes the PGOSShooter game client as an example:

Start 1 vs 1 mode matchmaking:

Matchmaking successful, enter the battle:

Play the battle:

Now, you can go to the portal and check the local DS instance status in the local placer:

A battle session is placed on the local DS instance with port 7777. You can click on the battle session ID to go to the details page for this battle session:

The local DS is now running, and you can test/debug it on the local machine.

4. Maintain Active Local DSs

Since the number of active process instances of local DS is not automatically guaranteed like in a cloud environment, you may need to find a solution to automatically maintain the number of local DS. For example, write a system command script that automatically maintains the desired number of available Local DS processes.

5. Note

• Make sure that the local machine that runs local DS has smooth outbound and inbound network communication.
• If a local DS process is suspended by the debugger for over 8 hours, PGOS will remove it from the local DS list.