DOCSEARCHbyAlgolia
Submit Docs

Honeycomb API v4.1.5

website·Indexed 32 days ago

https://abbekeultjes.nl/honeycomb/

A library for hexagonal grid manipulation, providing core structures for managing hexes, grids, and traversers. It includes technical specifications for coordinates (Cube, Axial, Offset), grid iteration, spatial operations, and (de)serialization using JSON.

Tokens
27.6K
Snippets
191
Records
285
Agent score
55%

What's inside Honeycomb

  1. Understand and use Traversers in Honeycomb

    A Traverser is a function that produces hexes in a specific order. When passed to a grid's traverse() method, it allows you to iterate over a subset of hexes. A traverser accepts a hex factory (to create hexes) and an optional cursor (to track the current position) and returns an iterable of hexes.
    type Traverser = (
  createHex: (coordinates?: HexCoordinates) => Hex,
  cursor?: HexCoordinates,
) => Iterable<Hex>

  2. Understand Honeycomb coordinate system types

    Honeycomb supports four types of coordinates for hexagonal grids:

    1. Cube: Explicit coordinates where all three values (q, r, s) must sum to 0. Example: { q: 1, r: 2, s: -3 }.
    2. Axial: A simplified version of cube coordinates omitting the redundant s coordinate. Example: { q: 1, r: 2 }.
    3. Offset: Coordinates based on the hex's offset setting. Example: { col: 1, row: 2 }.
    4. Tuple: A terse representation using arrays, supporting either axial [q, r] or cube [q, r, s] formats. Example: [1, 2].

    Internally, Honeycomb primarily uses axial or cube coordinates. Points (e.g., { x: 1, y: 2 }) are used for geometric positions, such as the corners property of a hex.

  3. Understand Honeycomb coordinate systems

    Honeycomb supports four types of coordinates for hexagonal grids:

    1. Cube: Explicit coordinates where all three values must sum to 0. Example: { q: 1, r: 2, s: -3 }.
    2. Axial: A simplified version of cube coordinates omitting the s coordinate. Example: { q: 1, r: 2 }.
    3. Offset: Coordinates based on the hex's offset setting. Example: { col: 1, row: 2 }.
    4. Tuple: A terse representation using arrays. Example: [1, 2] (axial) or [1, 2, -3] (cube).

    Internally, Honeycomb primarily uses axial or cube coordinates. Points (e.g., { x: 1, y: 2 }) are also used for geometric positions, such as hex corners.

  4. HexTraversable<T> Interface Overview

    The HexTraversable<T> interface extends HexStore<T> and is implemented by the Grid class. It provides a set of methods to manage hexagonal cells and perform traversal operations across a grid. The type parameter T must extend the Hex class.

  5. Use HexIterable<T> for hexagonal cell collections

    The HexIterable<T> interface is used for collections of hexagonal cells where the type T extends the Hex class. It extends Iterable<T> and HexStore<T>, and is implemented by the Grid class. It provides a set of functional-style methods to manipulate and query hexagonal data.

  7. HexIterable<T> Interface Overview

    The HexIterable<T> interface is a specialized collection for hexagonal grid elements where T must extend the Hex class. It extends both Iterable<T> and HexStore<T>, and is implemented by the Grid class. It provides functional-style methods (filter, map, reduce) and store-like access (getHex, hasHex) for managing hexes.

  8. Initialize a Grid instance

    The Grid<T> class manages a collection of hexagonal cells. It can be instantiated in several ways depending on whether you have a hex class, existing hexes, or another grid instance.
    // 1. Initialize with just a Hex constructor
const grid = new Grid(MyHexClass);

// 2. Initialize with a Hex constructor and specific traversers
const gridWithTraversers = new Grid(MyHexClass, traverser);

// 3. Initialize with a Hex constructor and a set of coordinates or Hex instances
const gridWithHexes = new Grid(MyHexClass, [{ q: 0, r: 0 }, { q: 1, r: 0 }]);

// 4. Clone an existing grid
const clonedGrid = new Grid(existingGrid);

  9. Add custom properties and methods to a Hex class

    Since defineHex() returns a class, you can extend it to add domain-specific properties and methods.

    • Prototype properties/methods: Use getters or standard methods for logic shared across all hexes.
    • Instance properties: Use these for data specific to a single hex instance.

    Note: If using TypeScript with strictPropertyInitialization enabled, use the optional operator (?) or the definite assignment assertion (!) for instance properties to avoid compiler errors.

    class CustomHex extends defineHex({ dimensions: 30, origin: 'topLeft' }) {
  // Shared in prototype
  get prototypeProp() {
    return `Shared property`;
  }

  // Specific to each instance
  instanceProp?: string;

  customMethod() {
    // custom logic
  }
}

  10. Add custom properties and methods to Hexes

    Since defineHex() returns a class, you can extend it to add domain-specific properties or methods.

    • Prototype properties: Use getters or methods for shared logic. These are shared by all hex instances for performance.
    • Instance properties: Use these for data specific to a single hex (e.g., unique IDs or state).

    TypeScript Note: If strictPropertyInitialization is enabled, use the definite assignment assertion (!) or make the property optional (?) to avoid initialization errors.

    class CustomHex extends defineHex({ dimensions: 30, origin: 'topLeft' }) {
  // Shared in prototype
  get prototypeProp() {
    return `shared property`;
  }

  // Specific to each instance
  instanceProp!: string;

  // Shared method
  customMethod() {
    // logic here
  }
}

  11. Convert between different coordinate types

    Honeycomb provides utility functions to convert various coordinate formats into Cube coordinates or other types. Functions like toCube(), offsetToCube(), and pointToCube() require the Hex.settings object to perform calculations correctly.
    // Convert various types to Cube coordinates
import { toCube, offsetToCube, pointToCube, tupleToCube, hexToOffset, hexToPoint } from 'honeycomb';

toCube(Hex.settings, [1, 2]);             // { q: 1, r: 2, s: -3 }
toCube(Hex.settings, { col: 1, row: 2 }); // { q: 0, r: 2, s: -2 }
offsetToCube(Hex.settings, { col: 1, row: 2 }); // { q: 0, r: 2, s: -2 }
pointToCube(Hex.settings, { x: 10, y: 20 });     // { q: -1, r: 13, s: -12 }
tupleToCube([1, 2]);                             // { q: 1, r: 2, s: -3 }

// Convert from a Hex instance
const Hex = defineHex({ dimensions: 30 });
const hex = new Hex([1, 2]);

hexToOffset(hex); // { col: 2, row: 2 }
hexToPoint(hex);   // { x: 103.923..., y: 90 }