Tutorial: Hex-Welten#

In diesem Tutorial baust du Schritt für Schritt eine Welt aus Sechsecken. Sechseckige Welten werden für Brettspiele wie Catan verwendet: Landhexfelder, Siedlungen auf Ecken und Straßen auf Kanten.

Wenn du noch nie mit Welten gearbeitet hast, beginne mit dem Kapitel Die erste Welt im interaktiven Kurs.

Schritt 1: Eine Hex-Welt erstellen#

Eine HexWorld wird mit (Spalten, Zeilen) und einer tile_size erstellt:

import miniworlds

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

world.run()

Hexfelder werden wie Kacheln in einer TiledWorld über (Spalte, Zeile)-Koordinaten angesprochen. Ungerade Zeilen sind um ein halbes Hexfeld nach rechts verschoben.

Schritt 2: Actors auf Hexfeldern platzieren#

Ein Actor, der auf einer Hexfeld-Position platziert wird, wird als Sechseck gezeichnet:

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()

Schritt 3: Nachbarn abfragen#

world.get_tile(position) gibt ein einzelnes Hexfeld zurück. tile.get_neighbour_tiles() gibt die bis zu sechs benachbarten Hexfelder zurück.

Das Beispiel färbt das zentrale Hexfeld und alle seine Nachbarn:

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) gibt alle Hexfelder innerhalb eines Hex-Abstands zurück, von der Mitte nach außen sortiert. world.get_tiles_in_ring(position, radius) gibt nur die Hexfelder mit genau diesem Abstand zurück, in der Reihenfolge des Rings.

Du kannst eine Position, eine Kachel oder einen Actor übergeben. Mit include_center=False wird das Hexfeld selbst weggelassen. Auch eine Kachel kennt ihre Umgebung:

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) gibt den Nachbarn in einer Richtung ("o", "so", "sw", "w", "nw", "no") zurück, oder None am Rand der Welt.

Abstände und Linien#

world.get_distance(a, b) gibt die Anzahl der Schritte zwischen zwei Hexfeldern zurück. Der Wert hängt nicht von der Zeilenparität ab und ist deshalb der richtige Weg, Abstände auf einem Hex-Gitter zu messen (tile.get_distance_to(other) macht dasselbe). Vergleiche die Offset-Koordinaten (column, row) nicht direkt, denn die verschobenen Zeilen machen sie irreführend.

world.get_tiles_in_line(start, end) gibt die Hexfelder auf der geraden Linie zwischen zwei Hexfeldern zurück. Zusammen mit tile.is_blocking beantwortet das Sichtlinien-Fragen:

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()

Als Radius sind nur ganze Zahlen erlaubt; ein negativer Radius liefert eine leere Liste.

Schritt 4: Actors von Hexfeld zu Hexfeld bewegen#

Actors bewegen sich mit den sechs Hex-Richtungen "no", "o", "so", "sw", "w" und "nw" von Hexfeld zu Hexfeld:

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()

Jeder Aufruf von move_in_direction bewegt den Actor genau ein Hexfeld weit, unabhängig davon, ob die Zeile gerade oder ungerade ist. Die Richtungen können auch als Grad angegeben werden: "no" ist 30, "o" ist 90, "so" ist 150, "sw" ist 210, "w" ist 270 und "nw" ist 330.

Schritt 5: Auf Klicks reagieren#

Mit @world.register kannst du auf Mausklicks reagieren. world.get_tile_from_pixel(mouse_pos) gibt das Hexfeld unter der Maus zurück oder None, wenn der Klick außerhalb der Welt liegt:

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()

Schritt 6: Siedlungen und Straßen#

Auch Ecken und Kanten sind Positionen. world.get_corner_from_pixel(mouse_pos) gibt die nächstgelegene Ecke zurück, world.get_edge_from_pixel(mouse_pos) die nächstgelegene Kante. Beide geben None zurück, wenn der Pixel außerhalb der Welt liegt, zum Beispiel wenn an die Welt eine Toolbar oder Konsole angedockt ist.

Ein Linksklick platziert eine Siedlung (kleiner Kreis) auf einer Ecke, ein Rechtsklick eine Straße (kleines Rechteck) auf einer Kante:

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()

Schritt 7: Ein Mini-Catan-Brett#

Ein Catan-Brett hat 19 Landhexfelder, angeordnet in Zeilen aus 3, 4, 5, 4 und 3 Hexfeldern:

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()

Schritt 8: Daten auf Hexfeldern speichern#

Jedes Hexfeld kann Spieldaten tragen. tile.data ist ein Dictionary für alles, was dein Spiel braucht, tile.terrain ist eine Abkürzung für 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()

Schritt 9: Wege finden#

world.find_path(start, goal) gibt den günstigsten Weg von einem Hexfeld zu einem anderen als Liste von Hexfeldern zurück. Ein Hexfeld zu betreten kostet tile.cost (Standard: 1). Ein Hexfeld mit tile.is_blocking = True kann nicht betreten werden, ebenso wenig ein Hexfeld mit einem blockierenden Actor (actor.is_blocking = True).

Klicke auf ein Hexfeld, damit der Roboter um das Wasser herum dorthin läuft:

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 gibt eine leere Liste zurück, wenn es keinen Weg gibt. Langsames Gelände bedeutet einfach höhere Kosten, zum Beispiel swamp.cost = 3.

world.get_reachable_tiles(start, max_cost) gibt jedes Hexfeld zurück, das der Actor mit einem Bewegungsbudget erreichen kann, und läuft dabei um blockierte Hexfelder herum:

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) findet den günstigsten Weg zum nächstgelegenen Hexfeld, das eine Bedingung erfüllt. Das Ziel darf blockiert sein, zum Beispiel ein Gegner, der sein eigenes Hexfeld blockiert:

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) beantwortet, ob ein blockiertes Hexfeld auf der geraden Linie zwischen zwei Hexfeldern das Ziel verdeckt:

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()

Schritt 10: Das Hexfeld unter der Maus hervorheben#

Eine Welt kann reagieren, wenn die Maus ein Hexfeld betritt oder verlässt. tile.highlight(color) färbt ein Hexfeld unter den Actors ein; tile.clear_highlight() entfernt die Farbe wieder:

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 enthält immer das Hexfeld unter der Maus oder None.

Von hier aus kannst du im Pattern Hex-Welten und ein Mini-Catan-Brett weitermachen und eigene Spielregeln ergänzen: Würfel, Rohstoffe und Handel sind nicht Teil des Frameworks — sie gehören in deinen Spielcode.

Die vollständige Schnittstelle ist in der HexWorld-API-Referenz dokumentiert.