GettingStarted

Greg edited this page Nov 26, 2013 · 23 revisions

What is Cloak?

Cloak is a library for writing networked HTML5 games using Node.js. By "networked" I mean they are either server-validated single-player games, or they are multiplayer games. Cloak provides a variety of systems that are useful for networked games, such as:

  • Automatic user identification and reconnection
  • Lobby system
  • Room system
  • Timers that compensate for network latency

How does it work?

Your game will have a client and a server. The client is a HTML5 and JavaScript web application. It can have its own backend, or it can be served as static files by a standard web server such as Apache or Nginx. The client will use the Cloak client library. The server is a Node.js application. The server will use the Cloak server library.

Diagram

If you are familiar with Socket.io this may look familiar. You can think of Cloak as a game-specific version of Socket.io with extra sugar. It currently uses Socket.io as a dependency, but in the future we might support other network libraries.

Example app

If you would rather learn by taking an existing app and looking under the hood, check out the chat example

Creating the server

To start making a game using Cloak, make sure you have the following software already installed:

First, create a directory for your server and add package.json and server.js files. A good starting package.json looks like this:

{
  "name": "MyCoolGame"
}

Before writing your server code, install the Cloak NPM module. Type npm install cloak --save. The --save flag will add it to your package.json as a dependency. Later on you can use npm install to install all dependencies listed in the package.json.

Now you can create your server.js. Use this as a starting point:

var cloak = require('cloak');

cloak.configure({
  port: 8090
});

cloak.run();

That is all you need to do to write a simple Cloak server. It just doesn't do much yet.

To run the server, type node server.js in this directory.

Creating the client

In another directory start making a client. There are plenty of different ways to do this. Bare minimum, create an index.html that includes the cloak client JavaScript, as well as Underscore and Socket.io See the example if you need help with this. In your own JavaScript, you can connect to the Cloak server like this:

cloak.configure({
  // You'll add stuff here later.
});

cloak.run('http://localhost:8090');

If you run this while the Cloak server is running, it'll connect!

Sending messages

The main thing you'll want to do is send messages between the client and server.

In the server config you can create a messages section, like this:

// On the server
cloak.configure({
  ...
  messages: {
    myMessage: function(arg, user) {
      console.log('message from client received!');
    }
  }
  ...
});

This event handler is called when cloak.message('myMessage') is called on the client.

Similarly, you can add a messages section to the client configuration:

// On the client
cloak.configure({
  ..
  messages: {
    differentMessage: function(arg) {
      console.log('server said: ' + arg);
    }
  }
  ..
});

On the server you can't just call cloak.message to respond. You can call cloak.messageAll('differentMessage', 'hello everyone!'), or if you have a reference to a specific user object you can call user.message('differentMessage', 'hello client!')

Learning more

Hopefully that gets you on your feet. The next step is to learn more from the documentation. If you have any questions you just can't figure out, open a bug and label it as a question. I hope Cloak helps you make awesome games!