

Board

Introduction¶

Core object of Board system.

Author: Rex
Member of scene

Live demos¶

Usage¶

Sample code

Install plugin¶

Load minify file¶

Load plugin (minify file) in preload stage

scene.load.scenePlugin('rexboardplugin', 'https://raw.githubusercontent.com/rexrainbow/phaser3-rex-notes/master/dist/rexboardplugin.min.js', 'rexBoard', 'rexBoard');

Add board object

var board = scene.rexBoard.add.board(config);

Import plugin¶

Install rex plugins from npm
```
npm i phaser3-rex-plugins
```

Install plugin in configuration of game

import BoardPlugin from 'phaser3-rex-plugins/plugins/board-plugin.js';
var config = {
    // ...
    plugins: {
        scene: [{
            key: 'rexBoard',
            plugin: BoardPlugin,
            mapping: 'rexBoard'
        },
        // ...
        ]
    }
    // ...
};
var game = new Phaser.Game(config);

Add board object

var board = scene.rexBoard.add.board(config);

Import class¶

Install rex plugins from npm
```
npm i phaser3-rex-plugins
```

Import class

import { Board, HexagonGrid, QuadGrid } from 'phaser3-rex-plugins/plugins/board-components.js';

Add board object
```
var board = new Board(scene, config);
```

Add board object¶

Quad board

var board = scene.rexBoard.add.board({
    grid: {
        gridType: 'quadGrid',
        x: 0,
        y: 0,
        cellWidth: 0,
        cellHeight: 0,
        type: 'orthogonal'  // 'orthogonal'|'isometric'
    },
    width: 0,
    height: 0
});

Hexagon board

var board = scene.rexBoard.add.board({
    grid: {
        gridType: 'hexagonGrid',
        x: 0,
        y: 0,
        cellWidth: 0,
        cellHeight: 0,
        staggeraxis: 'x',   // 'x'|'y'
        staggerindex: 'odd' // 'odd'|'even'
    },
    width: 0,
    height: 0
});

Configuration

grid :
- gridType :
  - 'quadGrid' : Quad grid
  - 'hexagonGrid' : hexagon grid
width : Board width in tiles
height : Board height in tiles

Custom class¶

Define class

class MyBoard extends RexPlugins.Board.Board {
    constructor(scene) {
        super(scene, {
            grid: {
                gridType: 'quadGrid',
                x: 0,
                y: 0,
                cellWidth: 0,
                cellHeight: 0,
                type: 'orthogonal'  // 'orthogonal'|'isometric'
            },
            width: 0,
            height: 0
        });
        // ...
    }
    // ...
}

Create instance
```
var board = new MyBoard(scene);
```

Board size¶

Width : Board width in tiles

Get
```
var width = board.width;
```
Set
```
board.setBoardWidth(width);
```

Height : Board height in tiles

Get
```
var height = board.height;
```
Set
```
board.setBoardHeight(height);
```

Add chess¶

board.addChess(chess, tileX, tileY, tileZ, align);

chess : A game object.
tileX , tileY , tileZ : Tile position.
align : Set true to align (i.e. set position) chess to grid (tileX, tileY). Default is true.

Chess and tile position

Any chess has a (tileX, tileY, tileZ) index
Any (tileX, tileY, tileZ) index contains only 1 chess.
(tileX, tileY) could have more then 1 chess with different tileZ index.
tileZ is not equal to depth.

Kick-out event¶

Board will fire kickout event when adding chess to an occupied grid.

board.on('kickout', function(chessToAdd, occupiedChess, tileXYZ){
})

chessToAdd kicks out occupiedChess at tile position tileXYZ({x,y,z}).

Remove chess¶

Remove chess object from board
```
board.removeChess(chess, null, null, null, destroy);
```
- chess : A game object
- destroy : Set true to desrtoy chess object.
Remove chess at (tileX, tileY, tileZ) from board
```
board.removeChess(null, tileX, tileY, tileZ, destroy);
```
- tileX, tileY, tileZ : Tile position
- destroy : Set true to desrtoy chess object.
Remove all chess
```
board.removeAllChess(destroy);
```
- destroy : Set true to desrtoy chess object.

Move chess¶

board.moveChess(chess, toTileX, toTileY, toTileZ, align);

chess : A game object
toTileX, toTileY, toTileZ : Target tile position
align : Set true to align (i.e. set position) chess to grid (tileX, tileY).

Swap chess¶

board.swapChess(chessA, chessB, align);

chessA, chessB : Game objects
align : Set true to align (i.e. set position) chess to grid (tileX, tileY).

Chess -> tile position¶

var tileXYZ = board.chessToTileXYZ(chess);

chess : A game object
tileXYZ : {x,y,z} or null if chess is not added to board.

Tile position -> chess¶

Get chess at (tileX, tileY, tileZ)

var chess = board.tileXYZToChess(tileX, tileY, tileZ);

chess : A game object

Get chess at (tileX, tileY)

var out = board.tileXYToChessArray(tileX, tileY);
// var out = board.tileXYToChessArray(tileX, tileY, out);

out : An array of chess

Get chess at tileZ

var out = board.tileZToChessArray(tileZ);
// var out = board.tileZToChessArray(tileZ, out);

out : An array of chess

Get chess from array of (tileX, tileY)

var out = board.tileXYArrayToChessArray(tileXYArray);
// var out = board.tileXYArrayToChessArray(tileXYArray, out);

or

var out = board.tileXYArrayToChessArray(tileXYArray, tileZ);
// var out = board.tileXYArrayToChessArray(tileXYArray, tileZ, out);

tileXYArray : An array of tileXY {x, y}
out : An array of chess

World position -> chess¶

Get chess at (worldX, worldY)

var out = board.worldXYToChessArray(worldX, worldY);
// var out = board.worldXYToChessArray(tileX, tileY, out);

out : An array of chess

Get chess at (worldX, worldY), tileZ

var chess = board.worldXYToChess(worldX, worldY, tileZ);

chess : A game object

Get chess at (worldX, worldY)
```
var chess = board.worldXYToChess(worldX, worldY);
```
- chess : A game object at a tileZ.

Contains¶

Is (tileX, tileY) inside board?

var isTileInBoard = board.contains(tileX, tileY);

Does (tileX, tileY, tileZ) have chess?

var isTileInBoard = board.contains(tileX, tileY, tileZ);

Is chess inside board?

var isChessInBoard = board.exists(chess);

chess : A game object

For each tile¶

board.forEachTileXY(function(tileXY, board) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
}, scope, order);

Iteration order :

board.forEachTileXY(function(tileXY, board) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
}, scope, order);

order :
- 0, or x+ : Increasing x, increasing y.
- 1, or x- : Decreasing x, increasing y.
- 2, or y+ : Increasing y, increasing x.
- 3, or y- : Decreasing y, increasing x.

Or using for-loop

for (var tileY = 0; tileY < board.height; tileY++) {
    for (var tileX = 0; tileX < board.width; tileX++) {
        // ...
    }
}

board.width , board.height : Board width/height in tiles.

Tile position -> world position¶

var worldXY = board.tileXYToWorldXY(tileX, tileY);  // worldXY: {x, y}
// var out = board.tileXYToWorldXY(tileX, tileY, out);

World position -> tile position¶

var tileXY = board.worldXYToTileXY(worldX, worldY);  // tileXY: {x, y}
// var out = board.worldXYToTileXY(worldX, worldY, out);

World position -> Grid world position¶

var gridWorldXY = board.worldXYSnapToGrid(worldX, worldY);
// var out = board.worldXYSnapToGrid(worldX, worldY, out);

Grid distance¶

var distance = board.getDistance(tileA, tileB);

Ring -> tile position¶

Get array of tile position around a ring.

var out = board.ringToTileXYArray(centerTileXY, radius);
// var out = board.ringToTileXYArray(centerTileXY, radius, out);

centerTileXY : Tile position {x, y} of ring center.
radius : Radius of the ring.

Get array of tile position within a filled ring.

var out = board.filledRingToTileXYArray(centerTileXY, radius);
var out = board.filledRingToTileXYArray(centerTileXY, radius, nearToFar);
// var out = board.filledRingToTileXYArray(centerTileXY, radius, out);
// var out = board.filledRingToTileXYArray(centerTileXY, radius, nearToFar, out);

centerTileXY : Tile position {x, y} of ring center.
radius : Radius of the ring.
nearToFar : From near ring to far ring. Default value is true.

Shape -> tile position¶

Line -> tile position¶

Get array of tile position along a line defined via (startWorldX, startWorldY) to (endWorldX, endWorldY)

var out = board.lineToTileXYArray(startWorldX, startWorldY, endWorldX, endWorldY);
// var out = board.lineToTileXYArray(startWorldX, startWorldY, endWorldX, endWorldY, out);

startWorldX, startWorldY, endWorldX, endWorldY : Start and end pointer of a line
out : An array of tile position

or

var out = board.lineToTileXYArray(line);
// var out = board.lineToTileXYArray(line, out);

line : Line object

Circle -> tile position¶

Get array of tile position inside a circle shape

var out = board.circleToTileXYArray(circle);
// var out = board.circleToTileXYArray(circle, out);

circle : Circle shape
out : An array of tile position

Rectangle -> tile position¶

Get array of tile position inside a rectangle shape

var out = board.rectangleToTileXYArray(rectangle);
// var out = board.rectangleToTileXYArray(rectangle, out);

rectangle : Rectangle shape
out : An array of tile position

Ellipse -> tile position¶

Get array of tile position inside a ellipse shape

var out = board.ellipseToTileXYArray(ellipse);
// var out = board.ellipseToTileXYArray(ellipse, out);

ellipse : Ellipse shape
out : An array of tile position

Triangle -> tile position¶

Get array of tile position inside a triangle shape

var out = board.triangleToTileXYArray(triangle);
// var out = board.triangleToTileXYArray(triangle, out);

triangle : Triangle shape
out : An array of tile position

Polygon -> tile position¶

Get array of tile position inside a polygon shape

var out = board.polygonToTileXYArray(polygon);
// var out = board.polygonToTileXYArray(polygon, out);

polygon : Polygon shape
out : An array of tile position

Angle between world position of 2 tiles¶

var radian = board.angleBetween(tileXY0, tileXY1);

radian : Angle between world position of 2 tiles, in radian.
tileXY0, tileXY1 : tile position {x, y}

Is angle in cone¶

var isInCone = board.isAngleInCone(chessA, chessB, face, cone);

chessA, chessB : Direction from chessA to chessB. Chess object, or tileXY.
face, cone : Range of compared angle is between face - (cone/2) to face + (cone/2). Angle in radian.

Direction between 2 tiles¶

var direction = board.directionBetween(chessA, chessB);

chessA, chessB : A chess object, or tile position {x,y}.
direction : Integer number.
- Quad grid : 0, 1, 2, 3, 4, 5, 6, 7.
- Hexagon grid : 0, 1, 2, 3, 4, 5.

var direction = board.directionBetween(chessA, chessB, false);

direction : Integer number, or float number.
- Quad grid : 0, 1, 2, 3, 4, 5, 6, 7, or float number between 0~1, 1~2, 2~3, 3~4, 4~5, 5~6, 6~7.
- Hexagon grid : 0, 1, 2, 3, 4, 5, or float number between 0~1, 1~2, 2~3, 3~4, 4~5, 5~6.

Is direction in cone¶

var isInCone = board.isDirectionInCone(chessA, chessB, face, cone);

chessA, chessB : Direction from chessA to chessB. Chess object, or tileXY.
face, cone : Range of compared direction is between face - (cone/2) to face + (cone/2). Integer number, or float number.
- Quad grid : 0, 1, 2, 3, or float number between 0~1, 1~2, 2~3, 3~4.
- Hexagon grid : 0, 1, 2, 3, 4, 5, or float number between 0~1, 1~2, 2~3, 3~4, 4~5, 5~6.

Opposite direction¶

var direction = board.getOppositeDirection(tileX, tileY, direction);

Angle snap to direction¶

var direction = board.angleSnapToDirection(chess, angle);

chess : Chess object, or tileXY, or undefined.
angle : Angle in radius.
direction : Integer number.
- Quad grid : 0, 1, 2, 3, 4, 5, 6, 7.
- Hexagon grid : 0, 1, 2, 3, 4, 5.

Align world position to grid¶

Align one chess object
```
board.gridAlign(chess);
```
Align all chess
```
board.gridAlign();
```

Is overlapping with world position¶

var isOverlapping = board.isOverlappingPoint(worldX, worldY);

or

var isOverlapping = board.isOverlappingPoint(worldX, worldY, tileZ);

Neighbors¶

Neighbor tile position¶

Get neighbor tile position at 1 direction
```
var neighborTileXY = board.getNeighborTileXY(srcTileXY, direction);
// var out = board.getNeighborTileXY(srcTileXY, direction, out);
```
- srcTileXY : Tile position {x, y} of source.
- direction : Number, or string number.
  - 0 ~ 3 : Quad grid in 4 directions mode.
  - 0 ~ 7 : Quad grid in 8 directions mode.
  - 0 ~ 5 : Hexagon grid.
- neighborTileXY : Tile position {x, y} of neighbor. Retrun null if no neighbor there (i.e. source chess is at the edge of board.)
Get neighbor tile position at directions
```
var neighborTileXY = board.getNeighborTileXY(srcTileXY, directions);
// var out = board.getNeighborTileXY(srcTileXY, directions, out);
```
- directions
  - Array of numbers, [0, 2, 4].
  - String number concatenated via ,, '0,2,4'.
- out : Tile position array of all neighbors

Get neighbor tile position at all directions

var out = board.getNeighborTileXY(srcTileXY, null);
// var out = board.getNeighborTileXY(srcTileXY, null, out);

out : Tile position array of all neighbors

Get direction between 2 tile positions
```
var direction = board.getNeighborTileDirection(srcTile, neighborTileXY);
```
- direction : Return null if these 2 tile positions are not neighbors.
Get neighbor tile position at angle
```
var neighborTileXY = board.getNeighborTileXYAtAngle(srcTileXY, angle);
// var out = board.getNeighborTileXY(srcTileXY, angle, out);
```
- srcTileXY : Tile position {x, y} of source.
- angle : Angle in radius.
- neighborTileXY : Tile position {x, y} of neighbor. Retrun null if no neighbor there (i.e. source chess is at the edge of board.)

Neighbor chess¶

Get neighbor chess at 1 direction
```
var neighborChess = board.getNeighborChess(chess, direction); // neighborTileZ = tileZ of chess
// var neighborChess = board.getNeighborChess(chess, direction, neighborTileZ);
```
- chess : A chess object, or tile position {x,y,z}.
- direction : Number, or string number.
  - 0 ~ 3 : Quad grid in 4 directions mode.
  - 0 ~ 7 : Quad grid in 8 directions mode.
  - 0 ~ 5 : Hexagon grid.
- neighborChess : A chess object.
Get neighbor chess at directions
```
var out = board.getNeighborChess(chess, directions); // neighborTileZ = tileZ of chess
// var out = board.getNeighborChess(chess, directions, neighborTileZ);
```
- chess : A chess object, or tile position {x,y,z}.
- directions
  - Array of numbers, [0, 2, 4].
  - String number concatenated via ,, '0,2,4'.
- out : Chess array of neighbors.

Get neighbor chess at all directions

var out = board.getNeighborChess(chess, null); // neighborTileZ = tileZ of chess
// var out = board.getNeighborChess(chess, null, neighborTileZ);

chess : A chess object, or tile position {x,y,z}.
out : Chess array of all neighbors.

Get direction between 2 chess
```
var direction = board.getNeighborChessDirection(chess, neighborChess);
```
- direction : Return null if these 2 chess are not neighbors.

Are 2 chess neighbors?

var areNeighbor = board.areNeighbors(chessA, chessB);

areNeighbor : Return true if chessA and chessB are neighbors.

Tile at direction¶

Get tile position at 1 direction
```
var out = board.getTileXYAtDirection(srcTileXY, direction, distance);
// var out = board.getTileXYAtDirection(srcTileXY, direction, distance, out);
```
- srcTileXY : Tile position {x, y} of source.
- direction : Number, or string number.
  - 0 ~ 3 : Quad grid in 4 directions mode.
  - 0 ~ 7 : Quad grid in 8 directions mode.
  - 0 ~ 5 : Hexagon grid.
- distance : A JSON, number, or number array.
  - JSON : Range of distances. {end: 3} is equal to [1,2,3].
```
{
    start: 1,
    end: 1,
    step: 1
}
```
    - start : Start distance. Default value is 1.
    - end : End distance. Default value is 1.
    - step : Step. Default value is 1.
  - Number, 3.
  - Array of numbers, [2, 3, 5] : Array of distances.
- out :
  - A single tile position, if distance is a number.
  - Tile position {x, y} array, if distance is a JSON or an array.

Get tile positions at directions

var neighborTileXY = board.getTileXYAtDirection(srcTileXY, directions, distance);
// var out = board.getTileXYAtDirection(srcTileXY, directions, distance, out);

directions
- Array of numbers, [0, 2, 4].
- String number concatenated via ,, '0,2,4'.
out : Tile position {x, y} array.

Get tile positions at all directions

var out = board.getTileXYAtDirection(srcTileXY, null, distance);
// var out = board.getTileXYAtDirection(srcTileXY, null, distance, out);

out : Tile position {x, y} array.

Empty tile position¶

Get a random tile position which does not have any chess
```
var tileXY = board.getRandomEmptyTileXY(tileZ);
// var out = board.getRandomEmptyTileXY(tileZ, out);
```
- tileXY : Tile position {x, y}, return null if all positions are occupied.

Get an array of tile position which does not have any chess

var tileXYArray = board.getEmptyTileXYArray(tileZ);
// var out = board.getEmptyTileXYArray(tileZ, out);

tileXYArray : An array of tile position

Get all chess¶

var chessArray = board.getAllChess();

Fit¶

var out = board.fit(tileXYArray);

tileXYArray : An array of tile position {x,y}.

Offset all of tile positions to (0, 0), and set board size to fit these tile positions.

Blocker¶

Set blocker property : See chess data

Has blocker at tile position (tileX, tileY, tileZ)

var hasBlocker = board.hasBlocker(tileX, tileY, tileZ);

Any chess at (tileX, tileY) has blocker property

var hasBlocker = board.hasBlocker(tileX, tileY);

Touch events¶

Set interactive¶

Enable
```
board.setInteractive();
```
Disable
```
board.setInteractive(false);
```

Pointer down¶

Pointer down at any tile

board.on('tiledown', function(pointer, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

pointer : Touch pointer
tileXY : {x, y}

Pointer down at chess

board.on('gameobjectdown', function(pointer, gameObject) {
})

or

gameObject.on('board.pointerdown', function(pointer) {
})

pointer : Touch pointer
gameObject : Game object at touched (tileX, tileY)

Pointer up¶

Pointer up at any tile

board.on('tileup', function(pointer, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

tileXY : {x, y}

Pointer up at chess

board.on('gameobjectup', function(pointer, gameObject) {
})

or

gameObject.on('board.pointerup', function(pointer) {
})

pointer : Touch pointer
gameObject : Game object at touched (tileX, tileY)

Pointer move¶

Pointer move to another tile

board.on('tilemove', function(pointer, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

tileXY : {x, y}
Only triggered when tileXY is changed.

Pointer move to another chess

board.on('gameobjectmove', function(pointer, gameObject) {
})

or

gameObject.on('board.pointermove', function(pointer) {
})

pointer : Touch pointer
gameObject : Game object at touched (tileX, tileY)

Pointer over¶

Pointer over to another tile

board.on('tileover', function(pointer, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

tileXY : {x, y}
Only triggered when tileXY is changed.

Pointer over to another chess

board.on('gameobjectover', function(pointer, gameObject) {
})

or

gameObject.on('board.pointerover', function(pointer) {
})

pointer : Touch pointer
gameObject : Game object at touched (tileX, tileY)

Pointer out¶

Pointer out tile

board.on('tileout', function(pointer, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

tileXY : {x, y}
Only triggered when tileXY is changed.

Pointer out chess

board.on('gameobjectout', function(pointer, gameObject) {
})

or

gameObject.on('board.pointerout', function(pointer) {
})

pointer : Touch pointer
gameObject : Game object at pointer-out (tileX, tileY)

Tap ¶

Tap at any tile

board.on('tiletap', function(tap, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
    // var tapsCount = tap.tapsCount;
});

tap : Tap behavior.
- tap.tapsCount : Taps count.
tileXY : {x, y}

N-taps at any tile

board.on('tile' + tapsCount + 'tap' , function(tap, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

'tile' + tapsCount + 'tap' : 'tile1tap', 'tile2tap', 'tile3tap', etc ...
tap : Tap behavior.
tileXY : {x, y}

Tap at chess

board.on('gameobjecttap', function(tap, gameObject) {
    // var tapsCount = tap.tapsCount;
})

or

gameObject.on('board.tap', function(tap) {
    // var tapsCount = tap.tapsCount;
})

tap : Tap behavior.
- tap.tapsCount : Taps count.
gameObject : Game object at touched (tileX, tileY)

N-taps at chess
```
board.on('gameobject' + tapsCount + 'tap' , function(tap, gameObject) {
})
```
or
```
gameObject.on('board.' + tapsCount + 'tap', function(tap) {
})
```
- 'gameobject' + tapsCount + 'tap' : 'gameobject1tap', 'gameobject2tap', 'gameobject3tap', etc ...
- 'board.' + tapsCount + 'tap' : 'board.1tap', 'board.2tap', 'board.3tap', etc ...
- tap : Tap behavior.
- gameObject : Game object at touched (tileX, tileY)

Press ¶

Press-start at any tile

board.on('tilepressstart', function(press, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

press : Press behavior.
tileXY : {x, y}

Press-end at any tile

board.on('tilepressend', function(press, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
});

press : Press behavior.
tileXY : {x, y}

Press-star at chess

board.on('gameobjectpressstart', function(press, gameObject) {
})

or

gameObject.on('board.pressstart', function(press) {
})

press : Press behavior.
gameObject : Game object at touched (tileX, tileY)

Press-end at chess

board.on('gameobjectpressend', function(press, gameObject) {
})

or

gameObject.on('board.pressend', function(press) {
})

press : Press behavior.
gameObject : Game object at touched (tileX, tileY)

Swipe ¶

Swipe at any tile

board.on('tileswipe', function(swipe, tileXY) {
    // var tileX = tileXY.x;
    // var tileY = tileXY.y;
    // var direction = swipe.direction;
});

swipe : Swipe behavior.
- swipe.direction : Integer number.
  - Quad grid : 0, 1, 2, 3, 4, 5, 6, 7.
  - Hexagon grid : 0, 1, 2, 3, 4, 5.
tileXY : {x, y}

Swipe at chess

board.on('gameobjectswipe', function(swipe, gameObject) {
    // var direction = swipe.direction;
})

or

gameObject.on('board.swipe', function(swipe) {
    // var direction = swipe.direction;
})

swipe : Swipe behavior.
- swipe.direction : Integer number.
  - Quad grid : 0, 1, 2, 3, 4, 5, 6, 7.
  - Hexagon grid : 0, 1, 2, 3, 4, 5.
gameObject : Game object at touched (tileX, tileY)

Grid points¶

Get an array of grid points at tile position (tileX, tileY).

var points = board.getGridPoints(tileX, tileY);
// var out = board.getGridPoints(tileX, tileY, out);

Draw grid polygon on graphics object
```
graphics.strokePoints(points, true);
```

Other properties¶

Scene
```
var scene = board.scene;
```