<commit_before># nodeGame User Guide

- status: incomplete

## Disclaimer

nodeGame is under active development and new features are constantly added. We do our best to keep this documentation up to date, but it may happen that the software still behave slightly differently than what herein documented. We apologize for this, and kindly ask you to report any gap between this documentation and the actual software behavior.

## Who should read this

This guide covers the basic functionalities of the framework, and offers a broad picture of nodeGame to the beginner. For detailed documentation, API, and format specification please read the other files in the doc directory of this repository.   

## Introduction

nodeGame is a free, open source, event-driven Javascript framework for on line, multiplayer games in the browser. It is specially designed to run social science experiments, for studying both individual choices and collective behavior. However, its architecture is general enough to run any type of game. 

### Targeted audience

nodeGame is designed to be as user-friendly as possible, but not more. This means that with little programming skills is already possible to create complex multiplayer games. On the other hand, minimal programming skills are indeed required. This obviously entails also some knowledge of Javascript, the programming language of the browser. For beginner guides about Javascript you can look into:

- [A beginner tutorial](http://www.w3schools.com/js/)
- [An advanced (not free) book](http://www.amazon.com/JavaScript-Good-Parts-Douglas-Crockford/dp/0596517742)

If you are familiar enough with Javascript you can proceed to the next section, and learn how to setup the nodeGame server, how clients can connect to it, and how to write games for nodeGame.

## Installation and Quick start

See [README](https://github.com/nodeGame/nodegame/blob/master/README.md) at the top of this root directory. 

## Understanding nodeGame

In order to run and conduct a game on nodeGame, you will need to:

  1. [setup the server](#setting-up-the-server)
  2. [create a game](#creating-a-game)
  3. [connect to the server](#connecting-to-the-server)


### Setting up the server

The launcher file starts the nodeGame server.

```js
    var ServerNode = require('nodegame-server').ServerNode;
    
    // Options can be specified as input parameter
    var sn = new ServerNode();
    
    sn.addChannel({
        name: 'Ultimatum',
        admin: 'ultimatum/admin',
        player: 'ultimatum',
        game: 'ultimatum',          
    });
```

In the above example:

- the `require` directive import the nodegame-server module;
- a `ServerNode` object with a given name is created listening on port 8080 (by default) 
- a _channel_ is added to the server; a channel binds a route to a specific game. It contains two end-points: for users and administrators.

The `ServerNode` object accepts a configuration object as input parameter. Moreover, it is possible to write separate configuration files for different features of the server. For a detailed documentation on how to configure the nodeGame server read [this guide](https://github.com/nodeGame/nodeGame/blob/master/doc/configure-nodegame-server.md)

### Creating a game

TODO...

### Connecting to the server

Now that the server is running, and the game was created, we need to point our browsers to the  

```html
    <!doctype html>
    <title>nodeClient Example</title>
    <body>
    <script src="/socket.io/socket.io.js"></script> 
    <script src="/javascript/nodegame.js" charset="utf-8"></script>
    <script src="Ultimatum.js" charset="utf-8"></script>
    <script>
      window.onload = function(){
        var conf = {
          player: {
            name: 'Player_1',
          }
          url: '/ultimatum'
        };
        node.play(conf, new Ultimatum());
      }
   </script>
   </body>
```

The above example shows a piece of HTML code containing three Javascript scripts. In this script 


Clients do not necessarily need to connect with the browser, or to be human. An automaton bot-player could be launched in the following way.

```js
    var UltiBot = require('ultimatum-bot'); // path/to/ultimatum-bot
    var node = require('nodegame-client'); 

    var conf = {
      player: {
        name: 'Player_Bot',
      },
      url: 'http://localhost:8080/ultimatum/'
    };
    node.play(conf, new UltiBot());
```

As you could see, both files are rather similar, and the main difference concerns how to import the nodeGame library. Notice that the actual game to play must be instantiated and passed as a parameter to the `play` method.


### server logic {#server-logic}

The automaton bot client already showed how to connect 

```js
    var UltiBot = require('ultimatum-bot'); // path/to/ultimatum-bot
    var node = require('nodegame-client'); 

    var conf = {
      player: {
        name: 'Player_Bot',
      },
      url: 'http://localhost:8080/ultimatum/'
    };
    node.play(conf, new UltiBot());
```


### The game structure

**Section still under construction...**

This is just a brief introduction for a complete guide refer to the specific guide.


A game consist in a set of states, steps and rounds. For each step it is possible to define different screens, and rules to apply to the user actions. 


| State       | State name   | Steps                | Repetitions |
| ----------- | ------------ | -------------------- | ----------- |
| **State A** | Instructions | Step 1		            | x1 round    |
| **State B** | Game  	     | Step 1, Step2, Step3	| x10 rounds  |
| **State C** | Debrief	     | Step 1  	 	          | x1 round    |

It is possible to associate other properties to each game state, however they may depend on the additional modules installed with nodeGame. Common extensions are the `timer`, or `done` properties.

#### What happens during a game ?

nodeGame is a messaging library. Clients exchange messages, and react accordingly. All messages pass through the server, which routes them to the correct receiver. When a message is received a particular event is created.

nodeGame provides a convenient API (application programming interface) to deal with most of the standard use cases and events. 

##### What are events?

An event is literally something that has happened. It can really be anything, e.g. the user moving the mouse over a given area of the screen, or clicking a button. Javascript is shipped already with an exhaustive list of event handlers, nodeGame adds some extra ones more targeted for a gaming environment. 
<commit_msg>user-guide<commit_after># nodeGame User Guide

- status: incomplete

## Disclaimer

nodeGame is under active development and new features are constantly added. We do our best to keep this documentation up to date, but it may happen that the software still behave slightly differently than what herein documented. We apologize for this, and kindly ask you to report any gap between this documentation and the actual software behavior.

## Who should read this

This guide covers the basic functionalities of the framework, and offers a broad picture of nodeGame to the beginner. For detailed documentation, API, and format specification please read the other files in the doc directory of the nodeGame repository.   

## Introduction

nodeGame is a free, open source, event-driven Javascript framework for on line, multiplayer games in the browser. It is specially designed to run social science experiments, for studying both individual choices and collective behavior. However, its architecture is general enough to run any type of game. 

### Targeted audience

nodeGame is designed to be as user-friendly as possible, but not more. This means that with little programming skills is already possible to create complex multiplayer games. On the other hand, minimal programming skills are indeed required. This obviously entails also some knowledge of Javascript, the programming language of the browser. For beginner guides about Javascript you can look into:

- [A beginner tutorial](http://www.w3schools.com/js/)
- [An advanced (not free) book](http://www.amazon.com/JavaScript-Good-Parts-Douglas-Crockford/dp/0596517742)

If you are familiar enough with Javascript you can proceed to the next section, and learn how to setup the nodeGame server, how clients can connect to it, and how to write games for nodeGame.

## Installation and Quick start

See [README](https://github.com/nodeGame/nodegame/blob/master/README.md) at the top of this root directory. 

## Understanding nodeGame

In order to run and conduct a game on nodeGame, you will need to:

  1. [setup the server](#setting-up-the-server)
  2. [create a game](#creating-a-game)
  3. [connect to the server](#connecting-to-the-server)
  4. [analyze the results](#analyzing-the-results)


### Setting up the server

In order to run the server you will need to write a small launcher file.

```js
    var ServerNode = require('nodegame-server').ServerNode;
    
    // Options can be specified as input parameter
    var sn = new ServerNode();
    
    sn.addChannel({
        name: 'Ultimatum',
        admin: 'ultimatum/admin',
        player: 'ultimatum',
        game: 'ultimatum',          
    });
```

In the above example:

- the `require` directive import the nodegame-server module;
- a `ServerNode` object with a given name is created listening on port 8080 (by default) 
- a _channel_ is added to the server; a channel binds a route to a specific game. It contains two end-points: for users and administrators.

The `ServerNode` object accepts a configuration object as input parameter. Moreover, it is possible to write separate configuration files for different features of the server. For a detailed documentation on how to configure the nodeGame server read [this guide](https://github.com/nodeGame/nodeGame/blob/master/doc/configure-nodegame-server.md)

### Creating a game

Create a new directory in one of the `games` folder, as defined in the configuration of your nodeGame server. This folder will contain all files necessary to run your game.

Designing a game can vary design. However, e is usually 

  - the client logic
  - the server logic
  - additional files (e.g. images and HTML files)



This is the file that is included in the HTML page

#### The game object

A game object defines a sequence of game states. Each state defines a set of local variables, the screens that will be shown, and the rules that will apply to user actions.
States can be repeated for a certain number of rounds, and divided in sub-states, called _steps_. It is possible to associate properties to each game state, however they may depend on the additional modules installed with nodeGame. Common extensions are the `timer`, or `done` properties.


| State       | State name   | Steps                | Repetitions | Properties  |
| ----------- | ------------ | -------------------- | ----------- | ----------- |
| **State A** | Instructions | Step 1               | x1 round    | timer       |
| **State B** | Game         | Step 1, Step2        | x10 rounds  | -           |
| **State C** | Debrief      | Step 1               | x1 round    | -           |

The game states are defined in the game _loop_.

```javascript

  var game = {
    1: function() {
      // some code here
    },
    2: function() {
      // some code here
    }
  };
  
  this.loop = {

      1: {
        state: function() {
          // the code for the instruction goes here
        },
        name: 'Instructions',
        timer: 120000,
      },
      
      2: {
        state: game,
        name: 'Game will start soon',
        rounds: 10,
      },
      
      3: {
        state: function() {
          // the code goes here
        },
        name: 'Game will start soon'
      },
      
  }
```


For complete, extensively commented examples see:

  - the [Ultimatum client](https://github.com/nodeGame/nodegame/blob/master/games/ultimatum/Ultimatum.js) file in the `games` folder.
  - the [Ultimatum logic](https://github.com/nodeGame/nodegame/blob/master/games/ultimatum/server/logic.js) file in the `games/server` folder.

### Connecting to the server

Now that the server is running, and that a new game folder was created, we need to point our browsers to the our game page, usually called `index.html`.

```html
    <!doctype html>
    <title>nodeClient Example</title>
    <body>
    <script src="/socket.io/socket.io.js"></script> 
    <script src="/javascript/nodegame-full.js" charset="utf-8"></script>
    <script src="Ultimatum.js" charset="utf-8"></script>
    <script>
      window.onload = function(){
        var conf = {
          player: {
            name: 'Player_1',
          }
          url: '/ultimatum'
        };
        node.play(conf, new Ultimatum());
      }
   </script>
   </body>
```

The above example shows a piece of HTML code containing four Javascript scripts. In this script 


Clients do not necessarily need to connect with the browser, or to be human. An automaton bot-player could be launched in the following way.

```js
    var UltiBot = require('ultimatum-bot'); // path/to/ultimatum-bot
    var node = require('nodegame-client'); 

    var conf = {
      player: {
        name: 'Player_Bot',
      },
      url: 'http://localhost:8080/ultimatum/'
    };
    node.play(conf, new UltiBot());
```

As you could see, both files are rather similar, and the main difference concerns how to import the nodeGame library. Notice that the actual game to play must be instantiated and passed as a parameter to the `play` method.


### server logic {#server-logic}

The automaton bot client already showed how to connect 

```js
    var UltiBot = require('ultimatum-bot'); // path/to/ultimatum-bot
    var node = require('nodegame-client'); 

    var conf = {
      player: {
        name: 'Player_Bot',
      },
      url: 'http://localhost:8080/ultimatum/'
    };
    node.play(conf, new UltiBot());
```


### The game structure

**Section still under construction...**


#### What happens during a game ?

nodeGame is a messaging library. Clients exchange messages, and react accordingly. All messages pass through the server, which routes them to the correct receiver. When a message is received a particular event is created.

nodeGame provides a convenient API (application programming interface) to deal with most of the standard use cases and events. 

##### What are events?

An event is literally something that has happened. It can really be anything, e.g. the user moving the mouse over a given area of the screen, or clicking a button. Javascript is shipped already with an exhaustive list of event handlers, nodeGame adds some extra ones more targeted for a gaming environment. 

{'fraction_non_alphanumeric': 0.09027589937787395, 'fraction_numerical': 0.006018393291858264, 'mean_word_length': 3.098946784922395, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2176872', 'n_tokens_mistral': 3979, 'n_tokens_neox': 3757, 'n_words': 1831}