PlayPad SDK integration guide

For asynchronous games with tournaments

To see lobby & PlayPad SDK integration requirements see the corresponding article.

Using AsyncGameSample

The main route for integrating PlayPad SDK with your Elympics game would be to use AsyncGameSample. It comes with already functional lobby scene and prefabs for streamlined gameplay integration.

Initial setup

Running the sample in the Editor for the first time (already done steps can be skipped):

1. Update Elympics SDK to the newset version
2. Install Newtonsoft (com.unity.nuget.newtonsoft-json)
3. Install PlayPad SDK or update it to the newset version
4. Import the sample
5. Import TextMeshPro essentials
6. Add new scenes to the build settings
7. Add the attached Elympics Game Config to the list in the Manage games in Elympics window and choose it as the active game
   Known bug

   There is a bug that won't allow developer to add an ElympicsGameConfig to the list manually. To do so, please delete ElympicsConfig and recreate it using Manage games in Elympics view like when starting your project.

8. Starting from the lobby scene, test if the setup works correctly

Connecting your own gameplay to the sample lobby

1. In the console, create a queue named solo (of Solo type). Alternatively, change playQueue in the TournamentPlayButton component to your pre-existing Solo type queue

2. Select your own game as an active one in Manage games in Elympics view. Also remember that your gameplay scene has to be added in the build settings

3. Be sure to check “Use HTTPS/WebRTC” in your game’s ElympicsConfig in order to make Elympics SDK work with WebGL
   

   warning

   There is a known bug, that when building to WebGL this checkbox is set automatically, but it doesn’t really work. In such case you have to check it when using another build target, be sure to save, upload new server build and only then you can proceed with building on WebGL. You will see in a version control tool if the change occured properly.

4. For gameplay scene integration, use GameplayNetworkManager prefab:

   • GenericServerHandler component is responsible for initial randomization seed determination, starting the game, and handling client disconnections on the server side
     • [mandatory action]: remove conflicting DefaultServerHandler script from Elympics GameObject (or if you have your own one, merge the functionality so only one remains)
     • [optional]: use GameJustStarted event to start the gameplay logic at the server and client at the same time, while being sure that randomization seed is already synchronized
     • [optional]: provide and reference your own implementation of randomization system deriving from SynchronizedRandomizerBase (you can remove ExampleSynchronizedRandomizer component afterwards)
     • [optional]: if your game is developed in a way allowing for rejoining a match after leaving and you want to enable such feature, change AutoTerminationOnLeft to None and utilize PlayerRejoined_ClientCallIncluded and PlayerDisconnected_ServerOnly events to handle game's behaviour
   • MatchEnder component is used for proper results uploading, including mid-game disconnection handling
     • [mandatory action]: make your score system derive from ScoreProviderBase and reference it
     • [mandatory action]: use to end the game according to your game's rules
     • [optional]: adjust the configuration for 0 score matches to be treated as not played ones (returning the tournament tickets)
   • MatchConnectionHandler component is responsible for client-side errors and temporary disconnections handling; it also hides persistent MatchConnectingMask on OnConnected event (if it exists)
     • [mandatory action]: add and reference an UI object with MatchDisconnectionMask component attached to display the errors (you can use DisconnectionMask prefab for that)

It should be working properly now, but you still should ensure smooth updating experience and customize the lobby design.

Ensuring smooth updates

Copy the lobby scene from the sample (remember to add it to the build settings!) and do not use the imported one. Any other files you are willing to modify should also be copied with the exception of prefabs, which should be made into variants.

warning

Although using these directly from Samples directory may be possible, it is not recommended as updating the package (and reimporting the sample) would erase your changes.

Customizing the lobby scene

Your lobby is now ready to embrace your creativity regarding the design and functionality! 🎨

It is important to preserve the UX suggested in the mockup, but remember that the UI and its arrangement can be way more flexible. You should provide your own UI design befitting your game style and needs. Be creative! You don't want your game menu to look like a copy-paste of many other titles, don't you?

Manual integration

warning

This approach is not recommended as it is errorprone and requires high workload. Use the AsyncGameSample instead.

1. Add PlayPadCommunicator prefab on your lobby scene and provide references to standalone configs for its PlayPadCommunicator component. To create them go to the Project context menu, then Create->Configs->Standalone

2. Ensure that ElympicsLobbyClient's AuthenticateOnAwakeWith is set to None

3. Be sure to check “Use HTTPS/WebRTC” in your game’s ElympicsConfig in order to make Elympics SDK work with WebGL

4. On Start, find the SessionManager game object and call a method connecting to the PlayPad (but only once per game application launch) and adjusting lobby UI with provided data

   private void Start()
   {
       var sessionManager = FindObjectOfType<SessionManager>();
       OnLobbySceneLoaded(sessionManager).Forget();
   }
   
   private async UniTask OnLobbySceneLoaded(SessionManager sessionManager)
   {
       bool shouldHideSplashScreen = false;
   
       if (!sessionManager.ConnectedWithPlayPad)
       {
           await sessionManager.AuthenticateFromExternalAndConnect();
           shouldHideSplashScreen = true;
       }
   
       // Put here any further lobby scene configuration and UI adjustments
       . . .
   
       if (shouldHideSplashScreen)
           PlayPadCommunicator.Instance.GameStatusCommunicator?.HideSplashScreen();
   }

5. Ensure that all the requirements are fulfilled. Use PlayPadCommunicator and SessionManager to implement the logic:

   • Tournament Rewards button should call PlayPadCommunicator.Instance.ExternalUiCommunicator.Display("tournament/rewards"). It is async and becomes complete after closing the corresponding over-game UI

   • Switch Tournament button should call PlayPadCommunicator.Instance.ExternalUiCommunicator.Display("tournaments/listing") It is async and becomes complete after closing the corresponding over-game UI

   • Use PlayPadCommunicator.Instance.LeaderboardCommunicator to set up the leaderboard UI

     • use .Leaderboard to access the leaderboard's entries, player's entry, and number of participants to display (available after AuthenticateFromExternalAndConnect)
     • use .LeaderboardUpdated event to get notified when PlayPad's leaderboard data gets updated (after leaving the gameplay scene) then adjust to it
     • [optional] use .FetchLeaderboard() to manually fetch the most recent leaderboard results from the PlayPad (meant for custom usage)

   • Use PlayPadCommunicator.Instance.TournamentCommunicator to set up tournament UI

     • use .CurrentTournament to access the tournament's data like its name, time scope, PrizePool, and more (available after AuthenticateFromExternalAndConnect)
     • use .TournamentUpdated event to get notified when PlayPad's tournament data gets changed then adjust to it
     • [optional] use .GetTournament() to manually fetch current tournament data from the PlayPad (meant for custom usage)

   • Use PlayPadCommunicator.Instance.GameStatusCommunicator to set up play button visuals, availability, and functionality

     • use .CurrentPlayStatus to access the tournament's play availability status and short text to put on the button label (available after AuthenticateFromExternalAndConnect)
     • use .PlayStatusUpdated event to get notified when tournament play availability changes then adjust to it
     • use .PlayGame(...) to load a match and run the gameplay
     • [optional] use .CanPlayGame(false) to manually fetch current play availability data from the PlayPad (meant for custom usage)

   • PlayButton should:

     • call PlayPadCommunicator.Instance.GameStatusCommunicator.PlayGame() upon click (note that PlayGameConfig's QueueName parameter is the only mandatory one)
     • try..catch around the call to handle and display potential issues
     • display match loading screen upon click (and hide it on an error)
     • change visually according to the PlayStatus
     • be non-interactable when in a Blocked state
     • use LabelInfo as displayed text
     info

     PlayPad SDK & PlayPad will take care of all the context-dependent requirements that the player has to meet to proceed with the gameplay. Corresponding UI will be displayed over your game (similar to how In-App Purchase UI could be displayed over your game in an iOS environment). So you don't have to care about what the user is doing with our (PlayPad) UI, but instead, you will be delivered a final result (which is proceeding to the game or failing with an error code)

   • Use PlayPadCommunicator.Instance.LeaderboardCommunicator to set up the player's all-time high score

     • use .UserHighScore to access the player's all-time best score (available after AuthenticateFromExternalAndConnect)
     • use .UserHighScoreUpdated event to get notified when PlayPad's best score data gets updated (after leaving the gameplay scene) then adjust to it
     • [optional] use .FetchUserHighScore() to force fetch the most recent all-time best score (meant for custom usage)

Playing outside the Editor

To learn how to run your build online, see the corresponding article.