Board
Introduction¶
Core object of Board system.
- Author: Rex
- Member of scene
Live demos¶
- Touch events
- Get tileXY at direction
- Line to tileXY array
- Triangle to tileXY array
- Ellipse to tileXY array
Usage¶
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 tilesheight
: 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);
- Get
- Height : Board height in tiles
- Get
var height = board.height;
- Set
board.setBoardHeight(height);
- Get
Add chess¶
board.addChess(chess, tileX, tileY, tileZ, align);
chess
: A game object.tileX
,tileY
,tileZ
: Tile position.align
: Settrue
to align (i.e. set position) chess to grid (tileX, tileY). Default istrue
.
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 objectdestroy
: Settrue
to desrtoy chess object.
- Remove chess at (tileX, tileY, tileZ) from board
board.removeChess(null, tileX, tileY, tileZ, destroy);
tileX
,tileY
,tileZ
: Tile positiondestroy
: Settrue
to desrtoy chess object.
- Remove all chess
board.removeAllChess(destroy);
destroy
: Settrue
to desrtoy chess object.
Move chess¶
board.moveChess(chess, toTileX, toTileY, toTileZ, align);
chess
: A game objecttoTileX
,toTileY
,toTileZ
: Target tile positionalign
: Settrue
to align (i.e. set position) chess to grid (tileX, tileY).
Swap chess¶
board.swapChess(chessA, chessB, align);
chessA
,chessB
: Game objectsalign
: Settrue
to align (i.e. set position) chess to grid (tileX, tileY).
Chess -> tile position¶
var tileXYZ = board.chessToTileXYZ(chess);
chess
: A game objecttileXYZ
:{x,y,z}
ornull
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)
or
var out = board.tileXYArrayToChessArray(tileXYArray); // var out = board.tileXYArrayToChessArray(tileXYArray, out);
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
, orx+
: Increasing x, increasing y.1
, orx-
: Decreasing x, increasing y.2
, ory+
: Increasing y, increasing x.3
, ory-
: 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 istrue
.
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 lineout
: 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 shapeout
: 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 shapeout
: 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 shapeout
: 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 shapeout
: 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 shapeout
: 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 betweenface - (cone/2)
toface + (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
.
- Quad grid :
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.
- Quad grid :
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 betweenface - (cone/2)
toface + (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.
- Quad grid :
Opposite direction¶
var direction = board.getOppositeDirection(tileX, tileY, direction);
Angle snap to direction¶
var direction = board.angleSnapToDirection(chess, angle);
chess
: Chess object, or tileXY, orundefined
.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
.
- Quad grid :
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. Retrunnull
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'
.
- Array of numbers,
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
: Returnnull
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. Retrunnull
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'
.
- Array of numbers,
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
: Returnnull
if these 2 chess are not neighbors.
- Are 2 chess neighbors?
var areNeighbor = board.areNeighbors(chessA, chessB);
areNeighbor
: Returntrue
ifchessA
andchessB
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 is1
.end
: End distance. Default value is1
.step
: Step. Default value is1
.
- Number,
3
. - Array of numbers,
[2, 3, 5]
: Array of distances.
- JSON : Range of distances.
out
:- A single tile position, if
distance
is a number. - Tile position
{x, y}
array, ifdistance
is a JSON or an array.
- A single tile position, if
- 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'
.
- Array of numbers,
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}
, returnnull
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
propertyvar 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 pointertileXY
:{x, y}
- Pointer down at chess
or
board.on('gameobjectdown', function(pointer, gameObject) { })
gameObject.on('board.pointerdown', function(pointer) { })
pointer
: Touch pointergameObject
: 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
or
board.on('gameobjectup', function(pointer, gameObject) { })
gameObject.on('board.pointerup', function(pointer) { })
pointer
: Touch pointergameObject
: 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
or
board.on('gameobjectmove', function(pointer, gameObject) { })
gameObject.on('board.pointermove', function(pointer) { })
pointer
: Touch pointergameObject
: 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
or
board.on('gameobjectover', function(pointer, gameObject) { })
gameObject.on('board.pointerover', function(pointer) { })
pointer
: Touch pointergameObject
: 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
or
board.on('gameobjectout', function(pointer, gameObject) { })
gameObject.on('board.pointerout', function(pointer) { })
pointer
: Touch pointergameObject
: 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
or
board.on('gameobjecttap', function(tap, gameObject) { // var tapsCount = tap.tapsCount; })
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
or
board.on('gameobject' + tapsCount + 'tap' , function(tap, gameObject) { })
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
or
board.on('gameobjectpressstart', function(press, gameObject) { })
gameObject.on('board.pressstart', function(press) { })
press
: Press behavior.gameObject
: Game object at touched (tileX, tileY)
- Press-end at chess
or
board.on('gameobjectpressend', function(press, gameObject) { })
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
or
board.on('gameobjectswipe', function(swipe, gameObject) { // var direction = swipe.direction; })
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;