World

The base class for all of your worlds.

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(...) for contains_position(...)

• broadcast(...) for send_message(...)

• actors_at(...) for detect_actors(...)

• set_bg(...), add_bg(...), next_bg() for background helpers

API-Referenz

class miniworlds.worlds.world.World(x=400, y=400)

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)

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

actors_at(position)

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

Rückgabetyp:

List[Actor]

add_background(source)

Fügt einen Hintergrund hinzu und macht ihn aktiv.

Rückgabetyp:

Background

Parameter:

source – Bildpfad oder RGB/RGBA-Farbtupel.

Rückgabe:

The newly created Background.

Beispiele

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

add_bg(source)

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

Rückgabetyp:

Background

property background: Background

Currently active world background.

Beispiele

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

Typ:

Background

broadcast(message, data=None)

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)

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

This is a short alias for contains_position().

contains_position(pos)

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

Parameter:

pos – Position as (x, y).

Rückgabe:

True if the position is inside the world.

Beispiele

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

contains_rect(rect)

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 if the whole rectangle is inside the world.

Beispiele

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

contains_rect_any(rect)

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)

Gibt alle Actor an einer Weltposition zurück.

Rückgabetyp:

List[Actor]

Parameter:

position – World position as (x, y).

Rückgabe:

Actors found at the position.

Beispiele

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

dialog

direction_to(pos1, pos2)

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

Rückgabetyp:

float

Parameter:

• pos1 – Start position as (x, y).

• pos2 – Target position as (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)

Gibt den euklidischen Abstand zwischen zwei Positionen zurück.

Rückgabetyp:

float

Parameter:

• pos1 – First position as (x, y).

• pos2 – Second position as (x, y).

Rückgabe:

Abstand zwischen beiden Positionen.

Beispiele

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

property fps: int

Frames per second of the render loop.

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

Example

world.fps = 24 world.tick_rate = 2

get_actors_from_pixel(pixel)

Gibt alle Actor unter einem Bildschirmpixel zurück.

Rückgabetyp:

List[Actor]

Parameter:

pixel – Screen pixel as (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()

Return the active background.

Rückgabetyp:

Background

Rückgabe:

The current Background.

Beispiele

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

get_from_pixel(position)

Wandelt eine Bildschirmpixelposition in eine Weltposition um.

Rückgabetyp:

Optional[Tuple[float, float]]

Parameter:

position – Pixel position as (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

Whether the world has at least one background.

Beispiele

if world.has_background:
    world.next_bg()

Typ:

bool

is_in_world(position)

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

Rückgabetyp:

bool

Parameter:

position – Position as (x, y).

Rückgabe:

True if the position is inside the world.

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

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

Rückgabetyp:

Background

on_setup()

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

quit(exit_code=0)

Beendet die Anwendung und schließt das Spielfenster.

Rückgabetyp:

None

Parameter:

exit_code – Prozess-Exitcode.

Beispiele

world.quit()

remove_background(background=None)

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

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)

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)

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)

Replace the active background.

Rückgabetyp:

Background

Parameter:

source – Bildpfad oder RGB/RGBA-Farbtupel.

Rückgabe:

The new active Background.

Beispiele

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

set_bg(source)

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

Rückgabetyp:

Background

set_columns(value)

Setzt die sichtbare Weltbreite in Pixeln.

Rückgabetyp:

None

Parameter:

value – Neue Breite in Pixeln.

Beispiele

world.set_columns(640)

set_rows(value)

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

Start or resume world updates.

Rückgabetyp:

None

Beispiele

world.start()

stop(frames=0)

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)

Switch to another background.

Ü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:

The new active 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)

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.

Example

from miniworlds import World

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

to_pixel(position)

Wandelt eine Weltposition in eine Bildschirmpixelposition um.

Rückgabetyp:

Tuple[float, float]

Parameter:

position – World position as (x, y).

Rückgabe:

Pixel position as (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)

exception miniworlds.base.exceptions.OriginException(actor, value=None)