Skip to content

Latest commit

 

History

History
927 lines (798 loc) · 20 KB

sdk-js.md

File metadata and controls

927 lines (798 loc) · 20 KB
Raw
layout title description
default
SDK for JavaScript
Build HTML5 games for the Phune Gaming platform

Before you start developing your game you need to install the JavaScript SDK.

Install

Download the Phune Gaming SDK directly from GitHub and unzip the contents of the dist folder into the JavaScript folder of your game (e.g. js folder).

Alternatively, if you use Bower, you can install the Phune Gaming JavaScript SDK from the command-line by running the command below from the root of your game folder:

bower install phune-gaming-sdk

Add the Phune Gaming SDK to your index.html file as below.

For direct download installation:

<script src="js/PG.min.js"></script>

For Bower installation:

<script src="bower_components/phune-gaming-sdk/dist/PG.min.js"></script>

You are now ready to start your game implementation. Please proceed to the Getting Started sub-section to find which callbacks your game needs to implement to process the messages sent by the platform or to the Public API sub-section to find out which methods you have available to send the game messages (e.g. moves) to the server.

{% markdown %} The [implementation of the game Tic-Tac-Toe](https://github.com/phune-gaming/pg-tic-tac-toe) is freely available on GitHub. {% endmarkdown %}

Getting Started

This section details the callbacks you must implement in your game to process the messages sent by the server.

Init

Initialize the JavaScript SDK by calling PG.init and defining the callback functions which will handle all matchmaking phases and the game events sent to your game by the platform.

Usage
PG.init(config);
Parameters
Param Type Details
{% markdown %} config {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} Object defining the callback functions. The object must provide the following properties:
  • onMatchPrepare – {function(player, opponent, deviceType)} – The game should build the user interface and get ready to start playing.
  • onGameLobby – {function(allowedTime)} – The game can now configure additional match details.
  • onMatchStart – {function(playerIdToPlayNext, timeToPlay)} – The match start confirmation. Only now is the player allowed to play the game.
  • onMoveValid – {function(playerIdWhoSentTheMove, playerIdToPlayNext, moveDetails, moveEvaluation, matchResult)} – Acknowledgment to a valid move.
  • onMoveInvalid – {function(playerIdToPlayNext, moveEvaluation)} – Acknowledgment to an invalid move sent by the current player.
  • onServerMessage – {function(playerIdWhoSentTheMessage, messageDetails, messageResult)} – A message from the server-side rules was received.
  • onPlayerMessage – {function(messageDetails)} – A message sent directly from another player was received.
  • onMatchEnd – {function(matchResult)} – Called by the platform when a match end event is received.
  • onKeyPress – {function(key)} – A keyboard or TV remote control key was pressed. {% endmarkdown %}

The detailed description for each callback is presented below.

Match prepare

During the match preparation phase, the game should build the user interface and get ready to start playing. It is provided with the details of the player, the opponent and the type of device on which the game is running (mobile or tv).

Callback function
onMatchPrepare(player, opponent, deviceType);
Parameters
Param Type Details
{% markdown %} player {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The current player details. {% endmarkdown %}
{% markdown %} opponent {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The opponent details. {% endmarkdown %}
{% markdown %} deviceType {% endmarkdown %} {% markdown %} `string` {% endmarkdown %} {% markdown %} Indicates the type of the device where the game is running. Possible values are `MOBILE` and `TV`. {% endmarkdown %}

Game lobby

If the game needs to configure the match details before it is started, the onGameLobby callback function will be called to allow it to do so. It is provided with the time allowed for the player to configure the game and start the match.

Callback function
onGameLobby(allowedTime);
Parameters
Param Type Details
{% markdown %} allowedTime {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} Time allowed for the player to configure the game and start the match. {% endmarkdown %}

Match start

When the match starts, the game will be informed of which player should play first and the time allowed for each player to make a move.

Callback function
onMatchStart(playerIdToPlayNext, timeToPlay);
Parameters
Param Type Details
{% markdown %} playerIdToPlayNext {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} The identifier of the player to whom the next move belongs. {% endmarkdown %}
{% markdown %} timeToPlay {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} Time allowed for the player to make a move. {% endmarkdown %}

Moves handling and validation

If a move is considered valid by the server-side rules, the server will respond with a confirmation message that will be handled by the onMoveValid callback function. Moves performed by the opponent will also be handled by this callback function. If a move ends the game, the matchResult parameter will indicate how the game ended.

Callback function
onMoveValid(playerIdWhoSentTheMove, playerIdToPlayNext, moveDetails,
    moveEvaluation, [matchResult]);
Parameters
Param Type Details
{% markdown %} playerIdWhoSentTheMove {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} The identifier of the player that sent the move. {% endmarkdown %}
{% markdown %} playerIdToPlayNext {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} The identifier of the player to whom the next move belongs. {% endmarkdown %}
{% markdown %} moveDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The move details. {% endmarkdown %}
{% markdown %} moveEvaluation {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The result of the move validation. {% endmarkdown %}
{% markdown %} matchResult _(optional)_ {% endmarkdown %} {% markdown %} `string` {% endmarkdown %} {% markdown %} If the move ended the match, this parameter returns the result. Possible values are `won`, `lost` or `draw`. {% endmarkdown %}

If a move does not pass the server-side rules validation, the game will be notified by the onMoveInvalid callback function.

Callback function
onMoveInvalid(playerIdToPlayNext, moveEvaluation);
Parameters
Param Type Details
{% markdown %} playerIdToPlayNext {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} The identifier of the player to whom the next move belongs. {% endmarkdown %}
{% markdown %} moveEvaluation {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The result of the move validation. {% endmarkdown %}

Handle messages from the server

Responses to messages sent to the server will be processed by the onServerMessage callback function.

Callback function
onServerMessage(playerIdWhoSentTheMessage, messageDetails, messageResult);
Parameters
Param Type Details
{% markdown %} playerIdWhoSentTheMessage {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} The identifier of the player that sent the message. {% endmarkdown %}
{% markdown %} messageDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} Message specific to a game and unknown to the platform. The developer is advised to have multiple message types with different bodies in order to achieve different goals. {% endmarkdown %}
{% markdown %} messageResult {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The result returned by the server-side rules. {% endmarkdown %}

Handle messages from an opponent

Messages sent by the opponent will be processed by the onPlayerMessage callback function.

Callback function
onPlayerMessage(messageDetails);
Parameters
Param Type Details
{% markdown %} messageDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} Message specific to a game and unknown to the platform. The developer is advised to have multiple message types with different bodies in order to achieve different goals. {% endmarkdown %}

Match end

When the game is over, the onMatchEnd callback function is called with the game result.

Callback function
onMatchEnd(matchResult);
Parameters
Param Type Details
{% markdown %} matchResult {% endmarkdown %} {% markdown %} `string` {% endmarkdown %} {% markdown %} The match result. Possible values are `won`, `lost` or `draw`. {% endmarkdown %}

TV remote control input handling

On TV environment, the onKeyPress callback handles the remote control keys that were pressed.'enter'.

Callback function
onKeyPress(key);
Parameters
Param Type Details
{% markdown %} key {% endmarkdown %} {% markdown %} `string` {% endmarkdown %} {% markdown %} The key that was pressed. Possible values are `left`, `right`, `up`, `down` or `enter`. {% endmarkdown %}

Public API

The Phune Gaming SDK provides an API which allows the game to send messages to the platform and to the server.

Match start

During the match preparation phase (onMatchPrepare callback) the game must inform the platform when it is ready to be shown to the user by calling PG.ready.

Usage
PG.ready();

Game lobby

If the game is configured on the server to require a configuration phase, the onGameLobby callback will be called to allow the game to send the required configuration back to the server by calling PG.sendMessageToServer. When the match is ready to start, the game must inform the platform by calling PG.exitGameLobby.

Usage
PG.exitGameLobby();

Show the platform menu

The game must include a visual component which allows the user to have access to the platform menu. In order to show the menu this component must call the function PG.showMenu.

Usage
PG.showMenu();

Perform a move

If it is the current player's turn, the game should allow the player to make a move and then send it to the platform. Optionally, you can specify a validate function that accepts the move object as a parameter and validates it before sending it to the server. This prevents additional round-trips to the server for invalid moves, thus making the game a lot more responsive.

Usage
PG.sendMove(moveDetails, [validate]);
Parameters
Param Type Details
{% markdown %} moveDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The move details. {% endmarkdown %}
{% markdown %} validate _(optional)_ {% endmarkdown %} {% markdown %} `function(moveDetails)` {% endmarkdown %} {% markdown %} Validates the move before sending it to server. {% endmarkdown %}
Returns
{% markdown %} `boolean` {% endmarkdown %} {% markdown %} `true` when the move is valid or when no validation function was provided, otherwise `false`. {% endmarkdown %}

Send messages to the server

It is possible to send messages to be evaluated by the server-side rules. You can specify if you want the response to be sent to both players or only to you. Additionally, you can indicate if you want the messages to be processed by the server-side rules in order of arrival or in parallel.

Usage
PG.sendMessageToServer(messageDetails, isAnswerPublic, [serializeRequest]);
Parameters
Param Type Details
{% markdown %} messageDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The content of the message to be sent. {% endmarkdown %}
{% markdown %} isAnswerPublic {% endmarkdown %} {% markdown %} `boolean` {% endmarkdown %} {% markdown %} Whether the reply from the server's rules should be sent to all players or not. {% endmarkdown %}
{% markdown %} serializeRequest _(optional)_ {% endmarkdown %} {% markdown %} `boolean` {% endmarkdown %} {% markdown %} Whether the messages should be processed in order of arrival or can be executed in parallel. {% endmarkdown %}

Send messages to the opponent

If the game requires to send messages to the opponent that should not be evaluated by the server-side rules, it can use this function. Optionally, you can specify if you do not want to allow more than one message to be sent within a specified time in milliseconds. In this case, if the function is called more than once during the specified interval, only the last message will be sent.

Usage
PG.sendMessageToPlayer(messageDetails, [sendTimeIntervalLimit]);
Parameters
Param Type Details
{% markdown %} messageDetails {% endmarkdown %} {% markdown %} `Object` {% endmarkdown %} {% markdown %} The content of the message to be sent. {% endmarkdown %}
{% markdown %} sendTimeIntervalLimit _(optional)_ {% endmarkdown %} {% markdown %} `number` {% endmarkdown %} {% markdown %} Do not allow sending more than one message within the specified time in milliseconds. If this function is called more than once during this interval only the last message will be sent. {% endmarkdown %}

What's next? Go to Server rules to find out how to do your game validations on the server.