18xx map and tile generator

Will build 18xx assets in a deterministic way. Currently focussed on tile manifests, printable tile sheets and maps. The program takes a bunch of JSON files which dictate what it should do. It outputs to SVG files, scaled to fit A4 paper.

Hexagon space

Items within a hex are usually given in hexagon-space. This is a 3 dimensional space where the axis are at 60° to each other. An example of the axis is given below. Note that the orientation of the axis when the hexagons are oriented with horizontal edges differs from when the hexagons are oriented with vertical edges.

Instead of using coordinates in hexagon-space there are these position codes that can be used as a shortcut. North is the upper edge on a hexagon that has horizontal edges, it is the top left edge on hexagons that are oriented vertically.

• N: north edge
• NE: north east edge
• NW: north west edge
• S: south edge
• SE: south east edge
• SW: south west edge
• C: center of hexagon

When specifying coordinates a position code can be used by inserting {"Named": "<code>"} in the appropriate location. <code> is one of the above position codes. When specifying a coordinate in hexagon-space it done done by setting the coordinate to {"HexSpace": [<x>, <y>, <z>]} where <x>, <y> and <z> are floating point numbers. It is important to always include at least one decimal even when not required (so 10.0 instead of 10). Otherwise map18xx will not be able to understand it.

Modes

The program can operate in several different modes, they are described here.

Definitions

By default the program runs in 'definitions' mode, meaning that it will output all currently known tile definitions to a single file definitions.svg. The output contains a list of tiles without a colour that can be used to define other tiles in a game.

Game mode

Generates a tile manifest (lists each tile in the game and how many there are in total) and sheets with tiles to print and play and play a specific game of 18xx. It will also generate a map on which the tiles can be placed.

Command line arguments

A list of command line options is given below:

• -h and --help: display usage and help
• -V and --version: display version information and exit

Tile definitions

To build a game you first need to know what tiles are available. To simplify the specification of tiles there are tile definitions which cover possible configurations of tiles. These definitions include the tracks and stations on a tile, but they also dictate where revenue circles and other text on the tile goes. The tile definitions live in tiledefs/, there is one tile definiton per file. The filename (the part before the .json) determines how the tile can be refered to from other files. The contents of the file can include:

• An array called paths, defining the lines on the tile.
• An array called cities, defining the tokenable places on the tile.
• An array called stops, defining the non-tokenable revenue locations on the tile.
• A is_lawson parameter that makes the centre of a tile prettier.
• A code that allows further specifications to put large letters like B or NY on the tile.

The is_lawson parameter is a boolean that is false by default. It will draw the centre of a tile neatly when multiple lines meet there. The tile number is always drawn at the bottom right corner and has text_id = 0.

text_id keys

Before discussing what can be defined on a tile it is necessary to know how to specify text. To reduce the number of definitions required a consumer like a tile manifest can determine what text goes on the tile. The tile definition can specify where the text should go on the tile. To link these the consumer has to supply an array of strings, the definition can then pick the string to use from that array using the text_id (or similar) key. These IDs represent a 0-based index in the array of strings. The 0th element of the string array is reserved for the tile number. It is recommended to keep the id of the text_id field as small as possible, otherwise the consumer will have to specify a lot of empty strings. Multiple elements on a tile can use the same text_id, these will all use the same string.

paths array

To define the lines that run across a tile you can use the paths array. Each entry defines a single path. They usually look like

{
	"start": { "Named": "N" },
	"end": { "HexSpace": [0.1, 0.2, 0.3] },
	"is_bridge": true
}

There are several things here. First are the start and end keys, these define the start and end positions of a path respectively. These can take the position codes and hexagon-space coordinates that were defined in the 'Hexagon space' section.

Usually paths are drawn with level crossings. If paths cross but it is not allowed to switch there the is_bridge key can be used. Its default value is false. When set to true it will cause white lines to be drawn along the path it is specified on whenever it intersects with another path. It is only necessary to specify it on one of the crossing paths.

cities array

Cities which have a space for tokens can be defined using the cities array. Each city defines a new set of up to 4 token circles with its own revenue circle. It is currently not possible to rotate a city. A city can be defined as

{
	"circles": 2,
	"position": { "Named": "C" },
	"text_id": 1,
	"revenue_position": { "HexSpace": [0.0, 0.6, 0.0]
}

The first key is the circles key, this determines how many token spots are available. This can be any number between 1 and 4 inclusive, if another amount is specified then a red circle will be drawn to indicate that it is an invalid amount. The position key specifies where to put the city. Usually it doesn't make sense to use a position code other than { "Named": "C" } because the city would be drawn half off the tile.

To define where the revenue should be located the revenue_position key can be used. It is recommended to use a hexagon-space coordinate. Along with revenue_position there is a text_id which specifies which string ends up as the revenue number. It is suggested to set this to 1 for consistency. If different cities earn different revenue they should have a different text_id.

stops array

Small cities are always rendered as small black circles. In the future it may become possible to render them as dashes as well. A stop is defined as

{
	"position": { "HexSpace": [0.0, 0.0, 0.0] },
	"text_id": 1,
	"revenue_angle": 30
}

A stop must have these three fields, other fields are ignored. The position key defines where a stop is positioned. The text_id field specifies which string is used as the revenue. The revenue circle is always at the same distance from a stop. You can specify where it goes with the revenue_angle key. This is the angle in degrees at which the revenue circle should be drawn relative to the stop.

Tile code

Some tiles have a letter or code on them to restrict the upgrade path. Think of B and OO tiles in 1830 for example. The string that is used for this can be defined with code_text_id and its position is defined with the code_position key. The code_position can be a position code or a coordinate in hexagon-space.

Game definition

By using game for the mode option mode you can put the program into game mode that will generate all files to PnP a game. The game mode requires an additional NAME parameter; this is the name of the game to generate files for. The available games are the sub directories in the games directory. Thisoutputs a tile manifest in manifest.svg and a list of files called NAME-sheet-x.svg where NAME is the name of the game and x is a sequence number. Each of these sheet files can be directly printed on A4 paper. The manifest file contains an example of each tile in the game together with a number that indicates how many of those tiles are available during play.

Tile manifest

A tile manifest consists of a list of tiles and a list of how often this tile can be used in the game. The definition of a usable tiles is given by the tiles array. A single entry looks like

{
	"color": "green",
	"base_tile": "52",
	"text": [
		"59",
		"40",
		"OO"
	]
}

There are several elements here. The first is the color key, this defines which color the tile is. Usual picks are yellow, green, russet and grey. The next key is base_tile which specifies which tile definition is used. This can be any JSON file in the tiledefs/ directory. Finally is the text array, it specifies the string that the text_ids in the tile definition refer to. The first entry is always the displayed tile number, this does not have to be the same as the base_tile key. The meaning of other entries depends on what the tile definition used as text_id.

To specify the amounts available of each tile there is an amounts array, it looks like

"amounts": {
	"1": 1,
	"2": 1,
	"3": 2,
	"4": 2,
	"7": 4
}

It has a number of string keys, these are the tile number that were defined in the first element of a tile's text array. After the colon is the amount of tiles that are available for placement during the game.