Tutorial: Hex Worlds#

In this tutorial you build a world made of hexagons, step by step. Hexagonal worlds are used for board games like Catan: land hexes, settlements on corners, and roads on edges.

If you have never worked with worlds before, start with the chapter Die erste Welt in the interactive course.

Step 1: Create a hex world#

A HexWorld is created with (columns, rows) and a tile_size:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

world.run()

Hexes are addressed with (column, row) coordinates, like tiles in a TiledWorld. Odd rows are shifted half a hex to the right.

Step 2: Place actors on hexes#

An actor placed on a hex position is drawn as a hexagon:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

forest = miniworlds.Actor((2, 3))
forest.fill_color = (0, 120, 0)

desert = miniworlds.Actor((4, 2))
desert.fill_color = (230, 210, 160)

world.run()

Step 3: Query neighbors#

world.get_tile(position) returns a single hex. tile.get_neighbour_tiles() returns the up to six neighboring hexes.

The example colors the center hex and all its neighbors:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

center = world.get_tile((3, 3))
center_actor = miniworlds.Actor(center.position)
center_actor.fill_color = (200, 30, 30)

for tile in center.get_neighbour_tiles():
    actor = miniworlds.Actor(tile.position)
    actor.fill_color = (0, 120, 0)

world.run()

world.get_tiles_in_radius(position, radius) returns all hexes within a given hex distance, ordered from the center outwards. world.get_tiles_in_ring(position, radius) returns only the hexes at exactly the given distance, in ring traversal order.

You can pass a position, a tile, or an actor. With include_center=False the hex itself is left out. A tile also knows its surroundings:

import miniworlds

world = miniworlds.HexWorld(9, 9, tile_size=30)
world.background.grid = True

center = world.get_tile((4, 4))
for tile in center.get_tiles_in_radius(2):
    tile.highlight((0, 120, 255, 90))
for tile in center.get_tiles_in_ring(3):
    tile.highlight((255, 120, 0, 90))

east = center.get_neighbour("o")
if east is not None:
    east.highlight((255, 0, 0, 120))

world.run()

tile.get_neighbour(direction) returns the neighbor in one direction ("o", "so", "sw", "w", "nw", "no") or None at the border of the world.

Distances and lines#

world.get_distance(a, b) returns the number of steps between two hexes. It does not depend on the row parity, so it is the right way to measure distances on a hex grid (tile.get_distance_to(other) does the same). Do not compare the offset coordinates (column, row) directly, because the shifted rows make them misleading.

world.get_tiles_in_line(start, end) returns the hexes on the straight line between two hexes. Together with tile.is_blocking this answers line-of-sight questions:

import miniworlds

world = miniworlds.HexWorld(9, 7, tile_size=30)
world.background.grid = True

wall = world.get_tile((4, 3))
wall.is_blocking = True
wall.highlight((90, 90, 90, 200))

line = world.get_tiles_in_line((1, 3), (7, 3))
visible = world.has_line_of_sight((1, 3), (7, 3))
for tile in line:
    tile.highlight((0, 200, 0, 90) if visible else (200, 0, 0, 90))

print("Distance:", world.get_distance((1, 3), (7, 3)), "visible:", visible)

world.run()

The queries accept only whole numbers as radius; a negative radius returns an empty list.

Step 4: Move actors from hex to hex#

Actors move from hex to hex with the six hex directions "no", "o", "so", "sw", "w", and "nw":

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

robot = miniworlds.Actor((3, 3))
robot.fill_color = (200, 30, 30)

@robot.register
def act(self):
    if world.frame % 20 == 0:
        self.move_in_direction("no")

world.run()

Every move_in_direction call moves the actor exactly one hex, independent of the row parity. The directions can also be given as degrees: "no" is 30, "o" is 90, "so" is 150, "sw" is 210, "w" is 270, and "nw" is 330.

Step 5: React to clicks#

With @world.register you can react to mouse clicks. world.get_tile_from_pixel(mouse_pos) returns the hex under the mouse, or None if the click is outside the world:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

@world.register
def on_mouse_left(self, mouse_pos):
    tile = world.get_tile_from_pixel(mouse_pos)
    if tile is None:
        return
    actor = miniworlds.Actor(tile.position)
    actor.fill_color = (0, 120, 0)

world.run()

Step 6: Settlements and roads#

Corners and edges are positions, too. world.get_corner_from_pixel(mouse_pos) returns the nearest corner, world.get_edge_from_pixel(mouse_pos) the nearest edge. Both return None if the pixel is outside the world, for example when a toolbar or console is attached to the world.

A left click places a settlement (small circle) on a corner, a right click places a road (small rectangle) on an edge:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

@world.register
def on_mouse_left(self, mouse_pos):
    corner = world.get_corner_from_pixel(mouse_pos)
    settlement = miniworlds.Actor(corner.position)
    settlement.fill_color = (200, 30, 30)
    settlement.size = (0.3, 0.3)

@world.register
def on_mouse_right(self, mouse_pos):
    edge = world.get_edge_from_pixel(mouse_pos)
    road = miniworlds.Actor(edge.position)
    road.fill_color = (90, 60, 30)
    road.size = (0.6, 0.15)

world.run()

Step 7: A mini-Catan board#

A Catan board has 19 land hexes, arranged in rows of 3, 4, 5, 4, and 3:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

land_positions = [
    (2, 1), (3, 1), (4, 1),
    (2, 2), (3, 2), (4, 2), (5, 2),
    (1, 3), (2, 3), (3, 3), (4, 3), (5, 3),
    (1, 4), (2, 4), (3, 4), (4, 4),
    (2, 5), (3, 5), (4, 5),
]
terrain_colors = [
    (0, 120, 0),      # forest
    (220, 180, 60),   # field
    (120, 200, 60),   # meadow
    (150, 150, 150),  # mountain
    (200, 90, 30),    # hill
    (230, 210, 160),  # desert
]

for number, position in enumerate(land_positions):
    actor = miniworlds.Actor(position)
    actor.fill_color = terrain_colors[number % len(terrain_colors)]
    actor.border = 1

world.run()

Step 8: Store data on hexes#

Every hex can carry game data. tile.data is a dictionary for anything your game needs, tile.terrain is a shortcut for tile.data["terrain"]:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

for position, tile in world.tiles.items():
    tile.terrain = "forest" if position[0] % 2 == 0 else "field"
    tile.data["dice_number"] = 2 + (position[0] + position[1]) % 11

tile = world.get_tile((3, 3))
print(tile.terrain, tile.data["dice_number"])

world.run()

Step 9: Find paths#

world.find_path(start, goal) returns the cheapest way from one hex to another as a list of hexes. Stepping onto a hex costs tile.cost (default 1). A hex with tile.is_blocking = True cannot be entered, and neither can a hex with a blocking actor (actor.is_blocking = True).

Click a hex to walk the robot there around the water:

import miniworlds

world = miniworlds.HexWorld(9, 9, tile_size=36)
world.background.grid = True

for position in [(3, 3), (4, 3), (5, 3), (3, 4), (5, 4)]:
    water = world.get_tile(position)
    water.is_blocking = True
    water.highlight((0, 80, 200, 160))

robot = miniworlds.Actor((1, 4))
robot.fill_color = (200, 30, 30)
route = []

@world.register
def on_mouse_left(self, mouse_pos):
    goal = world.get_tile_from_pixel(mouse_pos)
    if goal is None:
        return
    route[:] = world.find_path(robot, goal)[1:]

@robot.register
def act(self):
    if route and world.frame % 10 == 0:
        self.position = route.pop(0).position

world.run()

find_path returns an empty list if there is no way. Slow terrain is just a higher cost, for example swamp.cost = 3.

world.get_reachable_tiles(start, max_cost) returns every hex the actor can reach with a movement budget, walking around blocked hexes:

import miniworlds

world = miniworlds.HexWorld(9, 9, tile_size=36)
world.background.grid = True
world.get_tile((4, 3)).is_blocking = True

for tile in world.get_reachable_tiles((4, 4), 2):
    tile.highlight((0, 200, 0, 90))

world.run()

world.find_nearest(start, is_target) finds the cheapest way to the nearest hex that satisfies a condition. The target may be blocked, for example an enemy that blocks its own hex:

import miniworlds

world = miniworlds.HexWorld(9, 9, tile_size=36)
world.background.grid = True

for position in [(7, 2), (2, 7)]:
    world.get_tile(position).terrain = "forest"
    world.get_tile(position).highlight((0, 120, 0, 150))

path = world.find_nearest((4, 4), lambda tile: tile.terrain == "forest")
for tile in path:
    tile.highlight((255, 255, 0, 120))
print("cost:", world.get_path_cost(path))

world.run()

world.has_line_of_sight(start, goal) answers whether a blocked hex hides the goal on the straight line between two hexes:

import miniworlds

world = miniworlds.HexWorld(9, 9, tile_size=36)
world.background.grid = True
world.get_tile((4, 4)).is_blocking = True
world.get_tile((4, 4)).highlight((0, 80, 200, 160))

print(world.has_line_of_sight((1, 4), (7, 4)))  # False: the wall is in the way
print(world.has_line_of_sight((1, 1), (7, 1)))  # True

world.run()

Step 10: Highlight the hex under the mouse#

A world can react when the mouse enters or leaves a hex. tile.highlight(color) colors a hex below the actors; tile.clear_highlight() removes the color again:

import miniworlds

world = miniworlds.HexWorld(7, 7, tile_size=40)
world.background.grid = True

@world.register
def on_tile_enter(self, tile):
    tile.highlight((255, 255, 0, 100))

@world.register
def on_tile_leave(self, tile):
    tile.clear_highlight()

world.run()

world.hovered_tile always holds the hex under the mouse, or None.

From here you can continue in the pattern Hex Worlds and a Mini-Catan Board and add your own game rules: dice, resources, and trading are not part of the framework — they belong in your game code.

The full interface is documented in the HexWorld API reference.