# tikz-catan

`tikz-catan` is a LaTeX package that draws boards of *The Settlers of
Catan* as TikZ graphics: the 19-hex board with resources, number tokens,
ports, settlements, cities, roads, and the robber. Output is vector, in
the document's fonts; the only dependency is TikZ.

![Full board](gallery/full-board.png)

## Installation

Copy `tikz-catan.sty` into the same directory as the main `.tex` file (on
Overleaf, upload it to the project root) and load it with
`\usepackage{tikz-catan}`. For a system-wide install, place the file in
`TEXMFHOME/tex/latex/tikz-catan/` instead; `kpsewhich -var-value TEXMFHOME`
prints that location. TikZ ships with every standard TeX distribution, so
nothing else is needed.

## Quick start

```latex
\documentclass[tikz,border=8pt]{standalone}
\usepackage{tikz-catan}
\begin{document}
\begin{tikzpicture}
  \catanframe % sea frame
  \standardboard{\hexfull} % 19 hexes, full color
  \standardports{\port} % nine ports
  \robber{0}{0} % robber on the desert
\end{tikzpicture}
\end{document}
```

The same `tikzpicture` works inside any document class. `\standardboard`
and `\standardports` are a built-in legal example layout: correct tile and
token multisets, no adjacent 6/8 tokens, and a token-free desert.

## Usage

A board is written as data, one `{q}{r}{resource}{number}` entry per hex,
and passed to a renderer that decides how each hex is drawn; drawing the
same board in another style means changing only the renderer name. Here
`(q,r)` are axial hex coordinates (the manual contains a labeled map),
`resource` is one of `wood brick sheep wheat ore desert`, and number `0`
means no token (the desert). `\catanrows` builds the same list from five
comma-separated rows, so coordinates never have to be written by hand.

Highlighting means declaring hexes of interest, then rendering with
`\hexauto`: declared hexes draw in full color and all others gray out. A
declaration names one coordinate (`\hlhex{q}{r}`), every hex of one
resource (`\hlres{wheat}`), or every hex with a given dice number
(`\hlnum{6}`); a hex lights up if it matches any declaration, and
declarations reset outside the current `tikzpicture`. `\portauto` applies
the same rule to harbors. Pieces and ports are placed by naming a hex plus
one of its corners or sides. Each feature below is shown in the Gallery.

| Command | Purpose |
|---|---|
| `\standardboard{<renderer>}` | Built-in legal board through a callback |
| `\catanrows{<renderer>}{r1; r2; r3; r4; r5}` | Custom board from five comma-separated rows |
| `\hexfull{q}{r}{res}{n}` | Hex in full color: resource art and number token |
| `\hexdim{...}` | The same hex grayed out (backdrop for highlights) |
| `\hexshape{...}` | Outline only, no colors or numbers |
| `\hexprob{...}` | Neutral hex showing only the number token and its roll odds |
| `\hexauto{...}` | Full color if the hex is highlighted, grayed out otherwise |
| `\hlhex{q}{r}` / `\hlres{res}` / `\hlnum{n}` | Highlight by coordinate / resource / dice number |
| `\hexdots` | Mark the six corners of each hex (all 54 building spots) |
| `\settlement{q}{r}{corner}{col}` / `\city{...}` | Buildings on a vertex |
| `\road{q}{r}{side}{col}` | Road on an edge |
| `\port{q}{r}{side}{type}` | Harbor with piers and a ratio badge |
| `\portdim{...}` / `\portauto{...}` | Grayed-out harbor / full color only when its resource is highlighted |
| `\standardports{<port renderer>}` | The built-in layout's nine ports through a callback |
| `\robber{q}{r}` / `\catanframe` / `\catanlegend{y}` | Robber, sea frame, resource-color legend |
| `\vertexXY{q}{r}{corner}` / `\hexXY{q}{r}` | Low-level coordinates for annotations |
| `\CatanS` / `\cataniconsfalse` | Scale knob / resource-art toggle |

Corners are `N NE SE S SW NW`; sides are `NE E SE SW W NW` (side `E` runs
from corner `NE` to corner `SE`; a vertex can be addressed through any of
the up to three hexes that share it). Port types are `generic` (3:1) or a
resource name (2:1). Player colors `pred pblue porange pwhite` are
predefined, and every palette color is a redefinable `xcolor` name.
`\CatanS` is the hex circumradius in cm (default `1.05`);
`\cataniconsfalse` removes the resource art from hexes. User-supplied
boards and placements are not validated.

## Gallery

| ![Icons off](gallery/icons-off.png) | ![Silhouette](gallery/silhouette.png) |
|:--:|:--:|
| Resource art off (`\cataniconsfalse`) | Silhouette + 54 building spots (`\hexshape` + `\hexdots`) |
| ![Probability view](gallery/probability.png) | ![Opening position](gallery/opening.png) |
| Tokens and roll odds only (`\hexprob`) | An opening position (settlements, city, roads, robber) |
| ![Placement pair highlight](gallery/highlight.png) | ![Wheat economy](gallery/wheat-economy.png) |
| Highlighting chosen hexes (`\hlhex` + `\hexauto`) | All wheat hexes and the wheat port (`\hlres` + `\portauto`) |
| ![Custom board via row input](gallery/custom-board-rows.png) | ![Port distance annotation](gallery/port-distance.png) |
| A custom board from row input (`\catanrows`) | Annotation over a grayed board (`\hexdim` + `\vertexXY`) |

Source files for these are in [`examples/`](examples/); the full manual is
[`doc/tikz-catan-doc.pdf`](doc/tikz-catan-doc.pdf).

## License and attribution

MIT, see [`LICENSE`](LICENSE). All artwork is original flat geometry; no
official Catan art is reproduced. Not affiliated with Catan GmbH or Catan
Studio.