Pragma.gg

Prepare your environment.

  1. Merge our branch into your pragma.gg repository. Our custom services are located in 5-ext folder.

  2. The only change to existing pragma codebase is changing visibility modifier in AccountDao to access necessary info about users in our custom services.

Working with custom services

  1. The main classes to work with are AuthCodeService and ExternalMatchmakingService.

  2. AuthCodeService provides OAuth-like functionality for pragma - it issues one-time codes for user profile data and allows third-party services to access profile information on behalf of user (via one-time codes). This service is used to integrate Pragma account system and Escs account system together. You will need to set up Escs OAuth application as described here. In this scenario Pragma is going to act as "provider" for Escs accounts system.

  3. ExternalMatchmakingService provides means for Pragma players to enter a match that is created by Escs platform. High level process of match creation will be described later.

  4. Custom services provided by escs are used to communicate both with escs platform and with pragma itself (e.g. internal services)

  5. For our matchmaking to work you also have to use escs' matchmaking plugin, party plugin and match end plugin/dependent job. These pieces all work together and if you omit one of them, other will not work too.

Configuration

  1. To configure these services you need additional entries in your pragma yaml config. Here is an example:

social:
  serviceConfigs:
    AccountDaoConfig:
      databaseConfig:
        driver: "MYSQLDB"
        hostPortSchema:
          "localhost:3306/local_social_account"
        username: "superuser"
        password: "password"
    AuthCodeServiceConfig:
      authCodeTTL: 300
      authCodeApplicationId: "applicationId"
      authCodeApplicationSecret: "applicationSecret"
      maxCacheSize: 1000
      dbCleanInterval: 10
    AuthCodeDaoConfig:
      databaseConfig:
        driver: "MYSQLDB"
        hostPortSchema:
          "localhost:3306/local_social_account"
        username: "superuser"
        password: "password"

AccountDaoConfig - please enter your datasource parameters for account store. This should be the same as for default pragma services.

AuthCodeServiceConfig - specific values for AuthCodeService.

  • authCodeTTL - amount of seconds for access code to be valid

  • authCodeApplicationId - app id provided by escs platform here

  • authCodeApplicationSecret - secret provided by escs platform here

  • maxCacheSize - size of in-memory cache for auth codes (per service per node, all codes are also always stored in db)

  • dbCleanInterval - interval to clean db of expired codes in minutes

AuthCodeDaoConfig - please enter data source parameters to store auth codes. Could be the same instance that uses pragma.gg

game:
  serviceConfigs:
    MatchmakingDaoConfig:
      databaseConfig:
        driver: "MYSQLDB"
        username: "superuser"
        password: "password"
        hostPortSchema: "localhost:3306/escs_matchmaking"
    ExternalMatchmakingServiceConfig:
      cleanInterval: 10
    EscsResultsServiceConfig:
      url: "https://api.escs.io/rpc/SetRoundResult"
      secret: "secret"
      gameId: "gameId"
  pluginConfigs:
    MatchmakingService.matchmakingPlugin:
      class: "matchmaking.escs.ExternalMatchmakingFillPartyPlugin"
    MatchLifecycleService.matchEndPlugin:
      class: "matchlifecycle.escs.DefaultEscsMatchEndPlugin"
    PartyService.partyPlugin:
      class: "matchmaking.escs.ExternalMatchmakingPartyPlugin"

MatchmakingDaoConfig - please enter data source parameters to store matchmaking info from escs platform. Could be the same instance that uses pragma.gg

ExternalMatchmakingServiceConfig

  • cleanInterval - interval to clean db of expired matchmaking info in minutes

EscsResultsServiceConfig

  • url - please enter url as provided in the yaml code snippet (or contact us to use staging intances for testing purposes); this is url of our platform to receive match results

  • secret and gameId - provide info from your game setup on this screen: escs client -> Apps -> your game :

    pluginConfigs -provided in the yaml code snippet These classes are important for our matchmaking to work. If you have your own custom matchmaking and you want to support both escs and your own matchmaking, then you need to wrap our classes inside yours and distinguish matchmaking by Pragma queue keys (as described here: https://pragma.gg/docs/concepts/multiplayer/matchmaking/matchmaking-key-concepts#matchmaking-queues)

Required protobufs

There are couple of required additions to global protobufs that you might want to be aware of (they should automatically be merged when getting mentioned git branch)

  1. message ExtMatchmakingParty {
        .matchmaking.escs.SetStartPayload escs_matchmaking_info = 10001;
}

    This data is required to correctly assemble parties with escs data.

  2. enum ExtError {
        option (unreal_enum_name) = "ExtError";

    UNKNOWN_EXT_ERROR = 0;
    //  === EXTENSIONS (10001+) ===
    AUTH_CODE_NOT_FOUND = 10001;
    AUTH_CODE_EXPIRED = 10002;
    ESCS_CANNOT_CREATE_PARTY = 10003;
    ESCS_CANNOT_JOIN_PARTY = 10004;
    ESCS_MATCHMAKING_ERROR = 10005;
    ESCS_PARTY_NOT_FOUND = 10006;
}

    This is required to produce specific service errors.

AuthCodeService

Provides 2 endpoints: AuthCodeRpc.AuthCodeV1Request on social player backend and AuthCodeRpc.GetPlayerWithAuthCodeV1Request on social partner backend. GetPlayerWithAuthCodeV1Request lets escs to access pragma's player information to bind/create escs account. You don't need to use it, escs already took care of it. You only need to configure escs account in client.escs.io like described here.

For Game api url use your social partner pragma backend address and append /v1/rpc to it like this: https://your-backend.com/v1/rpc.

For Request Type and RPC type use values provided on the screenshot. Auth token should be generated by pragma backend and pasted in specified field. You can generate it in pragma web dashboard.

Note: you may need to add your backend to escs account system allowed hosts at account.escs.io -> developer -> edit app.

How to use AuthCodeService

The general flow is described here. AuthCodeService тут is playing the role of "your backend" in provided flow. To use it in game you have to let player to perform some kind of action, which leads to question "Do you want to let ESCS access your profile information?". If user answered yes, you can generate one-time access code and provide it to ESCS plugin in your game. Another option is to integrate with Escs plugin of your specific game engine and implement OnUserProfileRequested callback. This callback is called when a user is clicking "use game account to log in" inside escs overlay. You can get one-time code either using plain pragma rpc or via generated Unreal/Unity wrappers. Please refer to corresponding section for Unreal Escs plugin / Pragma integration. To use plain rpc you need to issue a request of form:

{
    "requestId": 1,
    "type": "AuthCodeRpc.AuthCodeV1Request",
    "payload": {
        "playerId": "any string"
    }
}

to pragma social player backend /v1/rpc endpoint. This will return access code that escs platform can use to access user profile data:

{
    "sequenceNumber": 0,
    "response": {
        "requestId": 1,
        "type": "AuthCodeRpc.AuthCodeV1Response",
        "payload": {
            "authCode": "c29c7043-16dc-4860-bd93-6bb2b360d2c4"
        }
    }
}

Now you can pass this authCode to escs plugin. After that escs will get user's profile data from your pragma backend and link it to existing or new escs account. After that your players are ready to use tournaments and other features of escs!

ExternalMatchmakingService

Provides several endpoints that you are going to use in your game and some endpoints for escs platform to pass data about matches. Below are simple diagrams describing how ExternalMatchmakingService is working to create matches for escs platform. We'll break it into 2 phases. The queueing phase and matchmaking phase.

  1. Queueing phase:

  • At given time (as per tournament settings and setup in Escs client dashboard) escs platform issues "set start" events. What is called in escs "a set" is one round of gameplay, i.e. "match" in Pragma. This event is received both by escs plugin that integrated in game (could be android, ios, desktop plugins, unity, unreal and so on) and also by escs custom services in pragma backend.

  • Escs pragma custom service records that information and is ready for players to join.

  • Players after receiving set start event should call RPC ExternalMatchmakingRpc.QueueForMatchmakingV1Request. This will automatically create party if needed and join the player if party for this match is already created. If you're using plain json then the request is in the following form (note that it should be issued for pragma game backend): 

{
    "requestId": 1,
    "type": "ExternalMatchmakingRpc.QueueForMatchmakingV1Request",
    "payload": {
    }
}

  • Upon successful request players are going to receive status QUEUED. At this point, player is awaiting for other players in a match to join his party.

  • When all players that are needed for the match to start are QUEUED, each is going to receive PartyIsCompleteForMatchmakingV1Notification from pragma backend. This notification ends queueing phase.

  1. Matchmaking phase:

  • After receiving PartyIsCompleteForMatchmakingV1Notification from pragma backend the party leader (party leader would be the first player that entered the flow, all others just join this party) can enter matchmaking using regular pragma matchmaking tools: i.e. issuing EnterMatchmakingV1 rpc. Note that every player should be in READY state for matchmaking to start.

  • Escs ExternalMatchmakingFillPartyPlugin checks the party for integrity and that it has all required info for starting a match and recording results.

  • Normal matchmaking proceeds with determining available game servers capacity etc. and issuing match start on your game backend with determined players as usual - no escs-specific logic is required.

  • when the match ends, pragma receives MatchEndV4 request. This in turn triggers escs match end plugin and match end job. You can use your own plugin, just add escs-specific SendResultsToEscsMatchEndDependentJob to the list of jobs. It will require EscsResultsTransformerPlugin - this is the place where you should transform your own matchEnd results to pairs of key-value metrics that escs platform accepts. It should implement the single method transform(ext: ExtPlayerMatchEnd) : Map<String, Double> which takes you game specific ExtPlayerMatchEnd type and returns map of key-value for escs.

  • SendResultsToEscsMatchEndDependentJob automatically sends the transformed results to escs. At this point results are successfully received and processed and next stage of tournament should run, or the tournament ends.

Working with match (set) info from escs platform

When configuring escs tournaments in dashboard, there are several parameters that you can specify for your game to receive. Some are metadata that is only understandable to your game, and there is also data that is created by escs to describe the set.

You can access this data in your matchmaking party ext proto: 

message ExtMatchmakingParty {
    .matchmaking.escs.SetStartPayload escs_matchmaking_info = 10001;
}

Wherever you can access ExtMatchmakingParty object (that would be party plugins or match starting code), you can also access all escs-specific data too. SetStartPayload has the following structure:

  • setId - setId of started set (string)

  • tournamentId - tournamentId of the set (string)

  • matchId - matchId of the set (string)

  • setEndTimeUnix - game's set max end time in unix time (i.e. time when the set will be ended forcefully even if players still have no game outcome; you should send any game results before this time and end the game session)

  • pariticipants - list of Participant. Each participant contains list of Player. Player object consists of:

    • playerId - escs player id (string)

    • ingamePlayerId - registered in-game player id via registerInGamePlayerId (string)

    • username - user's escs username (string)

    • firstName - user's escs first name (string)

    • lastName - user's escs last name (string)

    • ingameMetadata - in-game metadata that was registered via registerInGamePlayerId (string) and global metadata from tournament dashboard

    • roundId - roundId of the set (this is in fact id of the set "results") (string)

PreviousJS WatchThisNextUnreal

Last updated