Quartz Socket

Quartz Socket is a WebSocket implementation for games made for Gembly. Develops can use this to create their own games so that they can be implemented with the Game Logic running on a NodeJS server.

This socket implementation is backwards compatible with browser that have no WebSocket support with the use of a swf.

Key Features:

• Allows your game to work on Gembly
• Allows your game to work on Zigiz
• Works with IE9

Getting Started

First you'd want to include the library in your page by doing the following:

    <script src="path/to/your/external/libs/quartz-socket.min.js"></script>

Required variables

The following variables are important at some part of the game

var config = {
    baseUrl: '/' (The location of the assets to load)
}

Connecting and setting up the event handlers

Next up is setting up a socket connection, the socket self already reads the server and port properties from the config. The only thing you should do is add a game object. This game object is where all the logic should be located and all the game moves should be verified. But thats for later.

Setting the up the socket goes something like this:

var socket = Quartz.Socket.getInstance(
    new GameLogic(),    //(Required) Logic of the game
    offline,            //(boolean, default false) if we play with or without server
    shortGame,          //(boolean, default false) if we play short games or not (gembly only)
    gametime            //(number|boolean, default 300) the amount of time we want to play, set to false to play without time
);

That was easy! But now we have to set up the event handlers. There are 2 main events that should be used, e.g: data and connect.

//Data handler
socket.on('data', function (data) {
    console.log(data);
});
//connect handler
socket.on('connect', function () {
    //Do something to show we connected
});
//connect!
socket.connect(
    'localhost',    //(Required) The addres of the server
    8123,           //(Required) The port we connect to
    secure          //(boolean, default true) If we connect securely or not
);

Setting up a new Session

Sessions are Important, each request you send to the server require the Session. It contains information about the user and his game that need to be known by the server.

Using the config object we can create a new Session like this:

var session = Quartz.Session.getInstance(
    4001,
    config.uuId,
    config.practice,
    config.loggedIn
);

Now you don't have to worry about session anymore, apart from sending them to the server, but we'll cover that later ;)

Usage

Sending a request

Next up is sending some data to the server, for this we have a nice request class in which you can do some magic. The request class always requires a string (the command we want to send) and a session.

There is also room for an optional data object if you want to send something like coordinates to the server, or dice values ;)

//lets create a nice request, telling the server we clicked a die
var request = new Quartz.Request('select',  Quartz.Session.getInstance(), {
    dieId: 4
});

The data object can contain anything you like as long as it is a valid javascript Object. The command is dependend on your own game logic. There are a few generic commands like:

• init
• start
• quit

Init is send to signal we are loading a game.The response of an init should always contain enough info the create the game field Start is usually send after all opening animations are done, and we are ready to play. No response is returned for a start. Quit is only used when a user wants to quit a game.

Getting a response

After each request (except start) a response is returned from either the server, or the local game logic. This response is always an Quartz.Response object. It has 2 public methods, get and set. Which can do what they are named after :P.

A response should have a couple of default properties which give you some meta information about the game

• gameover (if the game has ended)
• time (time left to finish the game)
• call (the command the response was returned for)
• score (current score for this game)

socket.on('data', function (data) {
    if (data.get('call') === 'select') {
        //do some work regarding the response of the select
    }

    if (data.get('gameover') === true) {
        //end the game, show closing animation
    }
});

example flow

Due to having some default commands like init and start there is a certain flow that needs to be followed in order to correctly start game. This can be achieved by doing the following:

var socket = Quartz.Socket.getInstance(new GameLogic());
socket.on('data', function (data) {
    if (data.get('call') === 'init') {
        //init received, and we are done with animations. lets send start
        socket.send(new Quartz.Request('start', Quartz.Session.getInstance()));
    }

    if (data.get('call') === 'bank') {
        //current dice are banked, lets update the scores
        scoreLabel.setText(data.get('score'));
    }
});
//connect handler
socket.on('connect', function () {
    //We connected, so lets send the init command
    socket.send(new Quartz.Request('init', Quartz.Session.getInstance()));
});
//connect!
socket.connect();


bankButton.onClick(function () {
    socket.send(new Quartz.Request('bank', Quartz.Session.getInstance()));
});

Requirements for a Game

So the game we pass to the socket instance, does need to have some properties, and some methods in order to integrate nicely.

The game needs to have 2 functions:

• handleGameMove
• generateResponse

handleGameMove will have a dataobject as its first parameter that contains the request send by the frontend. This method will handle the game move that is passed and should always respond with an object that represents the games current state.

The generateResponse function is sometimes called externally by the server and should always be able to respond with the games current state. In essence it will return the same object as in the handleGameMove but then without any logic handled.

The required properties for a game object are:

• gameover (if the game is gameover or not)
• success (if the move was done successfully, invalid moves return success:false)
• isPlaying (if the user is playing the game)
• score (the current score of the user

How to build

Quarts Socket is built with Grunt. If you don't already have Node.js and NPM, go install them. Once you do, then install Grunt.

$> npm install -g grunt-cli

Then, in the folder where you have downloaded the source, install the build dependencies using npm:

$> npm install

Then, to build the source, run:

$> grunt prod

This will create a minified version at bin/Quartz/Socket-.min.js and a non-minified version at the same location.

There is also a watcher available if you want to work on the sources, this can be simply run with:

$> grunt watch

Run tests

First make sure everything is installed, but lets asume you've done so. All you need to do now is run the following:

$> npm test

voila!

Disclaimer

We at OrangeGames just love playing and creating awesome games. We needed some awesome socket connections in our awesome HTML5 games. Feel free to use it for enhancing your own awesome games!

Quartz Socket is distributed under the GPLv3 license. All 3rd party libraries and components are distributed under their respective license terms.