honeycomb-grid

Many methods that accept a single Traverser also accept an array of traversers. This allows you to compose complex paths by chaining simpler ones together.

When using an array of traversers:

1. Sequential Execution: The traversers are executed in order.
2. Implicit Continuity: If a traverser (like line()) does not specify a start coordinate, it will automatically start from where the previous traverser in the array left off.
3. Default Start: If the first traverser in the array does not specify a start, it defaults to [0, 0].

const grid = new Grid(Hex, rectangle({ width: 5, height: 5 }))

// Creates a square outline by chaining lines
const squareOutlineTraverser = [
  line({ direction: Direction.E, length: 4 }), // Starts at [0,0]
  line({ direction: Direction.S, length: 3 }), // Starts where previous ended
  line({ direction: Direction.W, length: 3 }),
  line({ direction: Direction.N, length: 3 }),
]

grid.traverse(squareOutlineTraverser)

Honeycomb supports four coordinate systems for representing hexagonal positions. While the library uses axial or cube coordinates internally, you can work with any of these types via the HexCoordinates union type:

1. Cube: The most explicit type. It uses three coordinates { q, r, s } which must always add up to 0.
2. Axial: A simplified version of cube coordinates using only { q, r }. The s coordinate is redundant.
3. Offset: Uses { col, row } coordinates. The specific mapping depends on the hex's offset setting (e.g., even-q, odd-r).
4. Tuple: A terse representation using arrays, such as [q, r] or [q, r, s].

Important Note on Hex Properties: When using a Hex instance, you can access all coordinate types as properties. However, only cube coordinates are settable. Offset coordinates are read-only and will throw a TypeError if you attempt to modify them directly.

const hex = new Hex([1, 2])

// Accessing properties
hex.q   // 1 (Cube)
hex.r   // 2 (Cube)
hex.s   // -3 (Cube)
hex.col // 2 (Offset)
hex.row // 2 (Offset)

// Setting coordinates
hex.q = 2 // Allowed (but ensure q + r + s === 0)
hex.col = 2 // ❌ TypeError: Offset coordinates are read-only

A Traverser is a function used to iterate over hexes in a grid. It is designed to be composable, meaning it can receive a cursor from a previous traverser to allow for continuous traversal across combined patterns.

To implement a Traverser, your function must follow this signature:

1. Accept a createHex function (a factory that produces Hex instances).
2. Accept an optional cursor (the HexCoordinates where the previous traverser left off).
3. Return an Iterable<Hex> (such as an Array or a Generator).

When creating custom traversers, use generics <T extends Hex> to allow your traverser to return specialized hex subtypes.

type Traverser = (
  // hex factory: a function that creates a hex
  createHex: (coordinates?: HexCoordinates) => Hex,
  // cursor: so that the next traverser knows where to continue traversing
  cursor?: HexCoordinates,
) => Iterable<Hex>

Honeycomb does not include a built-in renderer. To render a grid using SVG.js, iterate over the Grid instance and use the hex.corners property to generate SVG polygon points.

Note that by default, hex coordinates are centered. If you prefer the origin to be the top-left corner of the hex's bounding box, set origin: 'topLeft' in the defineHex configuration.

import { SVG } from '@svgdotjs/svg.js'
import { defineHex, Grid, rectangle } from 'honeycomb-grid'

// Set origin to 'topLeft' if you want coordinates relative to the bounding box
const Hex = defineHex({ dimensions: 30, origin: 'topLeft' })
const grid = new Grid(Hex, rectangle({ width: 10, height: 10 }))

const draw = SVG().addTo('body').size('100%', '100%')

grid.forEach(renderSVG)

function renderSVG(hex: Hex) {
  const polygon = draw
    // create a polygon from a hex's corner points
    .polygon(hex.corners.map(({ x, y }) => `${x},${y}`))
    .fill('none')
    .stroke({ width: 1, color: '#999' })

  return draw.group().add(polygon)
}

Since defineHex() returns a standard JavaScript class, you can extend it to add custom logic or data.

Best Practices

• Methods and Getters/Setters: Define these directly on the class. They exist on the prototype and are shared across all hex instances, which is performant.
• Instance Properties: Use these for data unique to a specific hex instance.

TypeScript Tip

If using strict mode, you may need to use a definite assignment assertion (!) or make properties optional (?) to satisfy the compiler when properties are initialized via custom logic rather than a constructor.

class CustomHex extends defineHex({ dimensions: 30, origin: 'topLeft' }) {
  get prototypeProp() {
    return `this property won't be present in the instance, only in the prototype`
  }

  // this property is present in the instance
  instanceProp!: string

  // methods always exist in the prototype
  customMethod() {}
}

To render a honeycomb grid using PixiJS, iterate over the Grid and use the hex.corners array to draw shapes. Since hex.corners is an array of {x, y} objects, it is directly compatible with PIXI.Polygon.

As with SVG, you can adjust the origin in defineHex (e.g., origin: 'topLeft') to change how coordinates are calculated relative to the hex's bounding box.

import * as PIXI from 'pixi.js';
import { defineHex, Grid, rectangle } from 'honeycomb-grid'

const Hex = defineHex({ dimensions: 30, origin: 'topLeft' })
const grid = new Grid(Hex, rectangle({ width: 10, height: 10 }))

const app = new PIXI.Application({ backgroundAlpha: 0 })
const graphics = new PIXI.Graphics()

document.body.appendChild(app.view)
graphics.lineStyle(1, 0x999999)

grid.forEach(renderHex)
app.stage.addChild(graphics)

function renderHex(hex: Hex) {
    // PIXI.Polygon happens to be compatible with hex.corners
    graphics.drawShape(
        new PIXI.Polygon(hex.corners)
    )
}