GUI for logging games of Settlers of Catan as you spectate
Clone or download
Pull request Compare This branch is 255 commits ahead, 2 commits behind fruitnuke:master.
rosshamish Merge pull request #2 from brooksandrew/master
adding --use_stdout command line argument
Latest commit 8b912c1 Jul 14, 2018
Failed to load latest commit information.
doc/gifs add v0.1.3 demo, update readme to point to gh-pages, readme is now fo… Feb 27, 2016
LICENSE merge from github Dec 31, 2013
Makefile Makefile: add "make demo" Jan 31, 2016
VERSION moving use_stdout to Game constructor Jun 29, 2018
requirements.txt explicit version v0.1.0, lock down dependency versions Feb 24, 2016 fix Feb 27, 2016 cherrypick numbers white background commit from tile image branch Jan 12, 2016 0.1.3: fix end turn on button press Feb 27, 2016 fix port trading Feb 12, 2016


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