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.