npm_crafty documentation

Crafty —

A CraftyJS instance.

`define(label, callback)`

Discussion

Define code which will be executed on a specific Crafty network instance.
The label argument is used to determine if this code is to be run on this Crafty instance. Iff this instance's label starts with the given label, the callback is executed. This instance's label is specified on the client / server creation.

Parameters

`label`	the label this instance's label has to start with in order for the callback to be executed
`callback`	the callback to execute if this instance's label starts with the given label

Return Value

this Crafty instance for method chaining

Example

// create an entity on the Crafty instance, whose label contains "CLIENT"
Crafty.define("CLIENT", function() {
    Crafty.e("2D, DOM, Text")
          .attr({ x: 100, y: 100 })
          .text("Loading, please stand by."); 
});

`netBind(eventName, callback)`

Discussion

Binds to an event over the net. Other than that it is functionally the same as the default bind method. The events will be delivered to the Crafty instance(s) at the other end of the network.
If the event was triggered on the server instance, the event will be received on all client instances. If the event was triggered on a client instance, the event will be received on the server instance.

Parameters

`eventName`	the event name
`callback`	the callback to execute upon event receipt

Return Value

this Crafty instance for method chaining

Example

Crafty.netBind("GameOver", function(data) {
    console.log("Congratulations, you achieved " + data.score + " points!");
});

`netTrigger(eventName, eventObject, isVolatile)`

Discussion

Triggers an event over the net. Other than that it is functionally the same as the default trigger method. The events will be delivered to the Crafty instance(s) at the other end of the network.
If this is called on the server instance, triggers the event on all client instances. If this is called on the client instance, trigger the event on the server instance.
The isVolatile parameter specifies if the transmission should be guaranteed to be delivered to the other end or not. If set to true, the event can get lost over the network, but it increases the network performance (useful for transmitting events every frame, like position updates).

Parameters

`eventName`	the event name
`eventObject`	the event object
`isVolatile`	whether the event should be sent reliably or not; if set to `true` the event will not be sent reliably

Return Value

this Crafty instance for method chaining

Example

Crafty.netTrigger("GameOver", {score: 11});
Crafty.netTrigger("GameOver", {score: 11}, false); // equivalent to the above

`netUnbind(eventName, callback)`

Discussion

Unbinds from an event over the net. Other than that it is functionally the same as the default unbind method. The events will be delivered to the Crafty instance(s) at the other end of the network.
If the event was triggered on the server instance, the event will be received on all client instances. If the event was triggered on a client instance, the event will be received on the server instance.

Parameters

`eventName`	the event name
`callback`	the callback to execute upon event receipt

Return Value

this Crafty instance for method chaining

Example

var callback = function(data) {
    console.log("Congratulations, you achieved " + data.score + " points!");
};
Crafty.netBind("GameOver", callback);
Crafty.netUnbind("GameOver", callback);

Net —

A Crafty component that adds net capabilities to Crafty entities.
It is necessary to add it to all entities that require net capabilities.
It is necessary to set an unique entity name when adding the component, which will be used to route events to correct entities on the other end of the network.

e —

A CraftyJS entity.

`define(label, callback)`

Discussion

Define code which will be executed on a Crafty enity, depending on the Crafty instance it belongs to.
The label argument is used to determine if this code is to be run on this Crafty instance. Iff this instance's label starts with the given label, the callback is executed. This instance's label is specified on the client / server creation (see lib documentation).

Parameters

`label`	the label this instance's label has to start with in order for the callback to be executed
`callback`	the callback to execute if this instance's label starts with the given label

Return Value

this Crafty entity for method chaining

Example

// Example showing definition of a basic entity, which is extended depending on the label of the Crafty instance it belongs to.
//common features
Crafty.e("2D, Net")
      .setName("Player1")
      .attr({ x: x, y: y, w: w, h: h })
      //this will be defined on all CLIENTS (e.g. CLIENT1, CLIENT2, ...)
      .define("CLIENT", function() {
          this.addComponent("DOM, Color")
              .color('rgb(255,0,0)');
      })
      //this will defined on CLIENT1 only
      .define("CLIENT1", function() {
          this.addComponent("Keyboard")
              .netTrigger("KeyDown", ...);
      })
      //this will be defined on SERVER only
      .define("SERVER", function() {
          this.addComponent("Collision")
              .onHit("Component", ...)
      });

`netBind(eventName, callback)`

Discussion

Binds to an event over the net. Other than that it is functionally the same as the default bind method. The events are received at the Crafty entity with the same entity name as the triggering Crafty entity on the other end of the network.
If the event was triggered on a server entity, the event will be received on all client entities. If the event was triggered on a client entity, the event will be received on the server entity.

Parameters

`eventName`	the event name
`callback`	the callback to execute upon event receipt

Return Value

this Crafty entity for method chaining

Example

var ent = Crafty.e("Net")
                .setName("MyEntity")
                .netBind("Moved", function(data) {
                    this.x = data.x;
                    this.y = data.y;
                });

`netTrigger(eventName, eventObject, isVolatile)`

Discussion

Triggers an event over the net. Other than that it is functionally the same as the default trigger method. The events will be delivered to the Crafty entity with the same entity name on the other end of the network, thus specifying an unique logical name for each entity is highly recommended.
If this is called on a server entity, triggers the event on all client entities. If this is called on a client entity, triggers the event on the server entitiy.
The isVolatile parameter specifies if the transmission should be guaranteed to be delivered to the other end or not. If set to true, the event can get lost over the network, but it increases the network performance (useful for transmitting events every frame, like position updates).

Parameters

`eventName`	the event name
`eventObject`	the event object
`isVolatile`	whether the event should be sent reliably or not; if set to `true` the event will not be sent reliably

Return Value

this Crafty entity for method chaining

Example

var ent = Crafty.e("Net")
                .setName("MyEntity")
                .netTrigger("Moved", {x: this.x, y: this.y});

`netUnbind(eventName, callback)`

Discussion

Unbinds from an event over the net. Other than that it is functionally the same as the default unbind method. The events are received at the Crafty entity with the same entity name as the triggering Crafty entity on the other end of the network.
If the event was triggered on a server entity, the event will be received on all client entities. If the event was triggered on a client entity, the event will be received on the server entity.

Parameters

`eventName`	the event name
`callback`	the callback to execute upon event receipt

Return Value

this Crafty entity for method chaining

Example

var callback = function(data) {
    this.x = data.x;
    this.y = data.y;
};
var ent = Crafty.e("Net").setName("MyEntity");
ent.netBind("Moved", callback);
ent.netUnbind("Moved", callback);

Client —

The Client API.
Can be constructed with this constructor or by calling the default setup method. After construction, various methods are available for creating a crafty client instance with net features and for connecting these net features to socket.io.
Also offers a static method for automatic matchmaking.

`createInstance(label)`

Discussion

Construct a Crafty client instance with net features enabled.
The label is used to determine which code to execute.

Parameters

label the label to use for this client instance

Return Value

the newly created Crafty client instance with net features enabled

Example

var Client = require('npm_crafty')();
var Crafty = Client.createInstance("CLIENT");

`setServer(Crafty, socket)`

Discussion

Bind the server socket to the Crafty client instance. The Crafty net features will use this socket to communicate with the server.

Parameters

`Crafty`	the Crafty client instance to bind the socket to
`socket`	the socket or socket namespace to use for communication with server

Return Value

the Crafty instance for method chaining

Example

var Client = require('npm_crafty')();
var Crafty = Client.createInstance("CLIENT");
Client.setServer(Crafty, socket);

`setupDefault(immediateFN, connectFN, disconnectFN, serverAddress)` static

Discussion

Setup a default browser client, which will connect to the node server of the website automatically.
Each callback will be called at the appropriate times. Communication will be set to the default '/' namespace.

Parameters

`immediateFN`	will be called immediately once all libraries are loaded
`connectFN`	will be called when the client connects to the server
`disconnectFN`	will be called when the client disconnects from the server
`serverAddress`	the server address to connect to (auto-resolved usually and thus can be omitted usually) e.g. "http://localhost"

Return Value

- the ClientAPI object, which in addition to the available methods also contains the io property

Example

var Crafty;
var Client = require('npm_crafty').setupDefault( function () { //immediate callback
    Crafty = Client.createInstance("CLIENT");
}, function (socket) { //connect callback
    Client.setServer(Crafty, socket);
}, function (socket) { //disconnect callback
});

`unsetServer(Crafty, socket)`

Discussion

Unbind the server socket from the Crafty client instance. The Crafty net features will no longer use this socket to communicate with the server.

Parameters

`Crafty`	the Crafty client instance to unbind the socket from
`socket`	the socket or socket namespace to no longer use for communication with server

Return Value

the Crafty instance for method chaining

Example

var Client = require('npm_crafty')();
var Crafty = Client.createInstance("CLIENT");
Client.setServer(Crafty, socket);
Client.unsetServer(Crafty, socket);

Server —

The Server API.
Can be constructed with this constructor or by calling the default setup method. After construction, various methods are available for creating a crafty server instance with net features and for connecting these net features to socket.io.
Also offers a static method for automatic matchmaking.
The sockets parameter contains the Socket.IO namespace to use for all Crafty related data.

`addClient(Crafty, socket)`

Discussion

Add a client socket to the Crafty server instance. The Crafty net features will use this socket to communicate with the client.

Parameters

`Crafty`	the Crafty server instance to bind the socket to
`socket`	the socket to use for communication with a client

Return Value

the Crafty instance for method chaining

Example

var Server = require('npm_crafty')(io.sockets);
var Crafty = Server.createInstance("Room1");
Server.addClient(Crafty, socket);

`createInstance(room)`

Discussion

Construct a Crafty server instance with net features enabled.
Each server instance shall have an unique room name. Only client and server instances within the same room can talk to each other.
This method also set's the server instance's label to "SERVER".

Parameters

room the room to use for this server instance

Return Value

the newly created crafty client instance with net features enabled

Example

var Server = require('npm_crafty')(io.sockets);
var Crafty = Server.createInstance("Room1");

`removeClient(Crafty, socket)`

Discussion

Remove a client socket from the Crafty server instance. The Crafty net features will no longer use this socket to communicate with the client.

Parameters

`Crafty`	the Crafty server instance to unbind the socket from
`socket`	the socket to no longer use for communication with a client

Return Value

the Crafty instance for method chaining

Example

var Server = require('npm_crafty')(io.sockets);
var Crafty = Server.createInstance("Room1");
Server.addClient(Crafty, socket);
Server.removeClient(Crafty, socket);

`setupDefault(immediateFN, connectFN, disconnectFN, port)` static

Discussion

Setup a default node server, which will serve npm_crafty's required files (it will reply to GET requests).
Each callback will be called at the appropriate times. Communication will be set to the default '/' namespace.

Parameters

`immediateFN`	will be called immediately once all libraries are loaded
`connectFN`	will be called when a client connects to the server
`disconnectFN`	will be called when a client disconnects from the server
`port`	the port to use (defaults to `process.env.PORT`; falls back to standard HTTP port `80`)

Return Value

- the ServerAPI object, which in addition to the available methods also contains the app, server and io property

Example

var Crafty;
var Server = require('npm_crafty').setupDefault( function () { //immediate callback
    Crafty = Server.createInstance("Room1");
}, function (socket) { //connect callback
    Server.addClient(Crafty, socket);
}, function (socket) { //disconnect callback
});