Tutorials/helloworldJsClientJavaScriptTutorialClient

= JavaScript API Tutorial - Client =

Before we Start
Before you start, make sure you have a Firebase server up and running. If not, please follow the server part first and then come back here.

For the Impatient
If you are impatient or just want to see the finished product, you can go straight here and check the source code. Note that the server has to be up and running on your machine for this to work!

Getting Started
Start by creating an empty HTML file. In the HEAD tag, add these two scripts:

 

Connecting
The key component in the JavaScript API is called the. To create a connector, you will need to pass in callback functions for packets, lobby packets, logins and status updates. Here's an example with empty callback functions:

connector = new FIREBASE.Connector(packetCallback, lobbyCallback, loginCallback, statusCallback); function lobbyCallback(lobbyPacket) { }

function packetCallback(packet) { }

function loginCallback(status, playerId, name) { }

function statusCallback(status) { console.log("Status received: " + status); } Then, you call the  function to connect to Firebase:

connector.connect("FIREBASE.WebSocketAdapter", 'localhost', '8080', "socket");

The first parameter says that we want to use web sockets. If you want to target non HTML 5 compliant browsers, we also offer support for CometD, which will be covered in another tutorial. The second and third parameters specify the host and the port where Firebase is listening, 8080 is the default port. The last parameter is only important if you are using CometD.

Try it Out
Run this in Chrome (or any browser that supports web sockets) and open the | JavaScript console. You should see: Status received: 1 Status received: 2 1 means connecting and 2 means connected. If your client does not manage to connect to Firebase, it will try to reconnect, which you will see in the logs.

Logging in
Now, we have successfully connected our client to Firebase. The next step is to log in so that we can start playing. Logging in is a simple matter of calling: . If the login is successful, you'll get a callback to the  function with a status param that is "OK".

To try this out, please head over to TODO. It assumes that you have a Firebase started on your localhost. You username can be anything but the password has to be a number. This is just how the default login handler works, it will use the password as your userId.

Requesting the Lobby List
In order for the player to find a suitable game to play, we need some kind of lobby. To keep things easy, we will just create a list of all available tables. In a real client, you may of course design the lobby in a completely different way, if you have a visible lobby at all. To get a list of available tables, send a subscription request with the gameId you chose when you created your server side logic, like so: The slash means that you want the entire tree of tables, starting from the root. It is possible to partition the lobby into sub nodes when it starts to grow. Firebase will respond with a list of all tables and the API will invoke your  function with a. Check the | protocol documentation here.

In this tutorial (link), we are using jQuery to construct a grid that shows all the tables. Check the source code and follow the link to  to see the code.

Joining a Game
When a player chooses to join a specific game, you call the  function. If you don't care which seat you get, just pass -1. If all goes well, you will get a  via the packetCallback function with an OK status. You will also receive s for all seated players. Again, see the protocol documentation for more information.

Sending an Action
Now we are ready to send our first game action! The JavaScript API provides three methods for doing this:


 * sendStringGameData
 * sendBinaryGameData
 * sendStyxGameData

To keep it simple we will be using the first method in this tutorial. However, for better efficiency and speed we recommend using a binary protocol instead, which the second function helps you with. The last function will send a packet that has been generated by the Styx tool (link), which is a tool for generating a binary protocol from an XML definition.

In this case, all we need to do to shoot a message to the server is: The first parameter is playerId, but can be ignored because Firebase will use the playerId you are logged in as (to avoid cheating). The second parameter is the tableId you are playing at and the third is the text you want to send.

The  method will first create a byte array from the string and then base 64 encode this byte array, before sending it to Firebase. The reason for the base 64 encoding is that this is currently recommended when transferring binary data over a WebSocket.

Receiving Data
The way we have written the  method on the server side, all it will do is echo the incoming message to all players. This means that the player (and any other player at this table) will receive a  via the   function. To parse the data, we need to first base 64 decode the contents, and then convert it from binary to a string. Like so: function handleGameTransport(packet) { // We need to first base64 decode the message. var byteArray = FIREBASE.ByteArray.fromBase64String(packet.gamedata); // And then convert the byte array to a string. var message = utf8.fromByteArray(byteArray); gameMessage("Player " + packet.pid + " sent: " + message); } Here's a screenshot of the client, showing an incoming message: