gridboard

A Grid-Based Games Framework For TypeScript/JavaScript

Usage no npm install needed!

<script type="module">
  import gridboard from 'https://cdn.skypack.dev/gridboard';
</script>

README

GridBoard - A Grid-Based Games Framework For TypeScript/JavaScript

Getting Started with GridBoard

Installation

npm install --save gridboard

Also available UMD package defines a window.gridboard global variable.
Can be used for <script> by this link: https://unpkg.com/gridboard@4.1.4/dist/gridboard.js
or minified version: https://unpkg.com/gridboard@4.1.4/dist/gridboard.min.js

Create A Empty Chess Board (use TypeScript)

import { GridBoard } from "gridboard";

type ChessColor = "white" | "black";
type ChessType = "king" | "queen" | "knight" | "bishop" | "rook" | "pawn";

interface Chess {
    color: ChessColor;
    type: ChessType;
}

var board = new GridBoard<Chess>(8, 8);

Create An Empty Chess Board (use JavaScript)

In Node.js

const { GridBoard } = require("gridboard");

var board = new GridBoard(8, 8);

In Browser (use RequireJS)

require(["https://unpkg.com/gridboard@4.1.4/dist/gridboard"], function (gridboard) {
    var GridBoard = gridboard.GridBoard;

    var board = new GridBoard(8, 8);
});

In Browser

Add this tag in your html file's <head> tag

<script src="https://unpkg.com/gridboard@4.1.4/dist/gridboard.js"></script>
var { GridBoard } = window["gridboard"];

var board = new GridBoard(8, 8);

Place Chess On Empty Chess Board

Chess can store in grid.piece

var __ = undefined;

var WK = { color: "white", type: "king" };
var WQ = { color: "white", type: "queen" };
var WN = { color: "white", type: "knight" };
var WB = { color: "white", type: "bishop" };
var WR = { color: "white", type: "rook" };
var WP = { color: "white", type: "pawn" };

var BK = { color: "black", type: "king" };
var BQ = { color: "black", type: "queen" };
var BN = { color: "black", type: "knight" };
var BB = { color: "black", type: "bishop" };
var BR = { color: "black", type: "rook" };
var BP = { color: "black", type: "pawn" };

var pieces = [
//   A,  B,  C,  D,  E,  F,  G,  H  x / y
    WR, WN, WB, WQ, WK, WB, WN, WR,  // 1
    WP, WP, WP, WP, WP, WP, WP, WP,  // 2
    __, __, __, __, __, __, __, __,  // 3
    __, __, __, __, __, __, __, __,  // 4
    __, __, __, __, __, __, __, __,  // 5
    __, __, __, __, __, __, __, __,  // 6
    BP, BP, BP, BP, BP, BP, BP, BP,  // 7
    BR, BN, BB, BQ, BK, BB, BN, BR,  // 8
];

board.grids.forEach((grid, i) => grid.piece = pieces[i]);

Define State On Grid

Define state in grid.state, such as like grid's color.

var W = "white";
var B = "black";

var colors = [
//  A, B, C, D, E, F, G, H  x / y
    W, B, W, B, W, B, W, B,  // 1
    B, W, B, W, B, W, B, W,  // 2
    W, B, W, B, W, B, W, B,  // 3
    B, W, B, W, B, W, B, W,  // 4
    W, B, W, B, W, B, W, B,  // 5
    B, W, B, W, B, W, B, W,  // 6
    W, B, W, B, W, B, W, B,  // 7
    B, W, B, W, B, W, B, W,  // 8
];

board.grids.forEach((grid, i) => grid.state = colors[i]);

Get Grid By Absolute Coordinate

var gridAtD5 = board.getGridByAbsoluteCoordinate(3, 4);
var gridAtC6 = board.getGridByAbsoluteCoordinate([2, 5]); // passing array is also available
var gridAtF4 = board.getGridAt(5, 3); // shortcut
var gridAtG2 = board.getGridAt([6, 1]);

Get Grid By Relative Coordinate

var gridAtD4 = gridAtD5.getGridByRelativeCoordinate(0, -1);
var gridAtE6 = gridAtC6.getGridByRelativeCoordinate([2, 0]); // passing array is also available
var gridAtE3 = gridAtF4.getGridTo(-1, -1); // shortcut
var gridAtF3 = gridAtG2.getGridTo([-1, 1]);

Use Direction

Refer to previous section, relative coordinate can be expressed by direction.

import { Direction } from "gridboard";
// F = y - 1
// B = y + 1
// L = x - 1
// R = x + 1
// ex. FFL = [-1, -2]
var gridAtD4 = gridAtD5.getGridByRelativeCoordinate(Direction("F"));
var gridAtF3 = gridAtG2.getGridTo(Direction`BL`); // template string is also available

Use Orientation Coordinate Converter

Change Board's Orientation, defining directions will be easy.

import { Orientation, OrientationCoordinateConverter } from "gridboard";

// default look like this:
//   F   |   | 0 | 1 |
// L   R | 0 |   |   |
//   B   | 1 |   |   |
var asBlackSide = new OrientationCoordinateConverter(board, Orientation.FBLR);

// can be look like this:
//   B   |   | 1 | 0 |
// R   L | 1 |   |   |
//   F   | 0 |   |   |
var asWhiteSide = new OrientationCoordinateConverter(board, Orientation.BFRL);

// the result will look like this:
//   A,  B,  C,  D,  E,  F,  G,  H  x / y
//  WR, WN, WB, WQ, WK, WB, WN, WR,  // 1
//  WP, WP, WP, WP, WP, WP, WP, WP,  // 2
//  __, __, __, __, __, __, __, __,  // 3
//  __, __, __, __, __, __, __, __,  // 4
//  __, __, __, __, __, __, __, __,  // 5
//  BP, __, __, __, __, __, __, __,  // 6
//  __, BP, BP, BP, BP, BP, BP, BP,  // 7
//  BR, BN, BB, BQ, BK, BB, BN, BR,  // 8
var gridAtA7 = board.getGridAt(0, 6, asBlackSide);
var gridAtA6 = gridAtA7.getGridTo(Direction`F`, asBlackSide);
gridAtA6.piece = gridAtA7.piece;
gridAtA7.piece = __;

// the result will look like this(rotated):
//   H,  G,  F,  E,  D,  C,  B,  A  x / y
//  BR, BN, BB, BK, BQ, BB, BN, BR,  // 8
//  BP, BP, BP, BP, BP, BP, BP, __,  // 7
//  __, __, __, __, __, __, __, BP,  // 6
//  __, __, __, __, __, __, __, __,  // 5
//  __, __, __, __, __, __, __, __,  // 4
//  WP, __, __, __, __, __, __, __,  // 3
//  __, WP, WP, WP, WP, WP, WP, WP,  // 2
//  WR, WN, WB, WK, WQ, WB, WN, WR,  // 1
var gridAtH2 = board.getGridAt(0, 6, asWhiteSide);
var gridAtH3 = gridAtH2.getGridTo(Direction("F"), asWhiteSide);
gridAtH3.piece = gridAtH2.piece;
gridAtH2.piece = __;

// result:
//   A,  B,  C,  D,  E,  F,  G,  H  x / y
//  WR, WN, WB, WQ, WK, WB, WN, WR,  // 1
//  WP, WP, WP, WP, WP, WP, WP, __,  // 2
//  __, __, __, __, __, __, __, WP,  // 3
//  __, __, __, __, __, __, __, __,  // 4
//  __, __, __, __, __, __, __, __,  // 5
//  BP, __, __, __, __, __, __, __,  // 6
//  __, BP, BP, BP, BP, BP, BP, BP,  // 7
//  BR, BN, BB, BQ, BK, BB, BN, BR,  // 8

Customize Coordinate Convertion

Use Coordinate Converter

Converter only needs 2 methods: convertAbsoluteCoordinate, convertRelativeCoordinate

var board = new GridBoard(3, 3);

var asCyclic = {
    convertAbsoluteCoordinate(x, y) {
        x = (x % board.width + board.width) % board.width;
        y = (y % board.height + board.height) % board.height;
        return [x, y];
    },
    convertRelativeCoordinate(dx, dy) {
        return [dx, dy]; // no need to change
    }
};

var grid = board.getGridAt(-1, -1, asCyclic);
grid.x === 2; // true
grid.y === 2; // true

Use Coordinate Convert Function

Refer to previous section, coordinate convert function is also available

var board = new GridBoard(3, 3);

function asCyclic(x, y) {
    x = (x % board.width + board.width) % board.width;
    y = (y % board.height + board.height) % board.height;
    return [x, y];
}

var grid = board.getGridAt(-1, -1, asCyclic);
grid.x === 2; // true
grid.y === 2; // true