OpenFrontIO/map-generator

MapGenerator

This is a go-based tool to generate map files for OpenFront.

The map generator reads PNG files and converts pixels into terrain based primarily on the Blue channel. Because only blue values are used, grayscale and other formats are fully supported. Many maps in assets/maps/<mapname> are grayscale.

Additional Guides, Tutorials, Scripts, Resources, and Third Party Unofficial Applications can be found on the Official Openfront Wiki

Installation

1. Install go https://go.dev/doc/install
2. Go to map-generator folder: cd map-generator
3. Install dependencies: go mod download
4. Run the generator for all maps: go run .

Creating a new map

1. Create a new folder in assets/maps/<map_name>

2. Create assets/maps/<map_name>/image.png

3. Create assets/maps/<map_name>/info.json with name and countries

4. Add the map name in main.go The <name> in {Name: "<name>"}, should match the <map-name> folder at assets/maps/<map_name>

5. Run the generator for your map: go run . --maps=<map_name>

   By default, go run . will process all defined maps.

   Use --maps to process a single map:

   go run . --maps=fourislands

   To process a subset of maps, pass a comma-separated list:

   go run . --maps=northamerica,world

6. Find the output folder at ../resources/maps/<map_name>

7. Go back to the root directory: cd ..

8. Run Prettier: npm run format This rewrites ALL files in place. Git figures out which files are actually changed, don't worry. Alternatively, you can either run Prettier per file: npx prettier --write resources/maps/<map_name>/<file_name> or in VSCode install the Prettier extension and per file do Show and run Commands > Format Document.

Output Files

• ../resources/maps/<map_name>/manifest.json - JSON metadata containing map dimensions and land tile counts for all scales.
• ../resources/maps/<map_name>/map.bin - Full-scale binary map data packed with terrain type and magnitude.
• ../resources/maps/<map_name>/map4x.bin - 1/4 scale (half dimensions) binary map data used for mini-maps.
• ../resources/maps/<map_name>/map16x.bin - 1/16 scale (quarter dimensions) binary map data used for mini-maps.
• ../resources/maps/<map_name>/thumbnail.webp - WebP image thumbnail of the map.

Command Line Flags

• --maps: Optional comma-separated list of maps to process.
  • ex: go run . --maps=world,eastasia,big_plains

Logging

• --log-level: Explicitly sets the log level.
  • ex: go run . --log-level=debug
  • values: ALL, DEBUG, INFO (default), WARN, ERROR.
• --verbose or -v: Adds additional logging and prefixes logs with the [mapname]. Alias of --log-level=DEBUG.
• --debug-performance: Adds additional logging for performance-based recommendations, sets --log-level=DEBUG.
• --debug-removal: Adds additional logging of removed island and lake position/size, sets --log-level=DEBUG.

The Generator outputs logs using slog with standard log-levels, and an additional ALL level.

The --verbose, -v, --debug-performance, and --debug-removal flags all set the log level to DEBUG. debug-performance and debug-removal are opt-in on top of the debug log level, as they can produce wordy output. You must pass the specific flag to see the corresponding logs if the log-level is set to DEBUG.

Setting --log-level=ALL will output all possible logs, including all DEBUG tiers, regardless of whether the specific flags are passed.

Create image.png

The map-generator will process your input file at assets/maps/<map_name>/image.png to generate the map thumbnail and binary files. To create this png input file, you can crop the world map:

1. Download world map (warning very large file)
2. Crop the file (recommend Gimp)

If you are doing work in image editing software or using automated tools, ./map_generator.go contains documentation for:

• Pixel -> Terrain Type & Magnitude mapping in GenerateMap
• Terrain Type -> Thumbnail Color mapping in getThumbnailColor

In-Game, terrain is rendered using themes. The color of a tile is determined dynamically based on its Terrain Type and Magnitude. Theme Files:

• ../src/core/configuration/PastelTheme.ts (Light)
• ../src/core/configuration/PastelThemeDark.ts (Dark).

Create info.json

The map-generator will process your input file at assets/maps/<map_name>/info.json to determine the position of Nations, their starting coordinates, and any flags.

Example:

{
  "name": "MySampleMap",
  "nations": [
    {
      "coordinates": [396, 364],
      "name": "United States",
      "flag": "us"
    }
  ]
}

coordinates is x/y position of the nation spawn on the map. Origin is at top left, with x extending right and y extending down

name is a CamelCaseName of your map. It is used to enable the map in-game.

flag is the code for a country

• The full list of supported codes can be seen in ../src/client/data/countries.json - all ISO_3166 codes are supported, with several additions.

• For quick reference, Use country codes found here

Update CREDITS.md

Add License & Attribution information to ../CREDITS.md. If you are unsure if a map's license can be used, open an issue or ask in Discord before beginning work.

Adding Flags

Flags can be added to ../resources/flags/<iso_code>.svg

The country will need to be added to ../src/client/data/countries.json

To Enable In-Game

Using the name from your json:

• Add to GameMapType and mapCategories in ../src/core/game/Game.ts
• Add to the map playlist in ../src/server/MapPlaylist.ts
• Add to the map translation object in ../resources/lang/en.json

Notes

• Islands smaller than 30 tiles (pixels) are automatically removed by the script.
• Bodies of water smaller than 200 tiles (pixels) are also removed.
• The map generator normalizes dimensions to multiples of 4. Any pixels beyond Width - (Width % 4) or Height - (Height % 4) are cropped.

For Performance Reasons:

• Maps should be between 2 - 3 million pixels square (area).
• Maps with over 3 million land tiles are not recommended.
• Average land tile count is around 1 - 2 million.

🛠️ Development Tools

• Format map-generator code:

  go fmt .
  

• Output Map Generator Documentation:

  go doc -cmd -u -all
  

  The map-generator is a cli tool, to get any visibility, we pass -cmd. It also does not expose any API, so we use -u and -all to show all documentation for unexposed values.

  Known Bug Using -http does not respect the other flags and only renders the README