** Updated Dec 2020 **
- Now Uses ES6 Modules
HexAPI is a simple javascript API for for hexagonal games or applications. It is an adaptation from the the articles written by Amit Patel on the subject. Read more here : http://www.redblobgames.com/grids/hexagons/
https://www.snowpack.dev/tutorials/getting-started
-
npm install hexapi
-
//in index.js import {Grid, Engine} from "hexapi"
https://nodejs.org/api/packages.html#packages_modules_packages
-
// package.json { "name":"you_project_name", "type":"module", ... }
Without additional work, this will requre all packages to use esm modules and will cause some older legacy packages to not work.
-
npm install hexapi
-
import {Grid,Engine} from "hexapi";
-
cd ~/project/libs/ git clone https://github.com/cefleet/hexAPI.git
- Clone repository into your project.
- Import needed components
import {Grid,Engine} from "./libs/hexapi/HexApi.js";
All Hexes are an object (or Map) with q,r,s keys.
let aHex = {q:2,r:2,s:3}
All Points are an object (or Map) with x,y keys.
let aPoint = {x:10,y:20}
- The Grid will supply x,y coordinates for hexes and can find a hex based on an x,y coordinates.
- The grid will also supply a 'map' of the hexes that fit within the grid parameters.
- Importing the Grid returns a function that will need to be called in order to use the grid.
- Grid MUST be called on order to create the grid and use any of the grid functions.
- The options argument is an object that provides settings for the grid.
const myGrid = Grid(options);
console.log(myGrid.map);
//or if you prefer the destructing method
const {map,hexAtPoint,pathTo} = Grid(options);
-
hexSize - Object or Map with an x and y keys that are both numbers. These numbers are the units (often pixels) to determine the size of the hex.
- defult value - {x:30,y:30}
-
origin - Object or Map with an x and y keys that are both numbers. This is how far from 0,0 that the map is to start. Used mostly for when a canvas is only rendering a section of the map.
- default value - {x:0,y:0}
-
type - String of either 'pointy' or 'flat' . This determines the orietation of the hexes. Pointy has the top part as a corner and flat has the top part be a horizontal line.
- default value - 'pointy'
-
rows - Integer of how many rows of hexes the grid will make.
- default value - 10
-
cols - Integer of how many columns of hexes the grid will make.
- default value - 10
//example
const myGrid = Grid({
hexSize:{x:10,y:10},
type:'flat'
});
//origin, rows, cols will all use the defaults.
- The prefered way is to use the descructruing syntax to use only the needed functions.
const {map,cornersOfHex,pathTo} = Grid({hexSize:{x:10,y:10},type:'flat'});
- Array of all of the hexes that the grid created based on the rows and cols suppied when the Grid function was called.
Returns - Hex or undefined of the hex the point supplied is within. If the optional second argument 'onlyInMap' is set to true, and the point is outside of the grid, then it would return undefined.
- point is an object or Map that has keys x and y.
let foundHex = hexAtPoint({x:100,y:100})
Returns - Point or undefined of the center point of a hex. If the optional second argument 'onlyInMap' is set to true, and the hex is outside of the grid, then it would return undefined.
let hexCenterPoint = centerOfHex(hex);
Returns - Array of Points or undefined - of the 6 corners of the supplied hex. If the optional second argument 'onlyInMap' is set to true, and the hex is outside of the grid, then it would return undefined.
let corners = cornersOfHex(hex);
Returns - Array of Hexes - from the start hex to the end hex.
- This function used an astar path finding algorythim if there are obstacles found in the straightest path or if the straightest path would include hexes outside of the grid.
- Obstacles is an optional argument that is an array of hexes.
- This functions relies on the grid map and will never return items outside of the grid.
let thePath = pathTo(startHex,endHex,obstacles);
Resolves - Array of Hexes - from the start hex to the end hex.
- This is a promise wrapper around the pathTo function.
const usePath = (hexes) =>{
console.log(hexes)
}
pathToPromise(startHex,endHex,obstacles)
.then(usePath)
- The Engine component handles all of the math directly related to the hexes. It operates independantly of size or orientation of the grid.
- Importing the Engine returns an object of the needed functions.
- Normally these values are provided from the grid, but the math is valid without a grid.
- If a grid is being used, the values supplied by the engine can be out of the limit of the grid map. Validation will need to be done to make sure the values are found in the grid.
//example
const {getAllNeighbors} = Engine;
console.log(getAllNeighbors({q:2,r:2,s:3}))
/*
//output
[ {q: 3, r: 2, s: 2},
{q: 3, r: 1, s: 3},
{q: 2, r: 1, s: 4},
{q: 1, r: 2, s: 4},
{q: 1, r: 3, s: 3},
{q: 2, r: 3, s: 2}
]
*/
Returns - Array of connected hexes between two different hexes.
let arrayOfHexes = getHexLineBetweenHexes(hexA,hexB)
Returns - Number representing how many hexes are between the two different hexes.
let numberOfHexes = getDistanceBetweenHexes(hexA,hexB);
Returns - Hex of the connected hex at the specified direction.
- direction is a Number between 0-5. Starting with 0 going counter-clockwise. 0 is the hex directly right of the hex if it is pointy grid and lower right if it is a flat grid.
//flat
let upHex = getNeighborAtDirection(hex, 2);
//pointy
let leftHex = getNeighborAtDirection(hex,3);
Returns - Hex of the hex going out from the specified corner.
- direction is a Number between 0-5. Starting with 0 going counter-clockwise. 0 is the corner directly right of the hex if it is flat grid and upper right if it is a pointy grid.
//flat
let rightHex = getNeighborAtDiagonalDirection(hex, 0);
//pointy
let lowerLeftHex = getNeighborAtDiagonalDirection(hex,3);
Returns - Array of all of the connected hexes. It will always return an array with 6 items even if the items are outside of a grid map.
let neighbors = getAllNeighbors(hex);
Returns - Array of all of the hexes going out from the corners of the supplied hex. It will ways return an array with 6 items even if the items are outside of a grid map.
let cornerNeighbors = getAllDiagonalNeighbors(hex);
Returns - Hex at the specified distant and direction.
- direction is a Number between 0-5. Starting with 0 going counter-clockwise. 0 is the hex directly right of the hex if it is pointy grid and lower right if it is a flat grid.
- distance is how many hexes away the target he is.
//pointy map
let right4away = getHexAtDistanceAndDirection(hex,4,0)
Returns - Array of hexes at the specified distance. Essentally it returns a ring of hexes around the given hex.
let ringAtTwo = getAllHexesAtDistance(hex,2);
Returns - Array of all of the hexes within the distance supplied.
let allHexesAround = getAllHexesWithinDistance(hex,3);