pyxen.Sprite

Repräsentiert ein darstellbares Bild, das einem Entity zugewiesen wird.

Sprites sind unveränderliche Objekte. Um die Darstellung eines Entity zu ändern, ersetze das Sprite.

Rendering-Konzepte findest du unter Sprites und Rendering.

Konstruktor

Sprite(
    image,
    *,
    tile=None,
    pivot=None,
    animation=None,
    loop=True
)

Du kannst image entweder positional oder als Keyword übergeben — aber nicht beides.

Parameter

image (Erforderlich)

Sprite("hero")

Wenn das Bild nicht existiert:

ValueError: Failed to load image 'hero'

tile (Optional)

Definiert ein Teilrechteck der Textur.

Sprite(
    "tileset",
    tile=(0, 0, 16, 16)
)

Wenn nicht angegeben, wird das gesamte Bild verwendet.

pivot (Optional)

Definiert den Ursprungspunkt des Sprites.

Sprite(
    "hero",
    pivot=(8, 8)
)

Wenn nicht angegeben: (0, 0) (obere linke Ecke).

animation (Optional)

Spielt eine benannte Animation ab, die in der Animations-Zeitleiste des Sprite-Editors definiert wurde. Die Engine liest die Animationsdaten (Frame-Sequenz, FPS) aus den Metadaten des Bildes und wechselt die Frames automatisch.

Sprite("hero", animation="walk")

Kann nicht mit tile kombiniert werden — verwende das eine oder das andere.

Die Animation beginnt sofort abzuspielen, wenn sie einem Entity zugewiesen wird. Standardmäßig wird sie wiederholt. Verwende loop=False für einmalige Animationen:

Sprite("hero", animation="death", loop=False)

Um den Animationszustand zu prüfen, verwende die e.animation-Komponente des Entity.

loop (Optional)

Steuert, ob die Animation wiederholt wird. Wird nur mit animation verwendet. Standard: True.

Sprite("hero", animation="jump", loop=False)

Beispiel

hero_sprite = Sprite(
    image="hero",
    tile=(0, 0, 16, 16),
    pivot=(8, 8)
)

Animiertes Sprite:

hero_sprite = Sprite(
    image="hero",
    animation="walk",
    pivot=(8, 8)
)

Ein Sprite zuweisen

Du kannst beim Spawn zuweisen:

player = world.spawn(
    sprite=Sprite("hero"),
    x=32,
    y=32
)

Oder nachträglich:

player.sprite = Sprite("hero_idle")

Sprite-Unveränderlichkeit

Sprites sind unveränderlich — du kannst ein Sprite nach der Erstellung nicht ändern.

Ersetze stattdessen das Sprite des Entity:

player.sprite = Sprite("hero_jump")

Farbe

Entities haben eine Farbeigenschaft, die das Sprite einfärbt, ohne es zu ersetzen:

entity.color = (r, g, b, a)

Beispiel:

player.color = (1.0, 0.5, 0.5, 1.0)

Standardfarbe: (1.0, 1.0, 1.0, 1.0)

Das Lesen der Farbe gibt ein Color-Objekt zurück:

c = player.color
print(c.r, c.g, c.b, c.a)

Animation

Die empfohlene Methode zur Animation von Sprites ist der animation-Parameter. Definiere benannte Animationen im Sprite-Editor, dann spiele sie nach Name ab:

player.sprite = Sprite("hero", animation="walk")

Wechsle Animationen, indem du ein neues Sprite zuweist:

player.sprite = Sprite("hero", animation="idle")

Für einmalige Animationen prüfe den Abschluss über die animation-Komponente des Entity:

player.sprite = Sprite("hero", animation="attack", loop=False)

def update():
    if player.animation and player.animation.finished:
        player.sprite = Sprite("hero", animation="idle")

Manuelle Animation

Du kannst auch manuell animieren, indem du die Kachel des Sprites in jedem Frame ersetzt:

player.sprite = Sprite(
    "atlas",
    tile=(frame * 16, 0, 16, 16)
)

Häufige Fehler

Fehlendes Bild

Sprite()

ValueError: Sprite must have an image

Doppeltes Bild-Argument

Sprite("hero", image="hero")

TypeError: image specified both positionally and as keyword

Tile und Animation gleichzeitig

Sprite("hero", tile=(0, 0, 16, 16), animation="walk")

TypeError: cannot specify both tile and animation

Animation nicht gefunden

Sprite("hero", animation="fly")

ValueError: Animation 'fly' not found in 'hero'