`pyxen.Sprite`

Représente une image affichable assignée à une Entity.

Les sprites sont des objets immuables. Pour changer ce qu’une entité affiche, remplacez le sprite.

Pour les concepts de rendu, consultez Sprites et Rendu.

Constructeur

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

Vous pouvez passer image en argument positionnel ou par mot-clé — mais pas les deux.

Paramètres

Paramètre	Type	Description
`image`	`str`	Nom de l’asset image
`tile`	`(x, y, w, h)`	Sous-rectangle de l’image
`pivot`	`(x, y)`	Point de pivot en pixels
`animation`	`str`	Nom d’une animation de sprite à jouer
`loop`	`bool`	Si l’animation boucle (défaut `True`)

`image` (Requis)

Sprite("hero")

Si l’image n’existe pas :

ValueError: Failed to load image 'hero'

`tile` (Optionnel)

Définit un sous-rectangle de la texture.

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

Si non spécifié, l’image entière est utilisée.

`pivot` (Optionnel)

Définit le point d’origine du sprite.

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

Si non spécifié : (0, 0) (coin supérieur gauche).

`animation` (Optionnel)

Joue une animation nommée définie dans la timeline d’animation de l’éditeur de sprites. Le moteur lit les données d’animation (séquence de frames, FPS) depuis les métadonnées de l’image et avance les frames automatiquement.

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

Ne peut pas être combiné avec tile — utilisez l’un ou l’autre.

L’animation commence immédiatement lorsqu’elle est assignée à une entité. Par défaut elle boucle. Utilisez loop=False pour les animations à lecture unique :

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

Pour vérifier l’état de l’animation, utilisez le composant e.animation de l’entité.

`loop` (Optionnel)

Contrôle si l’animation se répète. Utilisé uniquement avec animation. Défaut : True.

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

Exemple

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

Sprite animé :

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

Assigner un Sprite

Vous pouvez assigner lors du spawn :

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

Ou plus tard :

player.sprite = Sprite("hero_idle")

Immutabilité des Sprites

Les sprites sont immuables — vous ne pouvez pas modifier un sprite après sa création.

Remplacez plutôt le sprite de l’entité :

player.sprite = Sprite("hero_jump")

Couleur

Les entités exposent une propriété de couleur qui teinte le sprite sans le remplacer :

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

Exemple :

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

Couleur par défaut : (1.0, 1.0, 1.0, 1.0)

La lecture de la couleur renvoie un objet Color :

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

Animation

La méthode recommandée pour animer les sprites est avec le paramètre animation. Définissez des animations nommées dans l’éditeur de sprites, puis jouez-les par nom :

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

Changez d’animation en assignant un nouveau sprite :

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

Pour les animations à lecture unique, vérifiez la complétion via le composant animation de l’entité :

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

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

Animation manuelle

Vous pouvez aussi animer manuellement en remplaçant la tile du sprite à chaque frame :

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

Erreurs courantes

Image manquante

Sprite()

ValueError: Sprite must have an image

Argument image en double

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

TypeError: image specified both positionally and as keyword

Conflit entre tile et animation

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

TypeError: cannot specify both tile and animation

Animation introuvable

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

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

pyxen.Sprite