⚠️ Beta State

PyBevy is in an early and experimental stage. The API is incomplete, subject to breaking changes without notice, and you should expect bugs. Many features are still under development.

Sprite Sheet

Animate a sprite by cycling through frames in a sprite sheet.

Introduction

Sprite sheets pack multiple animation frames into a single image. A TextureAtlas defines how to slice the image into frames, and a timer controls the animation speed.

from dataclasses import dataclass
from pybevy.prelude import *
from pybevy.image import TextureAtlasLayout, TextureAtlas
from pybevy.math import UVec2

Animation Components

AnimationIndices defines which frames to cycle through. AnimationTimer controls the playback speed.

@component
@dataclass
class AnimationIndices(Component):
    first: int
    last: int
 
 
@component
@dataclass
class AnimationTimer(Component):
    timer: Timer

Animation System

Each frame, tick the timer. When it fires, advance to the next frame index, wrapping back to the first frame after the last.

def animate_sprite(
    time: Res[Time],
    query: Query[tuple[AnimationIndices, Mut[AnimationTimer], Mut[Sprite]]],
) -> None:
    for indices, timer_comp, sprite in query:
        timer_comp.timer.tick(time.delta_secs())
        if timer_comp.timer.just_finished():
            atlas = sprite.texture_atlas
            if atlas is not None:
                if atlas.index == indices.last:
                    atlas.index = indices.first
                else:
                    atlas.index += 1

Setup

Load the sprite sheet image, define the atlas layout (7 frames in a row, each 24x24), and spawn the animated sprite.

def setup(
    commands: Commands,
    asset_server: AssetServer,
    texture_atlas_layouts: ResMut[Assets[TextureAtlasLayout]],
) -> None:
    texture = asset_server.load_image("textures/rpg/chars/gabe/gabe-idle-run.png")
    layout = TextureAtlasLayout.from_grid(
        tile_size=UVec2.splat(24), columns=7, rows=1, padding=None, offset=None
    )
    atlas_layout = texture_atlas_layouts.add(layout)
    animation_indices = AnimationIndices(first=1, last=6)
 
    commands.spawn(Camera2d())
    commands.spawn(
        Sprite.from_atlas_image(
            texture, TextureAtlas(layout=atlas_layout, index=animation_indices.first)
        ),
        Transform.from_scale(Vec3.splat(6.0)),
        animation_indices,
        AnimationTimer(timer=Timer(0.1, TimerMode.REPEATING)),
    )

Running the App

@entrypoint
def main(app: App) -> App:
    return (
        app
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .add_systems(Update, animate_sprite)
    )
 
if __name__ == "__main__":
    main().run()

Running this example

Use PyBevy's hot reload feature to run and develop this example. If you don't have PyBevy installed, check out the Quick Start guide.

$pybevy watch sprite_sheet.py

The code will reload automatically when you make changes to the file.

From Python to Rust

Notice how the core concepts in the code—Commands, Assets, App, and Systems—are identical to the original Bevy example?

This is the power of pybevy! It lets you learn Bevy's powerful, data-driven architecture in friendly Python.

When your project grows and you're ready for maximum, native performance, you'll already know the concepts to start writing systems in Bevy Engine with Rust.

Sprite Flipping

Sprite Tile