Developer Guide

nodeGame Developer Guide

Installation

1. Download the version 4.x of Node.js for your platform.
2. Download the latest version of Git for your platform.
3. Get the latest sources from GitHub via the [Mac/Linux] (https://raw.githubusercontent.com/nodeGame/nodegame/master/bin/install.latest.sh) or [Windows] (https://raw.githubusercontent.com/nodeGame/nodegame/master/bin/install.latest.cmd) installer script.

There is a separate developer's [install script] (https://raw.githubusercontent.com/nodeGame/nodegame/master/bin/install.dev.sh) available for nodeGame contributors. It automatically places Git-hooks in all sub-modules which enables some automatic code-style enforcement and automatic doc-building on committing.

Compiling the Code

Building nodeGame

If you make changes in the code, you will have to run the build scripts to update the files necessary for running nodeGame:

1. Do your changes in the module of your choice.
2. In that module: node bin/make.js build -a
3. Go to the server module (nodegame/node_modules/nodegame-server) and type: node bin/make.js build-client -a -o nodegame-full

Debugging

JavaScript / Node.JS have a built-in debugger. Follow the links below for further information.

• Debugging in the browser.
• Debuggin in node.js

Furthermore, nodeGame can be executed in debug-mode if the flag node.debug is set to TRUE. In debug-mode all errors will be thrown. Otherwise, nodeGame will try to catch them.

Building documentation

After changing code and especially documentation comments for a module, it is recommended to re-build the HTML documentation with node bin/make.js doc.

This is done automatically with every git commit if the developer's install script was used or the [pre-commit] (https://raw.githubusercontent.com/nodeGame/nodegame/master/git-hooks/pre-commit) Git-hook was copied over from nodegame/git-hooks/.

To get the updated documentation onto a module's GitHub page (e.g. http://nodegame.github.io/nodegame-server/docs/index.js.html), execute the following command in the master branch:

git checkout gh-pages && git merge master && git pull && git push && git checkout master

For convenience, create an alias in your Git configuration file (~/.gitconfig on Linux):

...
[alias]
    pushpages = !git checkout gh-pages && git merge master && \
      git pull && git push && git checkout master
...

Browse Sources

• Client
• Widgets
• Window
• Server

NodeGame Events

See the list of all nodeGame events.

Writing Code

The source code of nodeGame follows the following conventions.

Whitespace

• Indenting uses four spaces, tabs are never used.
• Lines do not have any trailing whitespace.
• Source files have one newline at the end.
• In control flow statements, the opening parenthesis follows a space (see examples in Braces).
• There is no space between a function name and the opening parenthesis of its parameters.

Braces

• Opening braces are on the same line as their corresponding control flow statements.
• Closing braces are on their own line.
• When a control flow statement is broken into multiple lines, it is followed by an empty line.
• Braces may only be left out if the single statement it would contain is on the same line as the leading control flow statement (see bottom of example).

Examples:

function control(a, b) {  // No space after 'control'.
    if (a >= b) {
        console.log('Greater or equal');
    }
    else if (a < b) {  // Note brace arrangement around 'else'.
        console.log('Less');
    }
    else {
        console.log('NaN');
    }

    while (veryLongCondition1 &&
           veryLongCondition2) {  // Empty line following.

        doThing(function(e) {   // No space after 'function'.
            console.log(e);
        });
    }
}

if (x < 0) x = 0;  // OK

if (x === 5) {
  x = 8;  // OK
}

if (x > 9)
    x = 9;  // NOT OK!

Logic

• Strict in-/equality !==/=== is used instead of !=/== wherever possible.
• All "for-in" loops check hasOwnProperty on each iteration.
• Variable shadowing should be avoided.

Examples:

function printProps(obj) {
    var i;

    for (i in obj) {
        if (obj.hasOwnProperty(i)) {  // Important.
            console.log(i, obj[i] === null ? 'N/A' : obj[i]);
        }
    }

    function() {
        var obj;  // Shadowing NOT OK!
    }();
}

Naming

• Variable names use camelCase.
• Constant names use UNDERSCORED_UPPER_CASE.
• Class names use PascalCase.
• Names should be descriptive.

Miscellaneous

• Lines are at most 80 characters long.
• Strings use single quotes by default, double quotes if more convenient.
• All variables are declared at the top of their scope and are assigned to separately.
• Messages in new exceptions start with the class name suffixed with a dot (if inside a class), followed by the function name and a colon. The description starts with a lower-case letter and ends with a period.
• Comments are generally on lines of their own, before the code they concern, starting with a capital letter and ending with a punctuation symbol, usually a period.

Examples:

function sumArray(array) {
    var i, sum;  // All declarations on top, no assignments.

    // Check input.
    if (!array || 'number' !== typeof array.length) {
        throw new TypeError('sumArray: array.length must be number.');
    }

    // Sum up elements.
    sum = 0;
    for (i = 0; i < array.length; ++i) {
        sum += array[i];
    }

    console.log("Sum of 'array': " + sum + '.');
    return sum;
}

MyClass.prototype.fail = function() {
    throw new Error('MyClass.fail: always throws.');
}

Writing Documentation

nodeGame uses docker to generate its documentation. In addition to the above practices used in the code, the following rules apply for doc comments.

For an example of these rules used in practice, see the documentation of nodegame-server.

Sections

Docker pages use a hierarchy of sections, with different levels denoted by #, ##, ### etc. A nodeGame source file has the following structure:

# ClassName [filename without extension]
## ClassName constructor
### ClassName.field
### ...
## ClassName methods
### ClassName.method
### ...

For example:

# Circle
## Circle constructor
### Circle.posX
### Circle.posY
### Circle.radius
## Circle methods
### Circle.setPosition
### Circle.getArea
### Circle.draw

In special cases, more sections can be added.

Documentation comments

After the section definition, the rest of the doc comment describes the documented field or method.

• The first line is a short summary, beginning with a capital letter and ending without a period, surrounded by empty lines. For methods, this should start with a verb in third person.
• Next, an optional longer description follows. The sentences in the descriptions end in a punctuation symbol.

Field example:

/**
 * ### Circle.radius
 *
 * Radius of the circle
 *
 * The radius is half the diameter.
 */
this.radius = radius;

For methods:

• Parameter descriptions start with a capital letter, the last sentence has no period.
• Descriptions of optional parameters begin with "Optional.".
• @param, @return sections that span multiple lines have the extra lines indented by two spaces.
• There is a blank line before @return sections.

Method example:

/**
 * ### Circle.setPosition
 *
 * Sets the circle's position
 *
 * @param {number} x The new x position
 * @param {number} y The new y position
 * @param {boolean} rel Optional. Whether to add to the old position
 *   instead of using absolute coordinates. Default: FALSE
 *
 * @return {boolean} TRUE on success, FALSE on failure
 */
Circle.prototype.setPosition = function(x, y, rel) { ... }

• Horizontal lines (---) are never used.

Bulleted lists

• All bulleted lists in documentation comments are surrounded by empty lines.
• Lists in @param and @return are indented by two spaces.

Example:

/**
 * ### Circle.draw
 *
 * Draws the circle
 *
 * Can draw to either:
 *
 * - The console
 * - An HTML canvas
 *
 * @param {object} options Drawing options with the following fields:
 *
 *   - target (string): Where to draw
 *   - color (string): Optional. Color with which to draw
 *
 * @return {object} An object containing the results with the
 *   following fields:
 *
 *   - success (boolean): Whether the drawing was successful
 */
Circle.prototype.draw = function(options) { ... }