Phune Gaming docs

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.

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

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

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

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

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

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

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

Handle messages from an opponent

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

Callback function

onPlayerMessage(messageDetails);

Parameters

Match end

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

Callback function

onMatchEnd(matchResult);

Parameters

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

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

Returns

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

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

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