Bevy Aseprite Ultra

To use the asset processor which converts .aseprite files into a custom optimized format, you must configure the AssetPlugin in your Bevy App and run with the asset_processing feature enabled.

1. Configure AssetPlugin:

App::new()
    .add_plugins(DefaultPlugins.set(AssetPlugin {
        mode: AssetMode::Processed,
        ..Default::default(),
    }))
    .run();

2. Run with the feature:

cargo run --features asset_processing

To use Aseprite assets in Bevy UI, combine AseAnimation or AseSlice with an ImageNode component (which acts as the render target).

Example: Animation in UI

cmd.spawn((
        Button,
        ImageNode::default(),
        AseAnimation {
            aseprite: server.load("player.aseprite"),
            animation: Animation::tag("walk-right"),
        },
));

Example: Slice in UI

cmd.spawn((
        Node {
            width: Val::Px(100.),
            height: Val::Px(100.),
            border: UiRect::all(Val::Px(5.)),
            ..default()
        },
        ImageNode::default(),
        AseSlice {
            name: "ghost_red".into(),
            aseprite: server.load("ghost_slices.aseprite"),
        },
));

Animation tags in Aseprite are mapped to TagMeta. This allows you to identify specific animation sequences (e.g., "Idle", "Run") and their properties.

TagMeta Fields

• direction: The AnimationDirection of the tag.
• range: An inclusive range (std::ops::RangeInclusive<u16>) of frames covered by the tag.
• repeat: The number of times the animation repeats.

AnimationDirection

Supported directions are:

• Forward
• Reverse
• PingPong
• PingPongReverse
• Unknown(u8)

The AnimationState component tracks the real-time progress of an animation. It is automatically managed by the plugin unless ManualTick is present.

• current_frame: The absolute index of the frame in the Aseprite file.
• relative_frame: The frame index relative to the start of the current animation tag.
• current_direction: Tracks if the animation is currently playing Forward or Backward (used for PingPong modes).

To enable automatic processing of Aseprite files (converting them into optimized formats for runtime), add the AsepriteProcessorPlugin to your Bevy App.

This plugin registers default asset processors for the .aseprite and .ase file extensions. It uses a pipeline that transforms the raw Aseprite data into a serialized MessagePack format combined with a QOI-encoded texture atlas, ensuring efficient loading during runtime.

use bevy::prelude::*;
use bevy_aseprite_ultra::AsepriteProcessorPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AsepriteProcessorPlugin)
        .run();
}

To use Aseprite files in Bevy, add the AsepriteLoaderPlugin to your app. This plugin initializes the Aseprite asset type and registers the AsepriteLoader to handle .aseprite and .ase file extensions.

use bevy_aseprite_ultra::AsepriteLoaderPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AsepriteLoaderPlugin)
        .run();
}

app.add_plugins(AsepriteLoaderPlugin);

To enable Aseprite animation support in your Bevy application, add the AsepriteAnimationPlugin to your app. This plugin handles animation ticking, event triggering (like AnimationEvents::Finished), and automatic rendering for Sprite and ImageNode components.

app.add_plugins(AsepriteAnimationPlugin);

To use bevy_aseprite_ultra, add the AsepriteUltraPlugin to your Bevy App. It is highly recommended to configure the ImagePlugin with a nearest sampler to preserve pixel art clarity.

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(ImagePlugin {
            default_sampler: bevy::render::texture::ImageSamplerDescriptor::nearest(),
        }))
        .add_plugins(AsepriteUltraPlugin)
        .add_systems(Startup, setup)
        .run();
}

The repository includes several examples to demonstrate different features. You can run them using cargo run --example <name>:

• slices: Demonstrates static slices.
• animations: Demonstrates animation playback.
• ui: Demonstrates usage in Bevy UI.
• asset_processing: Demonstrates the asset processor (requires --features asset_processing).
• 3d: Demonstrates usage in 3D environments (requires --features 3d).

cargo run --example slices
cargo run --example animations
cargo run --example ui
cargo run --example asset_processing --features asset_processing
cargo run --example 3d --features 3d

The plugin emits AnimationEvents that you can listen to in a system. This is particularly useful for triggering logic when a one-shot animation (like an explosion) finishes.

Supported events:

• AnimationEvents::Finished(entity): Emitted when an animation reaches its end.
• AnimationEvents::LoopCycleFinished(entity): Emitted when an animation completes a loop cycle.

// animation events
fn despawn_on_finish(mut events: EventReader<AnimationEvents>, mut cmd : Commands){
    for event in events.read() {
        match event {
            AnimationEvents::Finished(entity) => cmd.entity(*entity).despawn_recursive(),
            AnimationEvents::LoopCycleFinished(_entity) => (),
        };
    }
}