Skip to main content

​
What is the Map Generator?

The Map Generator is a Go-based command-line tool that converts PNG image files into optimized binary terrain maps for OpenFront. It processes source images from the assets/maps/ directory and outputs game-ready map files to resources/maps/.

​
Key Features

​
Terrain Processing

  • PNG to Terrain Conversion: Reads PNG files and converts pixels into terrain based on the Blue channel value
  • Multi-format Support: Grayscale and other image formats are fully supported since only blue values are used
  • Automatic Cleanup: Removes small islands (< 30 tiles) and lakes (< 200 tiles) to improve game performance
  • Dimension Normalization: Automatically crops dimensions to multiples of 4 for minimap compatibility

​
Output Generation

For each map, the generator creates:
1

Binary Map Files

  • map.bin - Full-scale terrain data
  • map4x.bin - 1/4 scale (half dimensions) for minimaps
  • map16x.bin - 1/16 scale (quarter dimensions) for minimaps
2

Metadata

  • manifest.json - Map dimensions and land tile counts for all scales
3

Thumbnail

  • thumbnail.webp - WebP preview image of the map

​
Terrain Type Mapping

The generator determines terrain type and magnitude based on pixel blue channel values:
Input ConditionTerrain TypeMagnitudeNotes
Alpha < 20WaterDistance to Land*Transparent pixels become water
Blue = 106WaterDistance to Land*Specific key color for water
Blue < 140Land (Plains)0Clamped to minimum magnitude
Blue 140-158Land (Plains)0-9Low elevation terrain
Blue 159-178Land (Highland)10-19Medium elevation terrain
Blue 179-200Land (Mountain)20-30High elevation terrain
Blue > 200Land (Mountain)30Clamped to maximum magnitude
*For water tiles, magnitude is calculated during generation as the Manhattan distance to the nearest land tile.

​
Performance Recommendations

The map generator includes built-in performance recommendations:
  • Map Area: 2-3 million pixels (width × height)
  • Land Tiles: Maximum 3 million land tiles recommended
  • Average Land Count: 1-2 million tiles
Maps exceeding these limits will trigger debug warnings when using --log-level=debug or --log-performance.

​
How It Works

1

Read Source Assets

Loads image.png and info.json from assets/maps/<map_name>/
2

Process Pixels

Converts each pixel to terrain type based on blue channel value
3

Clean Up Terrain

Removes small islands and lakes using flood-fill algorithms
4

Generate Minimaps

Creates 4x and 16x downscaled versions using 2×2 block sampling
5

Calculate Water Distance

Uses BFS to compute distance-to-land for all water tiles
6

Pack Binary Data

Serializes terrain into compact binary format:
  • Bit 7: Land (1) / Water (0)
  • Bit 6: Shoreline flag
  • Bit 5: Ocean flag
  • Bits 0-4: Magnitude (0-31)
7

Write Output Files

Saves binary maps, manifest.json, and thumbnail.webp to resources/maps/<map_name>/

​
Additional Resources

For map creation tutorials, scripts, and third-party tools, visit the Official OpenFront Wiki - Map Making.

Build docs developers (and LLMs) love

Get started for freeTalk to us