Harbors

import { Aside } from ‘@astrojs/starlight/components’;

Problem

You want a hex board where a stretch of coastline opens into a deep-water harbor with two wooden piers and a few boats at anchor. The terrain should validate (no land tiles inside the water cluster, piers spanning the shore, navigable tiles for actors).

Snippet

import { createGameboardBuilder } from 'declarative-hex-worlds/gameboard';

const plan = createGameboardBuilder({
  seed: 'harbor-village-7',
  shape: { kind: 'rectangle', width: 8, height: 6 },
})
  .addHarbor({ center: { q: 4, r: 2 }, radius: 2 })
  .addBridge({ from: { q: 3, r: 1 }, to: { q: 4, r: 1 } })
  .addBuilding({ at: { q: 1, r: 4 }, kind: 'tavern' })
  .addBuilding({ at: { q: 2, r: 4 }, kind: 'home_A' })
  .build();

// plan.tiles + plan.placements are deterministic — same seed, same harbor.

What the library handles

Tile selection. addHarbor picks water + coast variants from the FREE manifest, rotates them to match neighbouring tile edges.
Connectivity validation. The bridge between {q:3,r:1} and {q:4,r:1} is rejected if those tiles aren’t adjacent.
Determinism. Same seed → same harbor layout across every machine.
Placement metadata. Every placement has a metadata.layoutFootprintSize + metadata.pieceRole for downstream rendering.

API cross-links

createGameboardBuilder — the entry point.
GameboardBuilder.addHarbor — harbor placement.
GameboardBuilder.addBridge — connector placement.
projectWorldToGameboardPlan — once you’ve spawned the plan into a koota world, project back to a GameboardPlan for serialization.