Add Players to a Game Instance #

This topic provides instruction on adding players to new or existing game instances.

Players are not added to a game instance until the Game Instance interface’s addPlayer() method is called. This method can be invoked in the following ways:

• by calling the Game Instance API’s join() method from the player client to enter the player into an existing game instance
• by calling addParties() from a Matchmaking Plugin method to add players from one or more parties to a game instance (see Create or update game instances in matchmaking).
• by calling the GameInstanceApi backend class’s addPlayers() method from a backend method or service to add one or more players to a game instance

The above scenarios invoke handler methods that in turn invoke GameInstance.addPlayer(). You can also choose to call GameInstance.addPlayer() from other Game Instance Plugin methods.

Join an active game instance #

Join an active game instance using the player client SDK

Player clients can join an existing game instance using the Game Instance API Join() method with the game instance ID and a ExtPlayerJoinGameInstanceRequest payload.

Player->GameInstanceApi()->Join(
  const FString& GameInstanceId, 
  const FPragma_GameInstance_ExtPlayerJoinGameInstanceRequest& RequestExt,
  const FOnCompleteDelegate& OnComplete
)

Player.GameInstanceApi.Join(
  PragmaId gameInstanceId, 
  ExtPlayerJoinGameInstanceRequest requestExt,
  CompleteDelegate onComplete
)

Handle player client join requests #

The Game Instance API’s join() method invokes the Game Instance Plugin’s handlePlayerJoinRequest() method, which you can customize to handle player data. Call GameInstance.addPlayer() from this method to allow the player to join the game:

suspend fun handlePlayerJoinRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    requestingPlayerId: PlayerId,
    requestExt: ExtPlayerJoinGameInstanceRequest
) {
    gameInstanceSnapshot.addPlayer(requestingPlayerId)
}

If you want to prevent a player from joining a game instance while in another game instance, use this method to throw an application error. To prevent unnecessary or unintended player additions, the method throws an error by default.

Add players from the backend #

Add players to a game instance using backend methods or custom services

Players can be added directly to a game instance via the GameInstanceApi.kt backend class’s addPlayers() method. To do so:

1. Create an instance of the GameInstanceApi.kt Kotlin class in a Pragma plugin or custom service:

private val gameInstanceApi: 
    GameInstanceApi = GameInstanceApi(service)

2. From a backend service, call the GameInstanceApi.kt class’s addPlayers() method with the game instance ID, ExtBackendAddPlayersRequest payload, and list of players to add to the game instance.

suspend fun addPlayers(
    gameInstanceId: GameInstanceId,
    requestExt: ExtBackendAddPlayersRequest,
    playersToAdd: List<PlayerToAdd>
): PragmaResult<Unit, PragmaFailure>

Handle backend add players requests #

When adding players to a game instance from the backend or through matchmaking, you have a chance to perform tasks such as verifying players or forwarding player data to the game instance using the Game Instance Plugin’s handleBackendAddPlayersRequest() method.

If you want to prevent a player or players from being added to a game instance while in another game instance via backend methods, use this method to throw an application error.

Example usage:

For example, say you know exactly what players should be added to a specific existing game instance, and you need to forward their character selections to the game instance. You can customize the handleBackendAddPlayersRequest() method to use the player’s ExtBackendAddPlayersRequest to populate their game instance ExtData.

override suspend fun handleBackendAddPlayersRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    requestExt: ExtBackendAddPlayersRequest,
    playersToAdd: List<PlayerToAdd>
) {

    playersToAdd.forEach { (playerId, playerExt) ->
        val gamePlayer = gameInstanceSnapshot.addPlayer(playerId)

        val playerCharacterExtData = ExtData.newBuilder().setCharacter(
            playerExt.selectedCharacter
        ).build()

        gamePlayer.dataStore.create(
            "character", playerCharacterExtData,
            PlayerSync.Player(playerId)
        )
    }
}

See Connect Players to a Game Server to learn how to connect players to their game instance’s host server.