Unity

How to integrate the Unity plugin.

You can use this plugin for Mobile Unity games - we support Android and iOS

Connecting plugin to your project.

Just download and put the EscsUnityPlugin plugin folder from

escs-unity-plugin git repo - v0.11.1

into your Assets/Plugins folder. Basically that's it. However, there are some considerations for each mobile platform

Android

Because Android build system heavily relies on package dependency management and Unity does't really support it out of the box, we need 3rd party dependency managements solution added. If you are working on a big project, chances are that you are already use it, otherwise please import following package:

This is officially supported by google package manager for Unity. Just download latest .unitypackage file from the repository and drag and drop it into your assets folder, it will automatically install itself. We recommend you to allow it to automatically resolve dependencies, otherwise you can do it manually from the Assets menu (after installing aforementioned package):

iOS

For iOS you need to use the same dependency resolver package as for Android, it will generate pods project. Be aware that we use use_frameworks! param in resulting pod file. However you can live without the resolver if you put required dependency manually. Internally the Escs Plugin uses SDWebImageWebPCoder (https://github.com/SDWebImage/SDWebImageWebPCoder) which in turn uses SDWebImage, so you need to manually link those libraries if you don't want to use pods and dependency resolver.

There is another catch, which is running your project in simulator. If you want to be able to do that, you will need Escs Unity binaries built for simulator image (x86_64 instead of armv7/arm64). To do that, simply overwrite the folder EscsUnityPlugin\iOS\EscsIosUnityPlugin\EscsIosPluginFramework.framework with contents of Release-iphonesimulator directory from our repo.

Integrating plugin into your game.

It is very easy to integrate ESCS plugin into your game code

First you need to initialize your plugin.

Initialization

To start using your plugin you need first initialize it:

EscsUnityPlugin.Invoke(
string public_key,
string base_url,
string player_base_url,
InvokeDelegate onEscsInit);

where:

  • public_key- a key that you've obtained in the step 1 of the integration guide, like "fee91a27-2b87-45f8-8ca4-0b317707806q"

  • base_url - url for the core ESCS service. It is https://api.escs.io for production environment

  • player_base_url - url for the player's ESCS service. It is https://player.escs.io for production environment

  • onEscsInit- callback delegate when init is completed; you can omit it.

Delegate method signature is following:

public delegate void InvokeDelegate (string status, string gameId, string tournamentId);

where:

  • status - string "initialized" for fully initialized escs, or some error message, or empty string

  • gameId - gameId of configured game or empty string

  • tournamentId - tournamentId of current active tournament or empty string

Start/End Game

After that you are all set and ready to use ESCS functionality. To start a game's round, just call StartGame() method:

EscsUnityPlugin.StartGame(StartGameDelegate onStartGame);

where

  • onStartGame - callback delegate when startGame has obtained round info (you can omit it) with following signature:

public delegate void StartGameDelegate (string roundId, string tournamentId, string status, string playerId);

where:

  • roundId - roundId of just started game round

  • tournamentId- tournamentId of active tournament for which the round was created for

  • status- round status. "active" for just created round

  • playerId- escs playerId

When the round of your game has ended, just call EndGame() with score parameter:

EscsUnityPlugin.EndGame(double score, EndGameDelegate onEndGame);

where

  • score - game score parameter of double type

  • onEndGame - callback delegate when startGame has obtained round info (you can omit it) with following signature:

public delegate void EndGameDelegate (string roundId, string tournamentId, string status, string playerId);

where:

  • roundId - roundId of just ended game round

  • tournamentId- tournamentId of active tournament for which the round was ended

  • status- round status. "ended" for just ended round

  • playerId- escs playerId

Optional steps

Hiding ESCS button

Most of the time you will not want to show the ESCS button during the actual game, to not mess with the gameplay, for example user can accidentally touch it and almost full-screen webview will show up. To hide or show button you can use following methods:

EscsUnityPlugin.HideEscsButton();
EscsUnityPlugin.ShowEscsButton();

Notifications/Announcements

There are situations, when ESCS needs to show announcements or notifications - for example to promote your game's upcoming championship, or ask user to add credit card, because his/her trial is about to expire. ESCS will open its full WebView automatically to show notification's content, if it's needed. To be able to show these, not interrupting your gameplay and at the times that are not interruptive for user, please call these methods:

EscsUnityPlugin.MaybeShowNotifications();
EscsUnityPlugin.MaybeShowAnnouncements();

There's internal logic in the plugin to decide whether it needs to show actual notification and announcement, but you should place these calls whenever you feel that interruption with ESCS WebView window is okay for user experience.

Please note that it does not mean that user will see notification or announcement every time you call these methods. We are trying for those to be as subtle and fluent as possible for end user. Their names imply that notification/announcement just maybe will be shown.

Changing default button position

There are situations when it is not suitable for your UI to have our ESCS button at default top center area. Then you can change that (remember, that user actually can drag the button anywhere on the screen he wants)

SetButtonDefaultPositionAbsolute() will set button position in absolute coordinates from left upper corner of the app.

EscsUnityPlugin.SetButtonDefaultPositionAbsolute(float x, float y);

where

  • x - x coordinate

  • y - y coordinate

SetButtonDefaultPositionRelative() will set button position in relative coordinates from center horizontally and top vertically of the app. That is, if you set 0, 0 coordinates the button will be shown in the x: (device width)/2 y: 0.

The coordinate system here is from -0.5 to 0.5 for xPart : where -0.5 means most left side of device and 0.5 - right side and 0 is dead center. For yPart it is from 0 to 1 where 0 is top of the screen and 1 is the bottom.

EscsUnityPlugin.SetButtonDefaultPositionRelative(float xPart, float yPart);

Getting in-game rewards

To receive the list of in-game rewards that particular player has (you can set those rewards as string fields in your game dashboard - for winning matches and so on) you can use the following method:

EscsAndroidUnityPlugin.GetIngameRewards(onGetRewards);
//...
public void onGetRewards(EscsIngameRewards rewards) {
Debug.Log("onGetRewards callback");
foreach(EscsRewardPayload p in rewards.data) {
Debug.Log(p.rewardData);
}
}

where:

  • onGetRewards- callback delegate when GetIngameRewards has rewards info, with following signature:

public delegate void EscsGetIngameRewardsDelegate (EscsIngameRewards rewards);

where: EscsIngameRewards is object with follwing fields:

  • int count - amount of rewards

  • EscsRewardPayload[] data - array of EscsRewardPayload objects, which contain:

    • string id - id of the reward

    • string rewardData - reward data - the string that you set in the game dashboard

    • string tournamentId - tournament id where the reward was obtained

Multiplayer

Overview

We support multiplayer games with different types of matches, matchmaking and so on. To be able to use this feature, you need to follow these steps:

  • Create multiplayer tournament in the game dashboard

  • Implement several callbacks in you game, which will be called in response to player's engagement with multiplayer tournament

Currently we provide 4 such callbacks:

  • OnGameSetStart callback - is called when a game set is started by escs backend. This is moment when you should start your game or create lobby and await for players to join it. What is a "set"? It's just one multiplayer game that several players are playing simultaneously. It can be real multiplayer (e.g. they, for example, race each other on track in a racing game or are participating in a deathmatch 1vs1 or 2vs2 and so on), or even "singleplayer", meaning that they all play their own singleplayer game (like solving puzzles and the one who solves it faster is the winner). In this callback you will receive information about players that are playing this set, teams that players are in (i.e. 2vs2 game), metadata that is supplied with the player (supplied by registerInGamePlayerId) and global metadata that is set in the game dashboard

  • OnGameSetEnd callback - is called when each player in the set has finished their game. this might be not necessary the same moment you end your multiplayer game - it is called when the escs backend processed all game end events from each participating player and saved their corresponding scores. You will receive matchId and setId as parameters

  • OnMatchStart callback - is called when multiplayer match has started. Usually you will get this event right before getting OnGameSetStart. Each match consists of several game sets. You will receive matchId as parameter of this callback.

  • OnMatchEnd callback - is called when multiplayer match has ended. That is when all the sets in the match has been played or timeout occurred. You will receive matchId as parameter of this callback

The following diagram may be helpful for understanding about aforementioned events:

To utilize these events you should call following methods after initializing escs service:

Registering in-game player id and metadata:

EscsAndroidUnityPlugin.RegisterIngamePlayerId(playerId, ingameMetadata);

where:

  • playerId - your ingame player id (string). It will be passed along with OnGameSetStart callback when the game set will start

  • ingameMetadata - your ingame metadata for this player (string)

Register OnGameSetStart event callback

EscsAndroidUnityPlugin.SetGameSetStartCallback(onSetStart);
//...
public void onSetStart(EscsSetStartPayload p) {
Debug.Log("set started - players: ");
foreach(EscsTeam team in p.teams) {
Debug.Log("team: ");
foreach(EscsParticipant particip in team.members) {
Debug.Log(particip.username);
}
}
}

where EscsSetStartPayload contains:

  • setId - setId of started set (string)

  • tournamentId - tournamentId of the set (string)

  • matchId - matchId of the set (string)

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

  • globalMetadata - metadata string that can be set in the game dashboard (string)

  • teams - array of EscsTeam objects. Each EscsTeam has array of EscsParticipant, which in turn contains:

    • 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)

    • avatar - user's escs avatar image url (string)

    • ingameMetadata - in-game metadata that was registered via RegisterInGamePlayerId (string)

    Thus, when playing, for example, 2vs2 game mode, you will have 2 EscsTeam objects in teams array, each containing 2 EscsParticipant. If playing 1vs1, then you will have 2 EscsTeam objects each holding just 1 EscsParticipant, i.e. 2 teams with 1 player only for each.

Register OnGameSetEnd event callback

EscsAndroidUnityPlugin.SetGameSetEndCallback(onSetEnd);
// ...
public void onSetEnd(string setId, string matchId) {
Dedug.Log("set ended: " + setId + "\n of match: " + matchId);
}

where:

  • setId - setId of finished set (string)

  • matchId - matchId of the set (string)

Register OnMatchStart event callback

EscsAndroidUnityPlugin.SetMatchStartCallback (onMatchStart);
// ...
public void onMatchStart(string matchId) {
Dedug.Log("match started: " + matchId);
}

where:

  • where matchId - is matchId of the match that started (string)

Register OnMatchEnd event callback

EscsAndroidUnityPlugin.SetMatchEndCallback (onMatchEnd);
// ...
public void onMatchEnd(string matchId) {
Dedug.Log("match ended: " + matchId);
}

where:

  • where matchId - is matchId of the match that has ended (string)