catan-gen

catan-gen is a fully convergent map creation app for Catan. It is written in C++ and uses libadwaita to provide a UX that is friendly on both desktop and mobile devices.

Dependencies

• Unix-like system (tested: Gentoo, Mobian on PinePhone, Mac OS Monterrey)
• GTK4 >= 4.6.0
• libadwaita >= 1.0.0
• Eigen >= 3.4
• Cairo >= 1.14
• jsoncpp >= 1.9
• Boost > 1.74

Obtaining catan-gen

catan-gen is available as a source tarball at http://proj.penguindevelopment.org/catan-gen/. Direct link to the latest version.

Installation follows the usual configure/make/make install procedure.

Using catan-gen

Upon launching catan-gen, you will be presented with a simple UI:

No map has been generated yet, since the app obviously can't divine what size of map you want; you can set that on this page. A radius of 0 corresponds to a single tile, a radius of 1 adds the 6 nearest-neighbour tiles around it, and so on. Press the Generate button and enlarge the window to find a map filled with water:

Before going into the details, let's have a look at the toolbar:

From left to right, these buttons are zoom out, zoom in, terrain paint mode, paint tile type, roll tile types, roll numbers, clear numbers and clear tile types. The zoom buttons are self-explanatory. Terrain paint mode is a toggle button, and is enabled by default. In this mode, you can draw land areas directly onto your map, simply by pressinging the tiles. Paint tile type (the downwards arrow) lets you choose what to draw, and is set to "Unspecified" by default. Press a few tiles to draw your map:

If you want to switch a tile back to water, simply press it again. Once you're satisfied with the shape of your map, it is time to roll tile types, which changes the unspecified tiles into resources. But before you press roll tile types, press the Tileset button in the titlebar. The page that appears allows you specify how many tiles of each resource you want to generate.

For each resource, you can specify the minimum and maximum number of tiles you want to have. The current number is also listed. Colour-blind users may also want to adjust the colour of each tile type. (N.B. this list can scroll; on desktops, use the mouse scroll wheel or the scrollbar that appears when hovering; on touchscreen devices, just drag to scroll.) When you are satisfied, go back to the map page and press the roll tile type button (the die) to populate your map:

If you don't have enough unspecified tiles to satisfy the minimum tile amounts listed on the tileset page, you will be met with an error instead. If you are unhappy with the generated map, you can still freely change the tiles by pressing them. Alternatively, you can press clear tile types to wipe every resource back to unspecified (N.B. this includes tiles you have manually set, so be careful with this button). Next, you can auto-generate the numbers that go on each resource, simply by pressing roll numbers (the circled 8).

Clear numbers removes them again, if you are unhappy. If you want to change a single number, you will need to turn off terrain paint mode. Once turned off, pressing a tile will open an overlay that lets you set the type and number directly:

(Note that the clicked tile has been highlighted in green.) Press the checkmark button on the right-hand side to accept the changes, or the cross on the left-hand side to discard them.

NOTE: unfortunately, selecting tile types and numbers from this interface can be unreliable due to GTK bug 2877. If the app refuses to accept your selection, you can use the keyboard to navigate to the drop-down and select an entry. Sadly, this does not appear to work with Squeekboard, so you will need a physical (Bluetooth or USB) keyboard on Phosh-based devices.

When you are completely satisfied with your map, you can export it from the hamburger menu (top-left corner). "Export SVG" produces a vector graphic representation identical to the one you see on-screen. "Export JSON" produces a textual representation of the map, which can be reimported at a later time. Of course, you can also generate a new map, which brings you back to the startup view.

Notes

Although catan-gen currently suffices at basic mapping, some new features are currently planned. Internationalisation will be relatively simple to add to the app as-is. A more complex feature --- the most complex one currently planned --- is the support of custom tile types, which would include the ability to import and export the tile set via JSON.

Currently, generated maps are always hexagonal, which can waste large swaths of space if a different shape is required. It is already possible to manually create non-hexagonal maps by importing a JSON file as a template, e.g. by exporting a blank hexagonal map and editing the JSON file to remove unwanted tiles. However, this is subject to an important symmetry constraint: the centre of the map must correspond to the centre of tile (0, 0). Failure to meet this requirement currently makes it impossible to correctly interpret mouse clicks/finger taps on the map. Since this is not trivial to resolve and the work-around is inconvenient but not prohibitively complicated, generating non-hexagonal maps most likely will not be supported from within the app.

Allowing the map to be extended or shrunk without discarding it completely is relatively simple and will most likely be included in the next non-bugfix update.

Automatic generation of a map outline is the final complex feature currently planned. This would most likely also incorporate the placement of harbours, which are not currently included.

Bugs and feedback

Report bugs via email at bugs[at]proj[dot]penguindevelopment[dot]org.

Send your feedback to feedback[at]proj[dot]penguindevelopment[dot]org.