Skip to main content

API reference

Thanks to modular architecture, our PlayPad can be easily swapped for a custom WebGL game hosting application. The custom solution has to satisfy the API described below.

Elympics SDK communicates with PlayPad (or its substitute) through so-called external communication interfaces described here.

The messaging protocol includes 3 types of communication possible between Elympics PlayPad SDK and PlayPad:

  • request-response messages: requests from SDK to be acted upon and answered by PlayPad,
  • void messages: one-way communication from SDK without a need for acknowledgement or response from PlayPad,
  • Web messages: one-way communication from PlayPad, being a result of some match status- or Web3-related event.

Request-response messages​

The communication flow is as follows: SDK -> PlayPad -> SDK.

Here, an action is requested by SDK. After PlayPad executes the action, it sends back an acknowledgement and return data (if applicable). Request-response pairs are identified by request type name and a ticket number.

The detailed structure of a generic request and response message is presented below:

class RequestMessage<T>
{
    int ticket;   // request number
    string type;  // request type
    T? payload;   // request arguments
}

The type field contains the request type name. Both in the request and response message, it is used to describe the request type. Possible type values are listed later on.

Each possible type is associated with a type of request payload (desribed above as a generic field payload of type T) and stringified response data (the response field). The response field stores untyped data as stringified JSON, allowing for its deserialization based on status and expected response type.

warning

Make sure the data sent back from your PlayPad implementation in the response field is stringified JSON and not a nested object.

Such a requirement is caused by the way responses are handled using built-in Unity JsonUtility tool.

The ticket field allows for matching responses with requests.

Finally, response status field indicates if the operation succeeded.

Possible type values (divided into categories)

Initialization

  • Handshake - initial exchange in which both the client and PlayPad identify themselves

General

  • GetPlayStatus - allows for checking the status of match preparations or making it progress
  • ShowPlayPadModal - causes a modal to be displayed; the response is sent when it gets closed

Features (available depending on the value of featuresAccess handshake field)

  • GetAuthentication - a request for Elympics authentication data (requiring the Authentication feature)
  • GetLeaderboard - a request for leaderboard data (requiring the Leaderboard feature)
  • GetTournament - a request for tournament details (requiring the Tournament feature)
  • GetUserHighScore - a request for current user's high score (requiring the HighScore feature)

GetAuthentication​

Retrieves the current user's authentication data. Requires the Authentication feature to be available.

There are several methods of authenticating players within Elympics. You can read about them in the related article.

class EmptyPayload
{ }

Any updates regarding authentication are to be reported to the SDK via AuthenticationUpdated Web messages.

GetLeaderboard​

Pulls the current leaderboard, i.e. a leaderboard associated with the currently selected tournament. Retrieves the leaderboard state. Requires the Leaderboard feature to be implemented.

If you want to use Elympics game services for handling leaderboards, check out how to query our API here.

class EmptyPayload
{ }

Any updates regarding leaderboards (entries being updated or another leaderboard being selected) are to be reported to the SDK via LeaderboardUpdated Web messages.

GetPlayStatus​

Retrieves the status of the match preparations along with a message to be displayed to the user (on the "Play" button). Depending on request arguments, it can be a read-only call (only checking the status) or it can push PlayPad to take action and try to advance the status automatically as far as possible.

struct CanPlayGameRequest
{
    bool autoResolve;  // should PlayPad try to automatically satisfy all remaining requirements for playing a game
}

The status field in the response payload indicates either that a match can be started (Play), there are still some actions required to complete the preparation (UserActionRequired), or a match cannot be started at all (Blocked). Starting a match can be blocked for example because the associated tournament has ended.

The labelMessage field provides more details. Example values include the following:

  • "Tournament ended",
  • "Play",
  • "Tournament not started",
  • "Not available",
  • "Tournament not found",
  • "Connect wallet to play",
  • "Enter",
  • "Connect account with wallet".

Any updates regarding match preparations are to be reported to the SDK via PlayStatusUpdated Web messages.

GetTournament​

Retrieves the details regarding the currently chosen tournament. Requires the Tournament feature.

If you want to use Elympics game services for setting up tournaments, check our API reference here.

class EmptyPayload
{ }

The type property of the prizePool field in the response specifies the prize currency. Currently supported currency types are: "Respect", "BaseETH", "ETH", "TON", "TVM", "TMX", "USDC", "USDT", "NIKO", "DOGS", and "NOT".

The ownerId field is either null for default tournaments provided by Elympics or it contains the ID of the player who created the tournament. It is not forbidden for the creator to take part in their own tournament.

Any updates regarding tournaments (current tournament details being updated or another tournament being selected) are to be reported to the SDK via TournamentUpdated Web messages.

GetUserHighScore​

Retrieves user's all-time high score. Requires the HighScore feature.

High score is not associated with any tournament, only with a specific game.

Elympics-provided high score service API is described here.

class EmptyPayload
{ }

Any updates regarding the high score are to be reported to the SDK via UserHighScoreUpdated Web messages.

Handshake​

In this message, client sends basic information about game version and SDK version.

PlayPad responds, specifying its capabilities as well as providing information about run conditions. This includes closest geographic region (ping wise), device type and environment type (debug/production, etc.).

struct HandshakeRequest
{
    string gameId;              // game ID
    string gameName;            // human-readable game name
    string versionName;         // human-readable game version number or name
    string sdkVersion;          // Elympics SDK version number
    string lobbyPackageVersion; // Elympics PlayPad SDK version number
}

Capabilities flags are set by the PlayPad implementation depending on authentication methods it offers.

FeaturesAccess flags are similarly set based on the list of game features made available by the PlayPad implementation.

The Authentication feature should always be implemented. Players have to be authenticated in order to access basic Elympics endpoints, including starting a match.

ShowPlayPadModal​

Causes a modal to be displayed. A response is expected to be received after the modal is closed. No more data should be included in the response.

If the modal name cannot be found (or it is a tournament modal, but the Tournament feature is missing), the "ModalUnavailable" error response (status 700) is to be returned.

struct ShowPlayPadModalRequest
{
    string modalName;  // e.g. "tournament/rewards", "tournaments/listing", or "game/tutorial"
}

Void messages​

So-called void messages are sent from SDK to PlayPad without a need for acknowledgement or return data. The structure of the message is described below:

class VoidMessage<T>
{
    string type;  // message type
    T? payload;   // message arguments
}

The type of each message is identified by the type field. The field value maps into the concrete type that is to be used in the place of the generic T type of the payload field.

Possible type values (divided into categories)

General

Logging

Forwards a log message from Elympics SDK along with its context.

note

Only messages coming from the SDK are forwarded. All other logs (coming from the game developer or external packages) are omitted.

struct BreadcrumbMessage
{
    LogLevel level;  // the category of the log message
    string message;  // log message
    MetaData data;   // context
}

enum LogLevel
{
    Log = 0,
    Warning = 1,
    Error = 2,
    Exception = 3,
}

struct MetaData
{
    string? sessionId;            // session ID
    string? app;                  // application name
    string? version;              // application version (SDK version)
    string? gameId;               // game ID
    string? userId;               // user's Elympics ID
    string? authType;             // authentication type: "None", "ClientSecret", "EthAddress", or "Telegram"
    string? nickName;             // user's nickname
    string? walletAddress;        // user's wallet address
    string? time;                 // timestamp of the log message (as ISO 8601 string)
    string? ip;                   // client IP (empty - to be filled in by PlayPad)
    string? fleetId;              // used fleet ID (empty - to be filled in by PlayPad)
    string? region;               // current region name
    string? lobbyUrl;             // URL used to connect to Elympics lobby
    string? roomId;               // current room ID
    string? queueName;            // the name of the queue used for starting current match
    string? matchId;              // current match ID
    string? tcpUdpServerAddress;  // the address of TCP/UDP interface of game server
    string? webServerAddress;     // the address of WebRTC interface of game server
    string? capabilities;         // "None" or a comma-separated list of supported authentication methods: "Guest", "Telegram", "Ethereum", "Ton"
    string? tournamentId;         // current tournament ID
    string? featureAccess;        // "None" or a comma-separated list of supported features: "Authentication", "Leaderboard", "Tournament", "HighScore"
    string? context;              // the name of the class responsible for emitting the log message
    string? methodName;           // the name of the method responsible for emitting the log message
}

ElympicsStateUpdated​

Notifies about the status of the game being changed. There are 5 statuses available: from client being completely disconnected from Elympics services to a match being currently played.

struct ElympicsStateUpdatedMessage
{
    ElympicsState previousState;  // previous status
    ElympicsState newState;       // current status
}

enum ElympicsState
{
    Disconnected = 0,
    Connecting = 1,
    Connected = 2,
    Matchmaking = 3,
    PlayingMatch = 4,
}

HideSplashScreen​

Reports that the game has finished loading. Used to hide the splash screen if it is still visible. No payload is required. If the splash screen has already disappeared, the message has no effect.

struct EmptyPayload
{ }

NetworkStatusMessage​

Provides statistics regarding the round-trip time on each game tick. Is sent perodically (in batches).

struct NetworkStatusMessage
{
    string matchId;      // match ID
    RttReceived[] data;  // a series of RTT measurements
}

struct RttReceived
{
	float rtt;  // in miliseconds
	long tick;  // game tick number
}

SystemInfoData​

Diagnostic information regarding user hardware sent just after a match starts.

struct SystemInfoDataMessage
{
    string userId;                  // user's Elympics ID
    string matchId;                 // started match ID
    SystemInfoData systemInfoData;  // user's hardware profile
}

// see: https://docs.unity3d.com/2021.3/Documentation/ScriptReference/SystemInfo.html
struct SystemInfoData
{
    int systemMemorySize;          // RAM size (in MB)
    string operatingSystemFamily;  // OS family name: "Other", "MacOSX", "Windows", or "Linux"
    string operatingSystem;        // OS name with version
    int graphicsMemorySize;        // VRAM size (in MB)
    string graphicsDeviceVersion;  // graphics API type and driver version
    int graphicsDeviceVendorID;    // GPU PCI vendor ID
    string graphicsDeviceVendor;   // GPU vendor name
    string graphicsDeviceName;     // GPU model name
    int graphicsDeviceID;          // GPU PCI device ID
}

Web messages​

Web messages are emitted by PlayPad. Targetting SDK, they require no response from it.

class WebMessage
{
    string type;      // message type
    string? message;  // message data as stringified JSON
}

The message field, being stringified JSON, is deserialized into an object in correspondence with the type identified by the type field.

warning

As in the case of request-response messages, the data sent by a PlayPad implementation in the message field is stringified JSON and not a nested object.

Possible type values (divided into categories)

General

Features (available depending on the value of featuresAccess handshake field)

AuthenticationUpdated​

Notifies SDK that authentication data has been updated. Only sent if PlayPad offers the Authentication feature.

struct AuthenticationUpdatedMessage
{
    string jwt;       // JSON Web Token storing authentication data
    string userId;    // Globally Unique Identifier of the current user
    string nickname;  // current user's nickname
}

For more information, check the description of the request-response version of this message.

LeaderboardUpdated​

Notifies SDK that leaderbord data has been updated. This can include the entries of the current leaderboard being updated or another leaderboard being set as the current one. Only sent if PlayPad offers the Leaderboard feature.

struct LeaderboardUpdatedMessage
{
    Entry[] entries;   // all leaderboard entries
    Entry? userEntry;  // entry related to the current user
    int participants;  // total number of users in the leaderboard
}

struct Entry
{
    string userId;        // Globally Unique Identifier of a user
    string nickname;      // nickname of a user
    int position;         // 1-based leaderboard index of the entry
    float score;          // points scored by a user
    string scoredAt;      // the timestamp when the associated match ended (as ISO 8601 string)
    string matchId;       // Globally Unique Identifier of a match
    string tournamentId;  // ID of the associated tournament
}

For more information, check the description of the request-response version of this message.

PlayStatusUpdated​

Notifies SDK that match preparations have progressed. For example, a required Ethereum transaction may have been detected having been performed by the player.

struct CanPlayUpdatedMessage
{
    string status;        // "Play", "UserActionRequired", or "Blocked"
    string labelMessage;  // a human-readable message to be displayed on the "Play" button
}

For more information, check the description of the request-response version of this message.

RegionUpdated​

Reports another region of the game server being selected.

struct RegionUpdatedMessage
{
    string region;  // chosen Elympics game server region name
}

TournamentUpdated​

Sent when the current tournament is switched or it updates. Only sent if PlayPad offers the Tournament feature.

struct TournamentUpdatedMessage
{
    string id;                    // ID of the tournament
    int leaderboardCapacity;      // number of rewarded players: 1, 3, or 10 (solo, podium, or top 10 respectively)
    string name;                  // a human-readable name of the tournament
    PrizePoolResponse prizePool;  // reward specifics
    string ownerId;               // Globally Unique Identifier of the creator of the tournament, can be null (which means it's a built-in one)
    string startDate;             // the timestamp when the tournament starts (as ISO 8601 string)
    string endDate;               // the timestamp when the atournament ends (as ISO 8601 string)
    bool isDefault;               // is the current tournament the default built-in one? (daily tournament)
}

struct PrizePoolMessage
{
    string type;         // e.g. "Respect", "ETH", "TON", "USDC"
    string displayName;  // human-readable name of the currency
    string? image;       // base64-encoded image representing the currency (optional)
    float amount;        // the amount of currency to be won
    string description;  // prize description
}

For more information, check the description of the request-response version of this message.

UserHighScoreUpdated​

Notifies SDK about player setting a new high score. This message is only sent if PlayPad offers the HighScore feature.

struct UserHighScoreUpdatedMessage
{
    string points;   // maximum number of points scored by the current user (as string)
    string endedAt;  // the timestamp when the associated match ended (as ISO 8601 string)
}

For more information, check the description of the request-response version of this message.

WebGLKeyboardInputControl​

Requests the game application to release or re-take control over the keyboard input.

The main use case is when a PlayPad implementation displays a text field to be filled by the player. By default, it is impossible as launched game application captures all keyboard input (see the official Unity docs). Making the application release the keyboard input allows the player to fill the field.

struct WebGLKeyboardInputControlMessage
{
    bool isKeyboardControlRequested;  // should the keyboard input be released by the game application?
}