August 2nd, 2022

Features #

  • A Party leader can now specify a list of preferred game server zones to be used by the Matchmaking service to select a GameServerZone for a match.
    • Description: Party leaders specify a list of PreferredGameServerZones, which is included in the Party service CreatePartyV1 call and can be updated with SetPreferredGameServerZonesV1. This list can then be used by MatchmakingStrategy.addToMatchAndBuildMatchmakingDetails to select a single GameServerZone to be used in Matchmaking. Game servers should pass in the GameServerZone to MatchCapacityService.StartReportCapacityPolling.
    • Related notes: See related deprecation, feature, and integration notes for GameServerZone.
  • A GameServerZone can now be mapped to a Multiplay region using the MultiplayCapacityProvider.
    • Description: MultiplayCapacityProvider can now take a GameServerZone and map it to a Multiplay region. To use this, provide a new configuration to map GameServerZones to Multiplay RegionIds and remove the old regionId field from the config.

      If using AllocateV2, gameServerZone is passed into the allocation. You can then query the Multiplay local proxy to get the game server zone to be passed to the SDK’s MatchmakingService.StartReportCapacityPolling. Note that to use multiple region support, you will need to implement all related game server zone integrations.
    • Example:
    game:
pluginConfigs:
  MatchCapacityService.capacityProvider:
    class: "pragma.matchcapacity.MultiplayCapacityProvider"
    config:
      gameServerZoneToMultiplayRegionId:
        gameServerZone1: "b7a6d0e8-a9eb-11eb-8c6a-7d2df11035b2"
        gameServerZone2: "291b8a29-468d-4eef-aeb8-7591402c4044"
    • Related notes: See related deprecation, feature, and integration notes for GameServerZone.
  • Added two methods on both SDKs for kicking a player from a party.
    • Description: Players can be kicked from a party, which prevents them from rejoining the party unless they receive a new invitation. KickPlayerV1 makes an RPC call to kick the provided PlayerId from a party, and CanKickPlayerV1 lets the client know if it’s able to execute a kick.

      When a player is kicked, everyone in the party receives a PartyDetailsV1Notification to update the party state, and the kicked player receives a RemovedV1Notification with a KICKED reason.
  • [Portal] All config.json data has been relocated to portalDevConfig.default.js to prevent merge conflicts and ease custom portlet development.
    • Description: The /platform/web/portal/src/assets/public/config.json config has been removed, and all data has been relocated to /platform/web/portal/portalDevConfig.default.js, which can now be extended locally like all other portal configurations. The config.json data can be found under app.config and app.extraConfig configuration keys. This only affects studios with active development on custom portlets when running the Portal locally in development mode.
    • Example: To enable a custom portlet, the following needs to be added to /platform/web/portal/portalDevConfig.local.js:
    module.exports = {
   default: {
      "app.extraConfig": {
       modules: ["MyCustomPortlet"]
      }
   },
}

Deprecations #

  • Update MatchCapacityService.StartReportCapacityPolling to take the new parameter GameServerZone.

    • Description: The StartReportCapacityPolling function in the MatchCapacity service takes the new parameter GameServerZone. You will need to either update your code in the SDKs or pass in an empty string.
    OriginalReplacementRemoval Patch
    Unity:
    public void StartReportCapacityPolling(
  string serverId,
  string gameVersion,
  float timeout,
  MatchAllocatedDelegate onComplete
)
    		Unity:
    public void StartReportCapacityPolling(
  string serverId,
  string gameVersion,
  string gameServerZone,
  float timeout,
  MatchAllocatedDelegate onComplete
)
    		0.0.80
    Unreal:
    void UPragmaMatchCapacityService::StartReportCapacityPolling(
  FString ServerId,
  FString GameVersion,
  float Timeout,
  const FMatchAllocatedDelegate& OnComplete
)
    		Unreal:
    UPragmaMatchCapacityService::StartReportCapacityPolling(
  FString ServerId,
  FString GameVersion,
  FString GameServerZone,
  float Timeout,
  const FMatchAllocatedDelegate& OnComplete
)
    		0.0.80
    • Related notes: See related integration and feature notes for GameServerZone.

  • Replace the listed RPC request implementation calls with their replacements, as they are being removed.

    • Description: This is part of our larger engine cleanup. If you’re using any of these calls in plugins or custom services, replace them and apply transforms when necessary.
      originalreplacementremoval patch
      Service::requestRpcAndTransform()Service::requestRpc()0.0.80
      RpcClient::requestRpcAsync()async { requestRpc() }0.0.80
      Service::requestRpcAsync()async { requestRpc() }0.0.80
      Service::requestRpcAsyncAndTransform()async { Service::requestRpc() }0.0.80

  • Update SDK configuration with new authorization tokens.

    • Description: The original partnerSessionAuthToken config value in Unity/Unreal SDKs was built before the separation of Social and Game backend tokens. The new config values partnerSessionGameAuthToken and partnerSessionSocialAuthToken have been added to allow Partner sessions to designate specific tokens per backend. The original config value will be removed in 0.0.80.

      Add a partnerSessionSocialAuthToken config option for situations where a Partner session needs to connect to the Social backend, and provide it with a Partner Social token.

      In the Unreal/Unity SDK, update any configs with a Partner session auth token (such as in pragma.json).
      originalreplacementremoval patch
      partnerSessionAuthTokenpartnerSessionGameAuthToken0.0.80

Integrations #

  • If you’ve customized your CapacityTracker or MatchmakingStrategy, you will need to update your plugins for the new GameServerZone features.
    • Description: Studios who have customized their own CapacityTracker or MatchmakingStrategy will need to update their plugins. These two game loop plugins allow the user to set up GameServerZone flows within their match loop.
    • Integration steps:
      • Update implementations of the CapacityTracker add function to receive a new parameter indicating which GameServerZone a game should be created in.
      • Update implementations of the MatchmakingStrategy function addToMatchAndBuildMatchmakingDetails to return a Pair<ExtCreateMatchV1Request, String>?. The second new string return value allows the plugin to indicate which GameServerZone the match should be created in. If you don’t want to use GameServerZone, use an empty string here.
        originalreplacement
        ExtCreateMatchV1Request?Pair<ExtCreateMatchV1Request, String>?
  • Add new ExtHiddenPartyData and ExtHiddenPlayerData proto definitions to partyRpcExt.proto.
    • Description: The new ExtHiddenPartyData and ExtHiddenPlayerData protos will allow you to store temporary data about players and parties throughout the game loop.
    • Integration step: Add the following proto definitions to ext-protos/src/main/proto/shared/partyRpcExt.proto in order to successfully compile.
      message ExtHiddenPartyData {
}
message ExtHiddenPlayerData {
}
  • If you’ve implemented your own MatchCapacity provider, remove the coroutineScope argument from the init() method.
    • Description: To increase product maintainability and reliability, CapacityProvider.init() no longer takes coroutineScope as an argument.
    • Integration step: If you’ve implemented your own MatchCapacity provider from the ground up, remove coroutineScope from its init() method. If you’ve extended an existing Pragma Engine MatchCapacity provider, no action is required.

      If you still need coroutineScope support, please reach out to us directly.
  • [Portal] If you’ve written a custom PortalModulePlugin, CORS definitions need to be rerouted into their respective gateways.
    • Description: Anyone who has written a custom PortalModulePlugin will need to reroute CORS definitions. The attachPortalModule function on the Portal plugin has been removed and the install CORS functionality has been moved out to the gateways.
    • Integration step: Update attachPortalRoutes to take in an Application instead of a Routing object. For example:
OriginalReplacement

override fun attachPortalRoutes(
  routing: Routing,
  pragmaNode: PragmaNode,
  infoEndpoint: Url
) {
  routing.route("config/config.json") {
    get {
      call.respondText(
        buildConfigJson(pragmaNode,infoEndpoint),
        ContentType.Application.Json
      )
    }
  }
  routing.static {
    staticRootFolder = File(config.portalSource)
    files(".")
    default("index.html")
  }
}

override fun attachPortalRoutes(
  application: Application,
  pragmaNode: PragmaNode,
  infoEndpoint: Url
) {
  application.apply {
    routing {
      options {
        call.respond(HttpStatusCode.OK)
      }

      route("config/config.json") {
        get {
          call.respondText(
            buildConfigJson(
              pragmaNode,
              infoEndpoint
            ),
            ContentType.Application.Json
          )
        }
      }

      static {
        staticRootFolder = File(config.portalSource)
        files(".")
        default("index.html")
      }
    }
  }
}
  • [Unreal] Update C++ Raw Service class names from Pragma to the root of your proto package.
    • Description: For any generated raw services, the C++ class names have changed to use the root of your proto package instead of Pragma.
    • Integration step: Update generated custom raw service names:
      originalreplacement
      UPragmaCustomServiceRawUGameCustomServiceRaw

Docs #


Pragma Engine 0.0.77
Pragma Engine 0.0.79