Skip to main content

Appendix B - API Reference

Game Start Implementation​

Restart​

This method is called by joyride code after the game’s scene is loaded. It is not called if the game has started already.

public abstract void Restart(JRGameInfo gameInfo)

Following tasks should be handled in this function:

  • Reset the game score,
  • Reset UI
  • Populate the UI with player info(name, profile-gif etc) present in the gameInfo parameter,
  • Connect all players to the game server. But the game should not start yet until the StartGamePlay method is called
Example

In the Runner game, it resets the score & UI, but the player doesn't start running. In a ludo game, it resets the board, populates the UI with players’ info, connects itself to the game server, and waits for others to join.

Parameters​

JRGameInfo has all the properties which can be used as input for the game. Below are the details

  • isDebugMode property can be used to toggle the visibility of Debug UI if required

  • myInfo and opponentArray properties, which contain information about all the players

  • JRUserInfo is the data type of myInfo and each item of opponentArray

  • roomName property has to be used to uniquely identify the room in which all the players for a given session will join. If you have a separate game session server like photon, make sure this param is used to join the room.

JRUserInfo has the properties to represent various attributes of a player. Below are the details

  • gameLevel represents GameAI level of a player. If its value is 0, it represents a REAL player, else if its value is greater than 0 then it represents a GameAI player. We can use different values to identify the smartness of the GameAI

  • abandonGameLevel represents GameAI level of a player when a REAL player leaves the game. If its value is 0, then the game should not give a chance to play for this player if he leaves the game. If its value is greater than 0, then the game should autoplay on behalf of the left player. In both cases, ‘Left’ should be shown near the user's profile

  • isFue flag represents whether or not the game is being played as part of FUE. Game mechanics/parameters may be required to change based on this flag

  • difficultyLevel represents the difficulty level of the game to be served to the user. Its range can vary for different games and is configurable from CMS

  • duration represents max amount of time given to user to play this game (optional)

  • gameSpecificConfigJson is a json string that gets passed as it is from CMS. This can be used to control game specific attributes/parameters

OnRestartCompletion​

In multiplayer games this function should be called when all the players have connected to the game server (eg - Unity Photon). Game should not have started yet

public virtual void OnRestartCompletion()

Joyride code waits for this callback or OnMatchFailed callback whenever joyride code sends a restart command via below method of Joyride.cs. It should be called on the latest instance of JoyrideGame

void Restart(JRGameInfo gameInfo)
Note

This method should be called by the game when all the tasks of the Restart function are successfully completed

OnMatchFailed​

This method should be called by the game if all players are unable to join the game within a specified time duration of 40 sec. 

public void OnMatchFailed()

Joyride code waits for this callback or OnRestartCompletion callback whenever joyride code sends restart command via below method of Joyride.cs.

void Restart(JRGameInfo gameInfo)
Note

If it is a single player game like solitaire, then this method is not needed

StartGamePlay​

This method is called by joyride code after successfully receiving OnRestartCompletion from all the other users of the current game. Parameter ` -

public virtual void StartGamePlay(string activeUserIds)

Parameters​

'activeUserIds` is the json array of userIDs that are currently active in the game. This method is responsible for handling the following tasks

  • Reset (if required)

  • Start the game. Eg - In a runner game,the player starts running

OnGamePlayStarted​

This method should be called by the game when the game starts

public void OnGamePlayStarted()

Joyride code waits for this callback whenever joyride code sends startGame command via the below method of Joyride.cs

void StartGamePlay()

Score Implementation​

CalculateScore​

This method is called by joyride code for results declaration. This method should return the current score of the user (with user ID userId) if available, or else return 0. It can be called even after the game ends, but before the next restart or cleanup command.

public abstract int calculateScore(string userId)

JRUpdateScore​

This method should be called by the game to update the score changes. If it is not score based game like ludo, then calculate the score with formula (totalInitialPlayerCount - rank + 1)

public void JRUpdateScore(int score)

JRUpdateGameAIScore​

If a GameAI is implemented on the client side, GameAI score should be updated using this call. Here, userId is the user ID of the GameAI.

public void JRUpdateGameAIScore(long userId, long score)

getUserIdToRankMap​

If the game is a non-scoring game, this method should be overridden. It should return userId to rank map based on current game status, if available. It can be called even after the game ends. 

public virtual Dictionary<string, int> getUserIdToRankMap()

getGamePlayStats​

This method must return the current game stats for this user if available, else return empty list or null. It can be called even after the game ends.

public abstract List<double> getGamePlayStats(string userId);

Game End and Disconnection Implementation​

CleanUp​

This method is called by joyride code when all the other players disconnected from the server or before starting a new match. This is responsible for cleaning the game, pausing any services which are running in the game, disconnecting itself from the game server, and muting the audio.

public virtual void CleanUp()

OnDisconnected​

This method should be called by the game whenever the user gets disconnected from the game server (eg - UnityPhoton). The user will be considered as lost in this case. 

public void OnDisconnected()

OnGamePlayEnded​

This method should be called by the game when the game ends. Game can either end normally or all other players leave. If sendState is true, then before notifying “end”, it calls OnPlayersStateUpdated also.

`public void OnGamePlayEnded(bool sendState, EndTrigger endTrigger = EndTrigger.COMPLETE, EmbeddedGameSummary embeddedGameSummary = null)

OnPlayersStateUpdated​

This method should be called mainly for those games, in which a player can be the winner even if he leaves in the middle of the game or if the game has GameAI implementation on the client side. 

public void OnPlayersStateUpdated()
Example

For ludo, if a player moves all its pawns to Final Triangle Home and becomes 1st place player, and then if he leaves, he still remains 1st place. This method should be called whenever any player’s rank gets fixed.

In normal game play of ludo, it will be called whenever any player moves all its pawns to Final Triangle Home

OnGameAIGamePlayEnded​

This method should be called if GameAI is implemented on the client side and GameAI game has ended before the user. If the GameAI game ends along with the user, GameAI game end will be handled in OnGamePlayEnded function call with sendState as true.

public void OnGameAIGamePlayEnded(long userId, long score)

ShowResultScreen​

This method is called if there is a separate CTA to show the Joyride result screen

public void ShowResultScreen()

Tutorial Implementation​

Following implementation is required if the tutorial is implemented inside the game. You can skip this step if the tutorial is not implemented inside the game

LoadTutorial​

This method is called by joyride code to load the game tutorial and if user related information is displayed in the UI, userInfo can be used.

OnTutorialLoaded function should be called as a response once the tutorial is loaded successfully.

protected virtual void LoadTutorial(TutorialInfo tutorialInfo)

OnTutorialLoaded​

This method should be called by the game when the tutorial is loaded.

public void OnTutorialLoaded()

OnTutorialSkipped​

This method should be called by the game when a user skips tutorials(if the skip button is available). Before calling this function make sure the game is ready for the Restart function call (Reset tutorial related UI or variables if needed)

public void OnTutorialSkipped()

OnTutorialCompleted​

This method should be called by the game when the user completes the tutorial and is ready to move to the next screen. Before calling this function make sure the game is ready for the Restart function call (Reset tutorial related UI or variables if needed).

public void OnTutorialCompleted()

Analytics​

SendBiEvent​

This method can be called from the game code to send analytics data. While populating the key value pair inside the BiEventUpdate object, use string constants defined in the BiHandler class only.

public static void SendBiEvent(BiEventUpdate eventUpdate)

Others​

The following methods should be overridden if the game supports pause functionality. For example, single player games must be paused. Usually multiplayer games like Sheep Fight, can’t be paused because it is not turn based. Turn based games may need to accommodate the pause when the user's turn is not active. This method can be called in the middle of the game or at the end of the game.

PauseGame​

This method is called by joyride code to pause the game if pausing is possible and the game is not paused.

public virtual void PauseGame()

ResumeGame​

This method is called by joyride code to resume the game if paused. This method can be called anytime in the middle of a game.

public virtual void ResumeGame()

MuteStatus​

This method is called by joyride code to mute/unmute game sound.

public virtual void MuteStatus(string muted)