morrisboard/README.md

A Node.js controller for a nine men's morris board

# Morris Board

The `MorrisBoard` controller is a module that is just used to control the board logic of a Nine Men's Morris board.
This API provides all needed methods and tools to manage a morris game logically.

If you are using the game controller, a board instance will be created automatically and is accessible at `yourGame.board`.
But that's how the board works:
```javascript
// 1. Argument is the amount of rows
// 2. Argument is an array representing the logic of points on a side and wether they are connected vertically
var board = new MorrisBoard(3, [false, true, false]);

// Test it out
console.log(board);
```
## Map

The board's points are stored within the `yourBoard.map`. The `map` contains each point as an object literal containing some details about the point and a lot of **Getters** that return things like `mills`, `surroundings`, `line` and more.

This is how a *point's object* looks like within the *map* array:
```javascript
yourBoard.map = [
  ...
  {
    team: false || "black" || "white", // Name of the team that is staying on the point (False if there is no team)
    surroundings: [Object], // (Getter): Returns all connected points
    position: [Object], // (Getter): Returns the position as position object { row: Number, position: Number}
    mills: [Array], // (Getter): Returns all mills in which the point is involved
    sides: [Array], // (Getter): Returns all sides the point is part of
    line: [Object] || [Boolean], // Getter: Returns index of the vertical line the point is part of. If there is no vertical line, the value is false
  }
  ...
]
```

## Coordinating

The coordinating system is, as I already explained, circular. That means, you will mostly address points on the board, by using a row index and a index within the row:
```javascript
// Example position object for a point
{
  row: [Number], // E.g. 0 for the inner row or 2 for the outer (Common Nine Mens's Morris)
  position: [Number] // E.g. 0 for the first of your row or 7 for the last one (Common Nine Men's Morris)
}
```

*Please keep in mind that you have to use your board instance* **within** *your game instance when working with a game controller. Normally this will be found at* `myGame.board`.

### Get Point Index (by using its position)

To get the index of a point directly from the position, use the `getPointIndex()` method of your board instance.

```javascript
var index = board.getPointIndex(row, position);
```
(Of course could also get a point's index by using the `indexOf` method with the `map` array of your *board instance* but this needs a *real* point object and is much slower than this method. This method just calculates it directly. That also means that you could a index that does not exist because no point has such a position.)

### Get Point (by using its position)

To get a point object literal by using the point's position, use the `getPoint()` method of your board instance.

```javascript
var point = board.getPoint(row, position);
```

### Get Point's Position (by using its index)

To get a point's position by using the point's index, use the get `getPointPosition()` method of your board instance.

```javascript
var pos = board.getPointPosition(index);
```

### Get Point (by using its index)

To get a points by its index, just call the index within the `map` array ;-)

```javascript
// Just simple as it is
var point = board.map[index];
```


### Surroundings

The connected points of a point are represented within the `surroundings` property of each point.
A surroundings object contains one key for each direction. Such a key itself contains a *point object*.

```javascript
{
  right: [Object], // Object literal representing the point right from this point
  left: [Object], // Object literal representing the point left from this point
  up: [Object], // Object literal representing the point top from this point
  down: [Object], // Object literal representing the point bottom from this point
}
```

Please always keep in mind that *right*, *right*, *up* and *down* are meant from the perspective of the middle point of the morris board. That's because we are using a **circular** coordinate system to address the points.

### Position

The property `position` of a *point object* returns the exact position within the **circular** coordinate system of the point.
It returns an object that looks like:
```javascript
{
  row: [Number],
  position: [Number]
}
```

As you can see, such an object is also used very often to address a point ;-)

### Mills

The property `mills` of a *point object* returns all mill's in which the point is involved.

Such a mill is represented by an array containing *point objects* for each point.

```javascript
[
  [Array], // Array containing point object for each point that is a part of the mill
  [Array] // Array containing point object for each point that is a part of the mill
]
```

Of course it is theoretically impossible that a point is involved in more than **2** mills at the same time.
And if you are playing morris normally a mill is always is using **3** points. But if you are using **100** rows, of course a vertical mill would need all **100** points.

### Sides

The property `sides` of a *point object* returns all sides the point is a part of. A side is represented by its index.

Normally, when playing with *4* sides this index is from 0-3. Of course, a point can only be a part of **2** sides at the same time.

```javascript
[
  Number, // Index [0-3]
  Number // Index [0-3]
]
```

### Line

The property `line` of a *point object* returns wether the point is a part of a vertical line and if this is the case, the index of it. If not, `false` will be returned.
Wether a point is part of a vertical line is defined by the vertical connections. If the `points` argument when creating the board is `[false, true, false]`, the point in the middle of each side has a vertical line but the others do not.

The index of such a vertical line is the index position relative within the circular coordinate system of its points. For example, in *Nine Men's Morris* there are **4** vertical lines and their indexes would be `1`, `3`, `5` & `7`.

#### getLine()

To return a line's points (*point objects*), call `yourBoard.getLine(lineIndex)`. This will return an *array* containing all points of the line as *point objects*.


## All Mills

To get all mills that are currently active on the board, just use the `mills` property of your board's instance.

```javascript
yourBoard.mills = [
  ...
  [Array],
  [Array],
  [Array]
  ...
];
```