@vanduo-oss/hex-grid

Standalone VdHexGrid package for canvas-based hex grids.

Install

pnpm add @vanduo-oss/hex-grid

Usage

import { VdHexGrid } from '@vanduo-oss/hex-grid';

const grid = new VdHexGrid({
  element: document.getElementById('hex-demo-container'),
  canvas: document.getElementById('hex-demo'),
  size: 30,
  width: 15,
  height: 10,
  rotation: 0
});

Optional Utility Import

import { hexToPixel, pixelToHex, hexDistance } from '@vanduo-oss/hex-grid/hex-math';

API

Constructor

new VdHexGrid({ element, canvas, size, width, height, rotation })

Option	Type	Default	Description
element	HTMLElement	required	Container element
canvas	HTMLCanvasElement	auto-created	Canvas element
size	number	30	Hex radius in pixels
width	number	10	Grid width in hexes
height	number	10	Grid height in hexes
rotation	number	0	Grid rotation in radians

Methods

• on(event, callback) — Subscribe to events (select, zoom, pan)
• setSize(size) — Change hex radius
• setDimensions(width, height) — Change grid dimensions
• setRotation(rotation) — Rotate the grid
• reset() — Reset to defaults
• resetView() — Reset pan and zoom
• zoomIn() / zoomOut() — Adjust zoom
• fillRandom() — Fill hexes with random colors
• getHex(q, r) — Get a hex by coordinates
• getAllHexes() — Get all hexes
• setHexFill(q, r, color) — Set hex fill color
• setHexTerrain(q, r, terrainType) — Set hex terrain
• getHexTerrain(q, r) — Get hex terrain
• generateRandomTerrain() — Randomize all terrains
• getValidMoves(q, r, movementPoints) — Get reachable hexes
• getPath(startQ, startR, endQ, endR) — BFS pathfinding
• hexDistance(q1, r1, q2, r2) — Distance between hexes
• setHexData(q, r, data) / getHexData(q, r) / clearHexData(q, r) — Custom data
• exportTerrainData() / importTerrainData(data) — Serialization
• setCustomRender(callback) / clearCustomRender() — Per-hex rendering hooks

Terrain Types

GRASSLAND, PLAINS, DESERT, TUNDRA, SNOW, MOUNTAIN, OCEAN, COAST

Hex Math Utilities

import {
  hexToPixel, pixelToHex, axialRound, rotatePoint, unrotatePoint,
  getHexCorners, getAdjacentHexes, hexDistance, isPassable,
  getMovementCost, getTerrainYields, getTerrainColor,
  TerrainType, TERRAIN_COLORS, DEFAULT_TERRAIN_COLOR,
  TERRAIN_YIELDS, TERRAIN_MOVEMENT_COSTS
} from '@vanduo-oss/hex-grid/hex-math';

License

MIT