World

Inhalt

World#

Die Basisklasse für all deine Welten.

Verwende world.send_message("name") fuer einfache Broadcasts zwischen Welt, Actors und angedockten GUI-Welten.

Für Einsteigerklassen setze world.learning_mode = True. Das aktiviert weiche Umwandlungen für typische Fehler in ausgewählten öffentlichen APIs, zum Beispiel bool-ähnliche Zeichenketten wie "yes"/"no" bei einigen Flags und Listenpositionen, wo Tupelpositionen erwartet werden.

Nutzliche Anfaenger-Aliasse auf World sind:

contains(...) für contains_position(...)
broadcast(...) für send_message(...)
actors_at(...) für detect_actors(...)
set_bg(...), add_bg(...), next_bg() für Background-Helfer

API-Referenz#

class miniworlds.worlds.world.World(x=400, y=400)[Quellcode]#

Pixelbasierte Szene, die Actor, Hintergründe, Eingaben und Ereignisse besitzt.

Positionen in einer World sind Pixelkoordinaten. Actor werden standardmäßig über ihre linke obere Position platziert, sofern ihr Ursprung nicht geändert wurde.

Hinweise

Kollisionsprüfungen verwenden standardmäßig Sprite-Masken.

Beispiele

Create and run a world:

    from miniworlds import World
    world = World(300, 200)
    world.run()

Configure a subclass during setup:

    import miniworlds

    class MyWorld(miniworlds.World):
        def on_setup(self):
            self.columns = 300
            self.rows = 200

__init__(x=400, y=400)[Quellcode]#

Erzeuge eine Welt mit der angegebenen Größe.

Parameter:

x – Breite in Pixeln oder ein (breite, höhe)-Tupel.
y – Höhe in Pixeln. Wird ignoriert, wenn x ein Tupel ist.

Beispiele

world = World(400, 300)
square_world = World((200, 200))

act()[Quellcode]#

Hook: wird einmal pro Frame aufgerufen, solange die Welt läuft.

Überschreibe diese Methode in einer Unterklasse (oder registriere eine Funktion mit @world.register), um Code in jedem Frame auszuführen.

Die Basisimplementierung tut nichts, daher ist super().act() in einer überschriebenen act-Methode nie nötig.

Rückgabetyp:: None

Beispiele

class MyWorld(World):
    def act(self):
        if self.frame % 60 == 0:
            self.spawn_enemy()

actors_at(position)[Quellcode]#

Schülerfreundlicher Alias für detect_actors(position).

Rückgabetyp:: List[Actor]

add_background(source)[Quellcode]#

Fügt einen Hintergrund hinzu und macht ihn aktiv.

Rückgabetyp:: Background
Parameter:: source – Bildpfad oder RGB/RGBA-Farbtupel.
Rückgabe:: Der neu erstellte Background.

Beispiele

world.add_background((255, 0, 0))
world.add_background("images/background.png")

add_bg(source)[Quellcode]#

Schülerfreundlicher Alias für add_background(source).

Rückgabetyp:: Background

property background: Background#

Der aktuell aktive Welt-Hintergrund.

Beispiele

world.background = (30, 30, 30)
world.background = "images/sky.png"
current = world.background

Typ:: Background

broadcast(message, data=None)[Quellcode]#

Schülerfreundlicher Alias für send_message(message, data).

Rückgabetyp:: None

property columns: int#

Breite des sichtbaren Weltbereichs in Pixeln.

Beispiele

world.columns = 640

Typ:: int

contains(pos)[Quellcode]#

Gibt zurück, ob eine Position innerhalb der Welt liegt.

Dies ist ein kurzer Alias für contains_position().

contains_position(pos)[Quellcode]#

Gibt zurück, ob eine Position innerhalb der Welt liegt.

Parameter:: pos – Position als (x, y).
Rückgabe:: True, wenn die Position in der Welt liegt.

Beispiele

if world.contains_position(actor.center):
    actor.move()

contains_rect(rect)[Quellcode]#

Gibt zurück, ob ein Rechteck vollständig innerhalb der Welt liegt.

Parameter:: rect – Rechteck als (x, y, breite, höhe) oder pygame.Rect.
Rückgabe:: True, wenn das gesamte Rechteck in der Welt liegt.

Beispiele

if world.contains_rect(actor.rect):
    actor.move()

contains_rect_any(rect)[Quellcode]#

Gibt zurück, ob irgendein Teil eines Rechtecks innerhalb der Welt liegt.

Parameter:: rect – Rechteck als (x, y, breite, höhe) oder pygame.Rect.
Rückgabe:: True, wenn mindestens ein Teil des Rechtecks innerhalb der Welt liegt.

Beispiele

if not world.contains_rect_any(actor.rect):
    actor.remove()

property debug: bool#

Ob ein kompaktes Debug-Overlay zur Laufzeit gezeichnet wird.

Beispiele

world.debug = True

Typ:: bool

detect_actors(position)[Quellcode]#

Gibt alle Actor an einer Weltposition zurück.

Rückgabetyp:: List[Actor]
Parameter:: position – Weltposition als (x, y).
Rückgabe:: Actors, die an der Position gefunden wurden.

Beispiele

actors = world.detect_actors(player.position)
for actor in actors:
    if isinstance(actor, Coin):
        actor.remove()

dialog#

direction_to(pos1, pos2)[Quellcode]#

Gibt die Miniworlds-Richtung von einer Position zu einer anderen zurück.

Rückgabetyp:

float

Parameter:

pos1 – Startposition als (x, y).
pos2 – Zielposition als (x, y).

Rückgabe:

Richtungswinkel in Grad.

Beispiele

mouse_position = world.mouse.get_position()
actor.direction = world.direction_to(actor.center, mouse_position)

static distance_to(pos1, pos2)[Quellcode]#

Gibt den euklidischen Abstand zwischen zwei Positionen zurück.

Rückgabetyp:

float

Parameter:

pos1 – Erste Position als (x, y).
pos2 – Zweite Position als (x, y).

Rückgabe:

Abstand zwischen beiden Positionen.

Beispiele

distance = World.distance_to((0, 0), (3, 4))

property fps: int#

Frames pro Sekunde der Render-Schleife.

Dies steuert die Zeichenfrequenz. Die Logikfrequenz kann unabhängig über world.tick_rate eingestellt werden.

Beispiel

world.fps = 24 world.tick_rate = 2

get_actors_from_pixel(pixel)[Quellcode]#

Gibt alle Actor unter einem Bildschirmpixel zurück.

Rückgabetyp:: List[Actor]
Parameter:: pixel – Bildschirm-Pixel als (x, y).
Rückgabe:: Actor, deren Bildschirmrechteck den Pixel überlappt.

Beispiele

@world.register
def on_mouse_left(self, position):
    for actor in self.get_actors_from_pixel(position):
        actor.hide()

get_background()[Quellcode]#

Gibt den aktiven Hintergrund zurück.

Rückgabetyp:: Background
Rückgabe:: Der aktuelle Background.

Beispiele

bg = world.get_background()
bg.fill_color = (0, 0, 0)

get_from_pixel(position)[Quellcode]#

Wandelt eine Bildschirmpixelposition in eine Weltposition um.

Rückgabetyp:: Optional[Tuple[float, float]]
Parameter:: position – Pixelposition als (x, y).
Rückgabe:: Weltposition oder None, wenn der Pixel außerhalb der Welt liegt.

Beispiele

@world.register
def on_mouse_left(self, position):
    world_position = self.get_from_pixel(position)
    if world_position:
        Actor(world_position)

property has_background: bool#

Ob die Welt mindestens einen Hintergrund hat.

Beispiele

if world.has_background:
    world.next_bg()

Typ:: bool

is_in_world(position)[Quellcode]#

Gibt zurück, ob eine Position innerhalb der Welt liegt.

Rückgabetyp:: bool
Parameter:: position – Position als (x, y).
Rückgabe:: True, wenn die Position in der Welt liegt.

Beispiele

if world.is_in_world((100, 100)):
    print("inside")

property layout#

Abwärtskompatible Docking-API für älteren Beispielcode.

Der eigentliche Layout-Manager bleibt intern unter world._layout. Öffentliche Docking-Hilfen liegen weiterhin unter world.camera und werden hier als Kompatibilitätsalias für bestehendes Unterrichtsmaterial verfügbar gemacht.

property learning_mode: bool#

Ob einsteigerfreundliche Umwandlungen und Hinweise aktiviert sind.

Beispiele

world.learning_mode = True

Typ:: bool

next_bg()[Quellcode]#

Schülerfreundlicher Alias, um zum nächsten Hintergrund zu wechseln.

Rückgabetyp:: Background

on_setup()[Quellcode]#

Hook für die anfängliche Einrichtung der Welt.

Überschreibe dies in Unterklassen oder registriere eine Funktion mit @world.register.

Rückgabetyp:: None

Beispiele

@world.register
def on_setup(self):
    self.background = (0, 0, 0)
    Actor((20, 20))

play_sound(path, volume=100)[Quellcode]#

Schülerfreundlicher Alias für sound.play(path, volume).

Schüler:innen probieren oft zuerst world.play_sound(...) aus, daher existiert dieser Alias zur besseren Auffindbarkeit. Bevorzugt sollte world.sound.play(...) verwendet werden.

Rückgabetyp:

None

Parameter:

path – Pfad zur Sound-Datei.
volume – Lautstärke zwischen 0 und 100.

quit(exit_code=0)[Quellcode]#

Beendet die Anwendung und schließt das Spielfenster.

Rückgabetyp:: None
Parameter:: exit_code – Prozess-Exitcode.

Beispiele

world.quit()

remove_background(background=None)[Quellcode]#

Entfernt einen Hintergrund.

Rückgabetyp:: None
Parameter:: background – Hintergrundindex oder Appearance. Wenn nichts angegeben wird, wird der letzte Hintergrund entfernt.

Beispiele

world.remove_background()
world.remove_background(0)

reset()[Quellcode]#

Setzt die Welt in ihren Anfangszustand zurück.

Beispiele

@player.register
def on_detecting_actor(self, other):
    if isinstance(other, Enemy):
        self.world.reset()

property rows: int#

Höhe des sichtbaren Weltbereichs in Pixeln.

Beispiele

world.rows = 480

Typ:: int

run(fullscreen=False, fit_desktop=False, replit=False, event=None, data=None)[Quellcode]#

Startet die Miniworlds-Hauptschleife.

Rufe dies einmal am Ende eines Miniworlds-Programms auf.

Rückgabetyp:

None

Parameter:

fullscreen – Ob im Vollbildmodus gestartet werden soll.
fit_desktop – Ob das Fenster an den Desktop angepasst werden soll.
replit – Ob Replit-spezifische Anzeigeanpassungen verwendet werden sollen.
event – Optionaler Ereignisname, der beim Start eingereiht wird.
data – Optionale Daten für das Startereignis.

Beispiele

world = World(800, 600)
world.run()

send_message(message, data=None)[Quellcode]#

Sendet eine Nachricht an die Welt und ihre Actor.

Die Nachricht wird über das Ereignissystem verteilt und kann von registrierten Nachrichten-Handlern verarbeitet werden.

Rückgabetyp:

None

Parameter:

message – Nachrichtenname.
data – Optionale Nutzdaten für nachrichtenspezifische Handler.

Beispiele

world.send_message("game_over")

@world.register
def on_message(self, message):
    if message == "game_over":
        self.stop()

set_background(source)[Quellcode]#

Ersetzt den aktiven Hintergrund.

Rückgabetyp:: Background
Parameter:: source – Bildpfad oder RGB/RGBA-Farbtupel.
Rückgabe:: Der neue aktive Background.

Beispiele

world.set_background("images/sky.png")
world.set_background((30, 30, 30))

set_bg(source)[Quellcode]#

Schülerfreundlicher Alias für set_background(source).

Rückgabetyp:: Background

set_columns(value)[Quellcode]#

Setzt die sichtbare Weltbreite in Pixeln.

Rückgabetyp:: None
Parameter:: value – Neue Breite in Pixeln.

Beispiele

world.set_columns(640)

set_rows(value)[Quellcode]#

Setzt die sichtbare Welthöhe in Pixeln.

Rückgabetyp:: None
Parameter:: value – Neue Höhe in Pixeln.

Beispiele

world.set_rows(480)

property size: Tuple[int, int]#

Weltgröße als (breite, höhe) in Pixeln.

Beispiele

width, height = world.size
world.size = (800, 600)

Typ:: tuple[int, int]

start()[Quellcode]#

Startet oder setzt die Welt-Aktualisierungen fort.

Rückgabetyp:: None

Beispiele

world.start()

stop(frames=0)[Quellcode]#

Stoppt Weltaktualisierungen sofort oder nach einer Anzahl von Frames.

Rückgabetyp:: None
Parameter:: frames – Frames, die vor dem Stoppen gewartet werden. 0 stoppt sofort.

Beispiele

world.stop()
world.stop(frames=5)

switch_background(background)[Quellcode]#

Wechselt zu einem anderen Hintergrund.

Übergebe einen Index, eine vorhandene Darstellung oder -1 für den nächsten Hintergrund.

Rückgabetyp:: Background
Parameter:: background – Hintergrundindex, Appearance oder -1.
Rückgabe:: Der neue aktive Background.

Beispiele

world.add_background("images/day.png")
world.add_background("images/night.png")
world.switch_background(1)
world.switch_background(-1)

switch_world(new_world, reset=False)[Quellcode]#

Wechselt die aktive Szene zu einer anderen Welt.

Rückgabetyp:

None

Parameter:

new_world – Die Welt, die aktiv werden soll.
reset – Wenn True, wird die neue Welt vor dem Start zurückgesetzt.

property tick_rate: int#

Wie oft die Weltlogik relativ zur Frame-Schleife läuft.

Ein Wert von 1 führt die Spiellogik in jedem Frame aus. Ein Wert von 30 führt sie in jedem 30. Frame aus.

Beispiel

from miniworlds import World

world = World(120, 210) world.fps = 60 world.tick_rate = 3 world.run()

to_pixel(position)[Quellcode]#

Wandelt eine Weltposition in eine Bildschirmpixelposition um.

Rückgabetyp:: Tuple[float, float]
Parameter:: position – Weltposition als (x, y).
Rückgabe:: Pixelposition als (x, y).

Beispiele

pixel = world.to_pixel(actor.position)

property world_size_x: int#

Horizontale Weltgröße in Pixeln.

Beispiele

world.world_size_x = 800
print(world.world_size_x)

Typ:: int

property world_size_y: int#

Vertikale Weltgröße in Pixeln.

Beispiele

world.world_size_y = 600
print(world.world_size_y)

Typ:: int

Ausnahmen#

Diese Ausnahmen werden von miniworlds exportiert, damit Code gezielt Miniworlds-Fehler abfangen kann. Sie sind hier dokumentiert, haben aber bewusst keinen eigenen Navigationseintrag.

exception miniworlds.base.exceptions.CostumeOutOfBoundsError(actor, costume_count, costume_number)[Quellcode]#

exception miniworlds.base.exceptions.OriginException(actor, value=None)[Quellcode]#