Transcribe games of Settlers of Catan for research purposes, replay purposes, broadcast purposes, etc.

pip install catan-spectator==0.1.4



A GUI for Mac and Windows for spectating and logging games of Settlers of Catan.

Other projects can read game logs and do useful things, i.e.

  • semi-automated tournaments: draws, matchups, stats, tiebreakers computed from game logs.
  • machine learning: game outcome prediction, AI development

Todos are listed below.

Author: Ross Anderson (rosshamish)






Clone, install dependencies:

$ git clone
$ cd catan-spectator
$ pip3 install -r requirements.txt

Basic usage:

$ python3

Full list of options:

$ python3 --help
usage: [-h] [--board BOARD] [--terrain TERRAIN] [--numbers NUMBERS]
               [--ports PORTS] [--pieces PIECES] [--players PLAYERS]
               [--pregame PREGAME]  [--use_stdout]

log a game of catan

optional arguments:
  -h, --help         show this help message and exit
  --board BOARD      string with space-separated short-codes for terrain and
                     numbers, e.g. 'w w h b s o w w b ... 2 None 9 3 4 6 ...'
  --terrain TERRAIN  random|preset|empty|debug, default random
  --numbers NUMBERS  random|preset|empty|debug, default preset
  --ports PORTS      random|preset|empty|debug, default preset
  --pieces PIECES    random|preset|empty|debug, default preset
  --players PLAYERS  random|preset|empty|debug, default preset
  --pregame PREGAME  on|off, default oncatan-spectator
  --use_stdout       write to stdout

Make targets:

- `make relaunch`: launch (or relaunch) the GUI
- `make logs`: cat the python logs
- `make tail`: tail the python logs
- `make`: alias for relaunch && tailFor a particular board layout:

File Format

catan-spectator writes game logs in the .catan format described by package catanlog.

They look like this:

green rolls 6
blue buys settlement, builds at (1 NW)
orange buys city, builds at (1 SE)
red plays monopoly on ore


Need to have

  • views documented
  • piece placing should be cancellable (via undo)
  • all actions should be undoable
  • ui+catanlog: save log file to custom location on End Game
  • ui: city-shaped polygon for cities
  • ui/ux improvements

Nice to have

  • board: random number setup obeys red number rule
  • ui+board+hexgrid: during piece placement, use little red x’s (at least in debug mode) on “killed spots”
  • ui+game+player+states: dev cards, i.e. keep a count of how many dev cards a player has played and enable Play Dev Card buttons if num > 0
  • ui+game+port+hexgrid: port trading, disable buttons if the current player doesn’t have the port. 4:1 is always enabled.
  • ui+port+hexgrid: port trading, don't allow getting or giving more or less than defined by the port type (3:1, 2:1).
  • ui+port: port trading, don’t allow n for 0 trades
  • ui: large indicator off what the current player is (and what the order is)
  • ui: cancelling of roads/settlements/cities while placing
  • ui: images, colors in UI buttons (eg dice for roll, )
  • [attempted, might be worse] ui: tile images instead of colored hexagons
  • ui: port images instead of colored triangles
  • ui: piece images instead of colored polygons
  • ui: number images instead of text (or avoid contrast issues otherwise)
  • ui+game+states+robber: steal dropdown has “nil” option always, for in case it goes on a person with no cards and no steal happens. Name it something obvious, don’t use an empty string.


Codebase originally forked from fruitnuke/catan, a catan board generator