pyxen.Sprite

Representa una imagen renderizable asignada a un Entity.

Los Sprites son objetos inmutables. Para cambiar lo que una entidad muestra, reemplaza el sprite.

Para conceptos de renderizado, consulta Sprites y renderizado.

Constructor

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

Puedes pasar image tanto posicionalmente como por nombre — pero no ambos.

Parámetros

image (Requerido)

Sprite("hero")

Si la imagen no existe:

ValueError: Failed to load image 'hero'

tile (Opcional)

Define un subrectángulo de la textura.

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

Si no se especifica, se usa la imagen completa.

pivot (Opcional)

Define el punto de origen del sprite.

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

Si no se especifica: (0, 0) (esquina superior izquierda).

animation (Opcional)

Reproduce una animación con nombre definida en la línea de tiempo de animación del editor de sprites. El motor lee los datos de la animación (secuencia de fotogramas, FPS) de los metadatos de la imagen y avanza los fotogramas automáticamente.

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

No se puede combinar con tile — usa uno u otro.

La animación comienza a reproducirse inmediatamente al asignarse a una entidad. Por defecto se repite en bucle. Usa loop=False para animaciones de una sola vez:

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

Para comprobar el estado de la animación, usa el componente e.animation en la entidad.

loop (Opcional)

Controla si la animación se repite. Solo se usa con animation. Por defecto: True.

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

Ejemplo

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

Sprite animado:

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

Asignar un Sprite

Puedes asignarlo durante spawn:

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

O después:

player.sprite = Sprite("hero_idle")

Inmutabilidad de Sprite

Los sprites son inmutables — no puedes modificar un sprite después de crearlo.

En su lugar, reemplaza el sprite de la entidad:

player.sprite = Sprite("hero_jump")

Color

Las entidades exponen una propiedad color que tiñe el sprite sin reemplazarlo:

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

Ejemplo:

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

Color por defecto: (1.0, 1.0, 1.0, 1.0)

Leer color devuelve un objeto Color:

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

Animación

La forma recomendada de animar sprites es con el parámetro animation. Define animaciones con nombre en el editor de sprites, luego reprodúcelas por nombre:

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

Cambia de animación asignando un nuevo sprite:

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

Para animaciones de una sola vez, comprueba la finalización mediante el componente animation de la entidad:

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

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

Animación manual

También puedes animar manualmente reemplazando el tile del sprite en cada frame:

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

Errores comunes

Imagen faltante

Sprite()

ValueError: Sprite must have an image

Argumento de imagen duplicado

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

TypeError: image specified both positionally and as keyword

Conflicto entre tile y animation

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

TypeError: cannot specify both tile and animation

Animación no encontrada

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

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