pyxen.Sprite

Represents a renderable image assigned to an Entity.

Sprites are immutable objects. To change what an entity displays, replace the sprite.

For rendering concepts, see Sprites and Rendering.

Constructor

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

You may pass image either positionally or as a keyword — but not both.

Parameters

image (Required)

Sprite("hero")

If the image does not exist:

ValueError: Failed to load image 'hero'

tile (Optional)

Defines a sub-rectangle of the texture.

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

If not specified, the full image is used.

pivot (Optional)

Defines the sprite origin point.

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

If not specified: (0, 0) (top-left corner).

animation (Optional)

Plays a named animation defined in the sprite editor’s animation timeline. The engine reads the animation data (frame sequence, FPS) from the image’s metadata and advances frames automatically.

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

Cannot be combined with tile — use one or the other.

The animation starts playing immediately when assigned to an entity. By default it loops. Use loop=False for one-shot animations:

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

To check animation state, use the e.animation component on the entity.

loop (Optional)

Controls whether the animation repeats. Only used with animation. Default: True.

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

Example

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

Animated sprite:

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

Assigning a Sprite

You can assign during spawn:

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

Or later:

player.sprite = Sprite("hero_idle")

Sprite Immutability

Sprites are immutable — you cannot modify a sprite after creation.

Replace the entity’s sprite instead:

player.sprite = Sprite("hero_jump")

Color

Entities expose a color property that tints the sprite without replacing it:

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

Example:

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

Default color: (1.0, 1.0, 1.0, 1.0)

Reading color returns a Color object:

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

Animation

The recommended way to animate sprites is with the animation parameter. Define named animations in the sprite editor, then play them by name:

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

Switch animations by assigning a new sprite:

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

For one-shot animations, check completion via the entity’s animation component:

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

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

Manual animation

You can also animate manually by replacing the sprite’s tile each frame:

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

Common Errors

Missing Image

Sprite()

ValueError: Sprite must have an image

Duplicate Image Argument

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

TypeError: image specified both positionally and as keyword

Tile and Animation Conflict

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

TypeError: cannot specify both tile and animation

Animation Not Found

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

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