Scenario format


Forum discussion thread

Extended heightmap format

The extended heightmap format aims to store most of the information of a scenario (terrain, water, towns, etc) in a NewGRF agnostic way. Since company property is not intended to be part of scenarios, this format will not be including it. Depending on the information included in the extended heightmap it will be possible to scale the extended heightmap to different sizes or it will be fixed.

NOTE: Unless mentioned otherwise, all properties are optional.

An extended heightmap is distributed as a tar file. The file includes the following parts:


In an extended heightmap, we have two different types of scaling.

Size scaling

The extended heightmap has multiple files that include information about the map. Some of these files are called "scalable in size". This means that OpenTTD is able to scale their size to a desired OpenTTD size without a (big) loss of information. As long as the extended heightmap only contains files that are scalable in size, each one of them can have a different size. OpenTTD will just scale all of them to the same size, as selected by the user when generating the map.

If an extended heightmap contains one or more files that cannot be scaled in size, all files must use the same size, and it must be a valid OpenTTD map size. If these conditions are not fulfilled, OpenTTD will not be able to load the extended heightmap.

Height scaling

Height scaling is completely independent from size scaling. It always takes place, no matter if the files that form the extended heightmap are size scalable or not.

All heights in an extended heightmap are defined between 0 and a property called "max_height". The extended heightmap includes two properties that define the desired lower height and upper height of the resulting OpenTTD map. They are called "min_desired_height" and "max_desired_height". When OpenTTD generates a game from the extended heightmap version, it will scale all heights from the extended heightmap interval ([0, max_height]) to the desired OpenTTD height interval [min_desired_height, max_desired_height].

Metadata file

The metadata file must be called "metadata.txt".

Extended heightmap section

The first section includes information about the extended heightmap itself.

Layer sections

All included layers must have their own section in the metadata file. The [height_layer] section is compulsory, because all extended heightmaps must have a height layer to be usable. Other layers are optional. Each layer section can have a file property that indicates which file contains the layer date if not included, a default file name will be used. Layers can also have extra properties, depending on their type. Note that even if a layer has no extra properties and uses the default file name, it must still have an empty section. Otherwise OpenTTD will ignore the layer.

Object file sections

Each object file has its own section. Their file property is also optional; if not included OpenTTD will search for the default file name. All object files must have "width" and "height" properties in their metadata section. These properties define the size of the rectangle in which their objects are placed. These properties are mandatory.

Example of metadata file









Each layer stores information for each one of the points in the map in PNG format. The different types of layers are described below.

Height layer

Metadata section: [height_layer]

Default filename: height.png

Size scalable: Yes

Extra properties:

Height layers are 8 bit grayscale images that describe the height of each point of the map as a number in the [0, 255] interval. Any heights above max_height will be clamped to max_height when generating maps.

Terrain layer

Metadata section: [terrain_layer]

Default filename: terrain.png

Size scalable: Yes

The terrain layer is a paletted PNG image that stores information about the terrain type of each one of the tiles.

Water layer

Metadata section: [water_layer]

Default filename: water.png

Size scalable: Yes

Water layers are paletted PNG images which indicate the presence or abscense of water in each tile. If a water layer is not present, OpenTTD will assume that all tiles with a resulting height of zero are sea. If the water layer is present, OpenTTD will only mark as sea those tiles indicated in the water layer (Issue: OpenTTD will flood any tiles with a height of zero in the border of the map).

Water layers include the following information:

Climate layer

Metadata section: [climate_layer]

Default filename: climate.png

Size scalable: Yes

The climate layer is a paletted PNG image that stores information about the climate type of each one of the tiles. Currently only the subtropical climate has different climate types for their tiles.

Canal layer

Metadata section: [canal_layer]

Default filename: canal.png

Size scalable: No

Canal layers are two-colour paletted PNG images that indicate the canals and locks present in the map. A "canal" in a sloped tile indicates a lock.

Road layer

The road layer will be defined after the rest of the format is done. See for details.

Object files

Object files contain text data associated to a given game entity.

The "direction" fields can take the following values:

Town file

Metadata section: [town_file]

Default filename: town.txt

Size scalable: Yes

The town file lists all towns included in the extended heightmap along with their position and properties. If this object file is not present, towns will be randomly generated accordingly to the current OpenTTD settings. There is a [town] section for each town, and it includes the following properties:

name=Town Name 1

Road bridge file

Metadata section: [road_bridge_file]

Default filename: road_bridge.txt

Size scalable: No

This file stores all road bridges. All properties are obligatory.


Road tunnel file

Metadata section: [road_tunnel_file]

Default filename: road_tunnel.txt

Size scalable: No

This file stores all road tunnels. All properties are obligatory.


Aqueduct file

Metadata section: [water_bridge_file]

Default filename: water_bridge.txt

Size scalable: No

This file stores all aqueducts. All properties are obligatory.


Sign file

Metadata section: [sign_file]

Default filename: sign.txt

Size scalable: Yes

This file stores all signs. All properties are obligatory.

text=Welcome to this scenario!

Industry file

An industry file is planned, but since it is quite complicated it won't be designed until everything else is already implemented and working.