World > HexWorld

API Reference

class miniworlds.worlds.hex_world.hex_world.HexWorld(x=20, y=16, tile_size=40, empty=False)

A world that consists of hexagonal tiles.

Hexes are addressed with offset coordinates (column, row), like tiles in a TiledWorld. Odd rows are shifted half a hex to the right (pointy-top layout). Actors can also be placed on corners (shared by up to three hexes) or edges (shared by two hexes).

The six neighbors of a hex are reached with the directions “o”, “so”, “sw”, “w”, “nw”, “no”. Because odd rows are shifted, the diagonal neighbors depend on the row parity:

• Odd rows: “no” and “so” point to (column + 1, row - 1) and (column + 1, row + 1), while “nw” and “sw” point to (column, row - 1) and (column, row + 1).

• Even rows: “no” and “so” point to (column, row - 1) and (column, row + 1), while “nw” and “sw” point to (column - 1, row - 1) and (column - 1, row + 1).

“o” and “w” always point to (column + 1, row) and (column - 1, row).

Examples

from miniworlds import HexWorld, Actor

world = HexWorld(7, 7, tile_size=40)
actor = Actor((3, 3))
actor.fill_color = (255, 0, 0)

world.run()

__init__(x=20, y=16, tile_size=40, empty=False)

Create a hex world.

Parameters:

• x – Number of columns.

• y – Number of rows.

• tile_size – The hex size in pixels (circumradius of the hex).

• empty – If True, tiles, edges, and corners are not created automatically.

dialog

get_actors_from_pixel(position)

Return all actors on the hex tile under a screen pixel.

Parameters:

position – Pixel position as (x, y).

Returns:

Actors located on the hex tile under the pixel. An empty list if the pixel lies outside the world.

Examples

actors = world.get_actors_from_pixel(mouse_pos)

get_center_points()

Return a mapping of hex positions to their center pixels.

Return type:

Dict[Tuple[int, int], Tuple[float, float]]

get_corner(position, direction=None)

Return a corner by corner position or hex position plus direction.

Parameters:

• position – Corner position, or hex position when direction is set.

• direction – Optional corner direction, e.g. “no”.

Returns:

The matching corner.

Raises:

CornerNotFoundError – If no corner exists at the resolved position.

Examples

corner = world.get_corner((3, 3), "no")

get_corner_from_pixel(position)

Return the corner nearest to a screen pixel.

Parameters:

position – Pixel position as (x, y).

Returns:

The nearest corner, or None if the pixel is outside the world.

Examples

corner = world.get_corner_from_pixel(mouse_pos)

get_edge(position, direction=None)

Return an edge by edge position or hex position plus direction.

Parameters:

• position – Edge position, or hex position when direction is set.

• direction – Optional edge direction, e.g. “o”.

Returns:

The matching edge.

Raises:

EdgeNotFoundError – If no edge exists at the resolved position.

Examples

edge = world.get_edge((3, 3), "o")

get_edge_from_pixel(position)

Return the edge nearest to a screen pixel.

Parameters:

position – Pixel position as (x, y).

Returns:

The nearest edge, or None if the pixel is outside the world.

Examples

edge = world.get_edge_from_pixel(mouse_pos)

get_from_pixel(position)

Return the hex position for a screen pixel.

Parameters:

position – Pixel position as (x, y).

Returns:

Hex position as (column, row), or None if the pixel lies outside the world.

Examples

hex_position = world.get_from_pixel((80, 120))

get_tile_from_pixel(position)

Return the hex tile under a screen pixel.

Parameters:

position – Pixel position as (x, y).

Returns:

The hex tile under the pixel, or None if the pixel lies outside the world (no tile exists at the rounded hex position).

Examples

tile = world.get_tile_from_pixel((80, 120))
if tile is not None:
    tile.fill_color = (255, 0, 0)

get_tiles_in_radius(position, radius)

Return all tiles within a hex distance of radius.

Neighbors are computed in cube coordinates, so the result is independent of the row parity described in the HexWorld docstring.

Return type:

List[HexTile]

Parameters:

• position – Hex position as (column, row).

• radius – Maximum hex distance (0 includes only the tile itself).

Returns:

List of tiles within the radius, including the tile itself, ordered from the center outwards in ring traversal order. Positions outside the world are skipped.

Examples

neighbours = world.get_tiles_in_radius((3, 3), 1)

get_tiles_in_ring(position, radius)

Return all tiles at exactly radius hex distance.

Neighbors are computed in cube coordinates, so the result is independent of the row parity described in the HexWorld docstring.

Return type:

List[HexTile]

Parameters:

• position – Hex position as (column, row).

• radius – Hex distance.

Returns:

List of tiles at the given distance, in ring traversal order starting at the westernmost hex of the ring. Positions outside the world are skipped.

Examples

ring = world.get_tiles_in_ring((3, 3), 2)

is_hex = True

to_pixel(position, size=(0, 0), origin=(0, 0))

Convert a hex position to the pixel position of its center.

Parameters:

• position – Hex position as (column, row).

• size – Reserved for compatibility.

• origin – Pixel offset added to the converted position.

Returns:

Pixel position as (x, y).

Examples

pixel = world.to_pixel((2, 3))

class miniworlds.worlds.hex_world.hex_tile.HexTile(position, world=None)

A hexagonal tile in a HexWorld.

Tiles are addressed with offset coordinates (column, row), like tiles in a TiledWorld. Odd rows are shifted half a hex to the right; because of this shift, the diagonal neighbors of a hex depend on the row parity (see the HexWorld docstring for the full convention).

corner_vectors: OrderedDict[str, Tuple[float, float]] = {'n': (1, -2, 1), 'no': (2, -1, -1), 'nw': (-1, -1, 2), 's': (-1, 2, -1), 'so': (1, 1, -2), 'sw': (-2, 1, 1)}

edge_vectors: dict[str, Tuple[float, float]] = {'no': (1, -1, 0), 'nw': (0, -1, 1), 'o': (1, 0, -1), 'so': (0, 1, -1), 'sw': (-1, 1, 0), 'w': (-1, 0, 1)}

classmethod from_pixel(pixel_position, world=None)

Return the hex tile containing a pixel position.

The conversion is exact: the pixel is converted to fractional cube coordinates and rounded to the nearest hex center. The position is not checked against the world bounds; use world.get_tile_from_pixel for a bounds-checked lookup that returns None outside the world.

Return type:

HexTile

classmethod from_position(position, world)

Create a tile from a world-relative position.

Return type:

HexTile

get_corner(direction)

Return the corner of this hex in the given direction.

Return type:

HexCorner

Parameters:

direction – Corner direction, e.g. “no”.

Examples

corner = world.get_tile((2, 2)).get_corner("no")

get_edge(direction)

Return the edge of this hex in the given direction.

Return type:

HexEdge

Parameters:

direction – Edge direction, e.g. “o”.

Examples

edge = world.get_tile((2, 2)).get_edge("o")

static get_local_center_coordinate(world)

Returns the center point offset for a tile, in local pixel coordinates.

Return type:

Tuple[float, float]

get_local_corner_points()

Return the six corner pixels relative to the hex bounding box topleft.

Return type:

List[Tuple[float, float]]

get_neighbour_tiles()

Return the up to six neighboring hex tiles.

Return type:

List[HexTile]

static get_position_pixel_dict(world)

Returns a mapping of tile positions to pixel coordinates.

Return type:

dict

tile_vectors: dict[str, Tuple[int, int]] = {'no': (1, -1, 0), 'nw': (0, -1, 1), 'o': (1, 0, -1), 'so': (0, 1, -1), 'sw': (-1, 1, 0), 'w': (-1, 0, 1)}

to_center()

Return the center pixel of the hex.

Return type:

Tuple[float, float]

to_pixel()

Return the topleft pixel of the hex bounding box.

Return type:

Tuple[float, float]

class miniworlds.worlds.hex_world.hex_corner.HexCorner(position, direction, world=None)

A corner of a hex, shared by up to three hexes.

The corner position is a unique key in tripled cube coordinates: all hexes that share the corner compute the same key, so corners are merged when the world is built.

angles: Dict[str, int] = {'n': 0, 'no': 1, 'nw': 5, 's': 3, 'so': 2, 'sw': 4}

direction_angles: Dict[str, int] = {'n': 0, 'no': 0, 'nw': 0, 's': 0, 'so': 0, 'sw': 0}

static direction_vectors()

Returns the available directions.

classmethod from_position(position, world)

Create a tile delimiter (override expected).

Return type:

HexCorner

get_neighbour_tiles()

Return the up to three hexes that share this corner.

The hexes are derived from the merged corner references, so no tile has to exist for every reference: references to positions outside the world are skipped.

Return type:

List[HexTile]

start_angle()

Override: starting angle offset for layouting (e.g. hex rotation).

Return type:

int

to_pixel()

Return the pixel position of the corner.

Return type:

Tuple[float, float]

class miniworlds.worlds.hex_world.hex_edge.HexEdge(position, direction, world=None)

An edge of a hex, shared by exactly two hexes.

The edge position is a unique key in doubled cube coordinates: both hexes that share the edge compute the same key, so edges are merged when the world is built.

angles: Dict[str, int] = {'no': 5, 'nw': 4, 'o': 0, 'so': 1, 'sw': 2, 'w': 3}

direction_angles: Dict[str, int] = {'no': 300, 'nw': 240, 'o': 0, 'so': 60, 'sw': 120, 'w': 180}

static direction_vectors()

Returns the available directions.

classmethod from_position(position, world)

Create a tile delimiter (override expected).

Return type:

HexEdge

get_neighbour_tiles()

Return the up to two hexes that share this edge.

The hexes are derived from the merged edge references, so no tile has to exist for every reference: references to positions outside the world are skipped.

Return type:

List[HexTile]

start_angle()

Override: starting angle offset for layouting (e.g. hex rotation).

Return type:

int

to_pixel()

Return the pixel position of the edge center.

Return type:

Tuple[float, float]