docs/importing_town_data.md

   1 # Importing Town Data into OpenTTD
   2
   3 To aid players in scenario creation, OpenTTD's Scenario Editor can import town data from external JSON files. This enables players to use an image editing program to align town coordinates with a real-world heightmap using a map underlay, instead of guessing at the correct locations in Scenario Editor itself.
   4
   5 This town data consists of a JSON file storing an array of town data objects, each containing a name, location, target OpenTTD population, and whether it is marked as a city in the game.
   6
   7 This document describes the standard format for this JSON file and outlines a workflow for creating this data effectively.
   8
   9 ## Table of contents
  10
  11 - Why load external data?
  12 - How to use this feature
  13   - Creating geodata
  14     - Town data format standards
  15     - Town data values
  16   - Loading geodata into OpenTTD
  17 - Tutorial: Creating town data
  18
  19 ## Why load external data?
  20
  21 There are three benefits to using an image editing program to create towns instead of the OpenTTD Scenario Editor.
  22
  23 1. Placing towns accurately is much easier using a map underlay such as OpenStreetMap to match town locations with the corresponding heightmap.
  24 2. Storing town data in a JSON file instead of as an OpenTTD Scenario (.scn) doesn't require choosing your NewGRF house set before placing towns.
  25 3. Town coordinates are scaled by the map size, so you can load the data onto whatever size map you like.
  26
  27 ## How to use this feature
  28
  29 ### Creating geodata
  30
  31 Town data is a text file in the JSON format, with a list of towns, each containing a coordinate location and properties: name, population, and whether or not it should be a city in OpenTTD.
  32
  33 The format of this file is standardized for importing into OpenTTD and must be followed for OpenTTD to properly parse the data.
  34
  35 For use in OpenTTD, you will also need a matching heightmap of the terrain features, as a PNG.
  36
  37 #### Town data format standards
  38
  39 The following code sample is complete and can be used in OpenTTD.
  40 - The list of towns is enclosed in an array marked with square brackets `[]`
  41 - Each town is enclosed in curly braces `{}`, with a comma after each town except for the last in the list.
  42 - The properties separated by commas except for the last.
  43 - Property names are enclosed in double quotes `""` with a colon `:` separating it from the property value.
  44 - The name property value is enclosed in double quotes `"London"`, while all other property values `44910`, `true`, etc., are not.
  45
  46 ```
  47 [
  48     {
  49         "name": "London",
  50         "population": 44910,
  51         "city": true,
  52         "x": 0.7998046875,
  53         "y": 0.708984375
  54     },
  55     {
  56         "name": "Canterbury",
  57         "population": 217.16,
  58         "city": false,
  59         "x": 0.83251953125,
  60         "y": 0.828125
  61     }
  62 ]
  63 ```
  64
  65 #### Town data values
  66
  67 - Population is scaled down for use in OpenTTD. It is possible to generate huge cities by using a large number, but there is a practical limit to town size. The larger the town, the longer it will take to import town data, since towns are placed at a relatively small size and then expanded until the population is greater than the player-defined target.
  68 - X and Y coordinates are a proportion of the total map dimension, between 0 and 1. Just take the pixel coordinates of the town's location in the corresponding heightmap (more detail in the tutorial below) and divide each by the maximum value.
  69   - For example, London is at `726, 1638` in a 1024 px by 2048 px heightmap, so `726 / 1024 = 0.7998046875` and `1638 / 2048 = 0.708984375` gives the correct coordinates for OpenTTD.
  70   - The reason for these proportional coordinates is so the data can be used for any map size.
  71 - 0,0 is (approximately) the very top tile in OpenTTD. You can see tile coordinates in-game with the Land Info Tool.
  72 - In most image editing programs, 0,0 is the top-left corner of the image. You can rotate the image however you want relative to compass north to orient the map to your liking. Make sure you crop and resize the image before recording town locations.
  73 - In OpenTTD, X and Y axis are swapped compared to most image editing programs and the standard Cartesian coordinate system. From the 0,0 origin at top left, X is the axis along the left side and Y is the axis along the right side. You can still measure X and Y coordinates in your image editing program, just swap them before importing into OpenTTD or towns won't line up with your heightmap.
  74
  75 ### Loading geodata into OpenTTD
  76 Using geodata to create a real-world location in OpenTTD is done in the Scenario Editor.
  77
  78 1. Choose the NewGRFs you want to use in the game.
  79 2. Load the heightmap which you created in the geodata workflow. Either rotation will work, but the clockwise rotation is considered "correct" and the coordinates in the Land Info Tool will match your data; counter clockwise maps will align properly but the coordinates won't match your data.
  80 3. In the Town Generation window, click `Load from file` and choose the .json file containing town data. The default directory to search for town data is `OpenTTD\scenario\heightmap`.
  81 4. (Optional) Manually add industries, rivers, trees, and objects.
  82 5. Save the game as a Scenario and exit to the main menu.
  83 6. Load the game with Play Scenario and enjoy.
  84
  85 Sometimes it's not possible to place a town, such as when the heightmap is very rough and a flat tile can't be found with a 16-tile radius of the target tile. In such cases, a sign will be placed on the target tile with the name of the town. The player can then place the town manually or change the heightmap settings and try again. This fallback also helps debug errors with data creation, such as if towns end up in the ocean.
  86
  87 ## Tutorial: Creating town data
  88
  89 1. Load both your heightmap and a labeled map like OpenStreetMap as layers in an image editing program. You can use a free/open-source program like QGIS to acquire, align, and export these map images, if you like.
  90 2. Crop the image to your desired bounds, ensuring the aspect ratio is supported in OpenTTD (1:1, 1:2, 1:4, etc.).
  91 3. Resize the image to one of OpenTTD's supported map sizes, such as 512 px by 1024 px. Some image editors let you do this part of step 2. You can always load heightmaps and town data at a reduced size, so you may want to make this larger than your intended use in case you want it later.
  92 4. Use the labeled map layer to find the pixel coordinates of each town you'd like to include in your map. In GIMP this is displayed in the bottom left corner of the image window, and in Photoshop you need to enable the Info panel (F8) and switch to pixel units of measurement if not already.
  93 5. Some spreadsheets including Google Sheets can export data as JSON, so you may want to record it there, to export after step 8. Or you can build the JSON file manually.
  94 6. Adjust population numbers for OpenTTD.
  95 7. Change coordinates from pixels to proportion (0-1) of the total dimension: `x / maximum_x` and `y / maximum_y`, as described in "Town data values" above.
  96 8. Swap X and Y coordinates before importing to OpenTTD, since OpenTTD uses a reverse X and Y system than most image editors.
  97 9. Save the heightmap and town data files in your `OpenTTD\scenario\heightmap` folder.