Skip to content
A Python-based hexagonal world map generator
Python Other
  1. Python 99.3%
  2. Other 0.7%
Branch: master
Clone or download

Latest commit

oubiwann and eranimo Add CLI (#6)
* In Python 3, simplejson is included as json.

* Re-enable all the image output types, and save them to the 'output' dir.

* Updated Pillow version and added missing NumPy dep.

* Added a script that accepts CLI arguments/options.
Latest commit 872582d Oct 3, 2018


Type Name Latest commit message Commit time
Failed to load latest commit information.
hexgen Add CLI (#6) Oct 3, 2018
LICENSE Initial commit Jun 12, 2015
Makefile pressure attempt #1. Not ideal Jul 17, 2015
setup_env setup_env Feb 21, 2016


Satellite Map

What is this?

It's a world map generator written in Python. It generates a random world map represented in a hexagon grid. The parameters for the generator allow for any kind of planet surface to be generated. It also can segment the surface into randomly sized globs called territories.


I'm using this as a board for a browser-based game I am working on. It can be used for anything from DnD campaigns to open-source games or even just for fun.


This project requires the following:

It's recommended to use virtualenv and virtualenvwrapper to keep the dependencies of this project separate from those that are installed globally on your system. With virtualenvwrapper, you can install this project with the following:

mkvirtualenv hexgen -p python3
pip install -r requirements.txt

Tip: Installing Pillow through pip requires the python header files. You can install those on Debian/Ubuntu with sudo apt-get install python3-dev.

To test your installation, run the unit tests:


If everything is working, it should report back "OK".

How to use

Export types

The primary export of Hexgen is a data structure that represents the world map. It can also export a bunch of png files that show various features on the map.

One interesting thing it can do is take all the data about a hexagon and determine its true color. As exported as an image, the entire grid taken as a whole can be thought of as a satellite image.

Hexagon types:

  • land: defined as a solid surface
  • water: define as a liquid surface

Hexagon properties

  • altitude (int, 0 - 255)
  • temperature (celsius)
  • moisture (int): water content
  • fertility: soil fertility
  • feature
    • lake
    • crater
    • volcano


  • Required parameters

    • size (int): World map size in hexagons. This defines the width and height of the hexagon grid.
    • avg_temp (celsius): average surface temperature of this planet
  • General parameters (required):

    • roughness (int, 0 - 10): used by the diamond-square algorithm to determine the roughness of the terrain.
    • axial_tilt (int, -90 - 90): This world's axial tilt. Has a huge impact on temperature variations.
    • land_percent (int, 0 - 100): Percent of surface that is land
    • hydrosphere (bool): whether the world has surface hydrosphere
    • ocean_type (OceanType): composition of the ocean. Can be water, hydrocarbons, magma
  • Surface features (optional):

    • aquifer_max (int): maximum number of aquifers to place underground
    • river_max (int): maximum number of rivers to place on the map
    • crater_max (int): maximum number of craters to place on the surface
    • volcano_max (int): maximum number of volanoes to place on the surface
    • make_lakes (bool): Put lakes on hexes with 4 or more river segments
  • Territories (optional):

    • make_territories (bool): whether to generate territories
    • land_only (bool): if True, territories will only exist on land
    • separate_zones (bool): if True, territories will never leave their zones
    • merge_islands (bool): if True, unclaimed islands will be given to the nearest territory
    • merge_small (bool): if True, small territories will be merged with their neighbors
  • Exporting:

    • export_type (string, one of "png", "json")
    • png export:
      • draw_borders: (bool): Draw borders between territories and on coastlines
You can’t perform that action at this time.