2d-board

Simple array wrapper for 2-dimensional grid-based games

Usage

Basic Usage

// Get and set cells
var cell = [ x, y ];
board.val(cell);
board.val(cell, val);
 
// Set out-of-bounds behavior for step functions
board.setoob("OOB_NEXT");
 
// Step through cells
var next = board.right(cell);

Advanced Usage

// Get and set cols and rows
board.col(x);
board.col(x, vals);
board.row(y);
board.row(y, vals);
 
// Get and set entire board
board.cols(x);
board.cols(x, vals);
board.rows(y);
board.rows(y, vals);
 
// Merge boards
board1.cols(board2.cols());

Documentation

Create a new 3 * 2 board:

var createBoard = require("2d-board");
var board = createBoard(3, 2);

Cell Operations

var cell = [ 0, 0 ];
board.val(cell, 'X'); // Set cell at (0, 0) to 'X'
var val = board.val(cell); // Get cell at (0, 0)
console.log(val); // 'X'

Step Functions

Given the board:

A B C
D E F
G H I

Step across cols and rows:

var cell = [ 1, 1 ]; // 'E'
var next = board.up(cell); // 'E' -> 'B'
if (next !== null) cell = next; // Check for OOB
else { /* Handle it */ }

Step functions are up, down, left, right, and they return null if out of bounds.

You can set the oob flag to define out-of-bounds behavior:

// A B C
// D E F
// G H I
 
board.setoob("OOB_SAME");
var cell = [ 3, 0 ]; // 'F'
var next = board.right(cell); // 'F' -> 'D'
 
board.setoob("OOB_NEXT");
var cell = [ 2, 0 ]; // 'F'
var next = board.right(cell); // 'F' -> 'G'

The available options are:

• "OOB_NULL" to return null on oob (default)
• "OOB_STICK" to return the same coordinates on oob
• "OOB_SAME" to wrap to the same row or col on oob
• "OOB_NEXT" to wrap to the next row or col on oob

Row and Column Operations

To set an entire row or column:

var row0 = [ 0, 1, 2 ];
var row1 = [ 3, 4, 5 ];
var col1 = [ 'A', 'B' ];
board.row(0, row0);
board.row(1, row1);
board.col(1, col1);

This yields the board:

0 A 2
3 B 5

To get an entire row or col:

var row = board.row(0);
var col = board.col(2);
console.log(row); // [ 0, 'A', 2 ]
console.log(col); // [ 2, 5 ]

Board Operations

To set the entire board:

var vals = [
  [ 0, 1, 2 ],
  [ 3, 4, 5 ]
];
board.rows(vals); // Fill the board in rows
 
var vals = [
  [ 0, 3 ],
  [ 1, 4 ],
  [ 2, 5 ]
];
board.cols(vals); // Fill the board in cols

The two operations above yield the same board:

0 1 2
3 4 5

To get the entire board:

var rows = board.rows(); // Retrieve all rows
var cols = board.cols(); // Retrieve all cols
console.log(rows); // [[ 0, 1, 2 ], [ 3, 4, 5 ]]
console.log(cols); // [[ 0, 3 ], [ 1, 4 ], [ 2, 5 ]]

Features & Notes

• Permissive set methods. Handles any given array up to capacity, ignoring the rest.

var board = createNewBoard(3, 1);
board.row(0, [ 0, 1, 2, 3, 4 ]);
 
// Yields the board:
// 0 1 2
// 3 and 4 are ignored.

• Undefined values are skipped.

// A B C
// D E F
// G H I
 
board.row(1, [ '#', , '#' ]);
 
// Yields the board:
// A B C
// # E #
// G H I

• As usual, array contents can be objects. Types can be mixed.

var item = { 'number': 4, 'elements': [ 123, 'abc' ] };
var row = [ 789, item, 'xyz' ];
var board = createNewBoard(3, 1);
board.row(0, row);

• Due to the internal representation of the array, references to rows are more efficient than references to cols.

// Assume a board with equal rows and cols, and homogeneous elements
 
// This is more efficient
var row = board.row(0);
 
// This is less efficient
var col = board.col(0);

Future Developments

• Custom comparator function for board merging
• Hashmap for board representation, instead of using array