pybevy 0.2.1

PyBevy: A Python Real-Time Engine Built on Bevy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

"""Renders an animated sprite by loading all animation frames from a single image.

This example demonstrates:
- Sprite sheet animation using TextureAtlas
- Automatic frame advancement with Timer
- Custom components for animation state
- Mutable field access on Sprite.texture_atlas.index

The sprite sheet is divided into a grid, and the animation cycles through
a subset of frames at a fixed frame rate.

Note: PyBevy doesn't support DefaultPlugins.set() yet, so ImagePlugin
configuration (nearest-neighbor filtering) is not available. Sprites may
appear slightly blurred at certain scales.
"""

from dataclasses import dataclass

from pybevy.prelude import *


@component
@dataclass
class AnimationIndices(Component):
    """Defines which frames in the sprite sheet to use for animation.

    Attributes:
        first: Index of the first frame in the animation sequence
        last: Index of the last frame in the animation sequence
    """
    first: int
    last: int


@component(storage="python")
@dataclass
class AnimationTimer(Component):
    """Timer controlling animation frame advancement.

    Attributes:
        timer: Timer that ticks each frame
    """
    timer: Timer


def animate_sprite(
    time: Res[Time],
    query: Query[tuple[AnimationIndices, Mut[AnimationTimer], Mut[Sprite]]],
) -> None:
    """Advance sprite animation frames based on timer."""
    for indices, timer_component, sprite in query:
        timer_component.timer.tick(time.delta_secs())

        if timer_component.timer.just_finished():
            atlas = sprite.texture_atlas
            if atlas is not None:
                # Cycle to next frame, wrapping back to first after last
                if atlas.index == indices.last:
                    atlas.index = indices.first
                else:
                    atlas.index += 1


def setup(
    commands: Commands,
    asset_server: Res[AssetServer],
    texture_atlas_layouts: ResMut[Assets[TextureAtlasLayout]],
) -> None:
    """Set up camera and animated sprite."""
    # Load the sprite sheet texture
    texture = asset_server.load_image("bevy/textures/rpg/chars/gabe/gabe-idle-run.png")

    # Create a texture atlas layout from a sprite sheet grid
    # The sprite sheet has 7 frames in a single row, each 24x24 pixels
    layout = TextureAtlasLayout.from_grid(
        tile_size=UVec2.splat(24),
        columns=7,
        rows=1,
        padding=None,
        offset=None,
    )
    texture_atlas_layout = texture_atlas_layouts.add(layout)

    # Use only the subset of sprites that make up the run animation (frames 1-6)
    animation_indices = AnimationIndices(first=1, last=6)

    commands.spawn(Camera2d())

    commands.spawn(
        Sprite.from_atlas_image(
            texture,
            TextureAtlas(
                layout=texture_atlas_layout,
                index=animation_indices.first,
            ),
        ),
        Transform.from_scale(Vec3.splat(6.0)),
        animation_indices,
        AnimationTimer(timer=Timer(0.1, TimerMode.REPEATING)),
    )


@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()