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 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
#![warn(
future_incompatible,
nonstandard_style,
rust_2018_idioms,
missing_docs,
clippy::pedantic
)]
#![allow(clippy::needless_pass_by_value, clippy::module_name_repetitions)]
#![cfg_attr(nightly, feature(doc_auto_cfg))]
//! A sprite-sheet animation plugin for [bevy](https://bevyengine.org)
//!
//! ## Usage
//!
//! 1. Add the [`AnimationPlugin`] plugin
//!
#![cfg_attr(
feature = "bevy-app-07",
doc = "
```no_run
# use bevy::prelude::*;
use benimator::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugin(AnimationPlugin::default()) // <-- Enable sprite-sheet animations
.add_startup_system(spawn)
// ...
.run()
}
fn spawn() { /* ... */ }
```
"
)]
//!
//!
//! 2. Create a [`SpriteSheetAnimation`] and insert the asset handle to the sprite sheet entity you want to animate
//!
//! ```
//! # use std::time::Duration;
//! # use bevy::prelude::*;
//! # use benimator::*;
//!
//! fn spawn(mut commands: Commands, mut animations: ResMut<Assets<SpriteSheetAnimation>>) {
//!
//! // Create an animation
//! let animation_handle = animations.add(SpriteSheetAnimation::from_range(
//! 0..=2, // Indices of the sprite atlas
//! Duration::from_secs_f64(1.0 / 12.0), // Duration of each frame
//! ));
//!
//! commands
//! .spawn_bundle(SpriteSheetBundle {
//! // TODO: Configure the sprite sheet
//! ..Default::default()
//! })
//! // Insert the asset handle of the animation
//! .insert(animation_handle)
//! // Start the animation immediately
//! .insert(Play);
//! }
//! ```
//!
//! ## Run the animation only once
//!
//! By default the animation loops forever. But it is possible to configure it differently:
//!
//! ```
//! # use std::time::Duration;
//! # use benimator::*;
//! SpriteSheetAnimation::from_range(0..=2, Duration::from_millis(100))
//! .once(); // <-- Runs the animation only once
//! ```
//!
//! Note that, for animations that run once, the `Play` component is automatically removed when the animation is done.
//! So you can use the `RemovedComponents<Play>` system parameter to execute logic at the end of the animation.
//!
//! ## Play/Pause
//!
//! Animations proceed only if the [`Play`] component is present in the entity.
//!
//! To pause or resume an animation, simply remove/insert the [`Play`] component.
//!
//! ## Fine-grained frame-duration
//!
//! For a more precise configuration, it is possible to define the duration of each frame:
//!
//! ```
//! # use benimator::*;
//! # use std::time::Duration;
//! SpriteSheetAnimation::from_frames(vec![
//! Frame::new(0, Duration::from_millis(120)),
//! Frame::new(1, Duration::from_millis(100)),
//! Frame::new(2, Duration::from_millis(80)),
//! ]);
//! ```
//!
//! ## Reset animation
//!
//! For each entity with a [`SpriteSheetAnimation`], a [`SpriteSheetAnimationState`] component is automatically inserted.
//! It can be used to reset the animation state by calling [`SpriteSheetAnimationState::reset`]
//!
//! ```
//! # use bevy::prelude::*;
//! # use benimator::SpriteSheetAnimationState;
//!
//! fn restart_anim_from_start(mut query: Query<&mut SpriteSheetAnimationState>) {
//! for mut state in query.iter_mut() {
//! state.reset();
//! }
//! }
//! ```
//!
//! ## Load animation from file **(Unstable)**
//!
//! By enabling the cargo feature: `unstable-load-from-file` you can write the animation in an asset file.
//!
//! First, create an asset file with the extension `.animation.yml`:
//! ```yaml
//! # The mode can be one of: 'Once', 'Repeat', 'PingPong'
//! # or 'RepeatFrom: n' (where 'n' is the frame-index to repeat from)
//! # The default is 'Repeat'
//! mode: PingPong
//! frame_duration: 100 # duration of the frame in milliseconds
//! frames: [0, 1, 2] # Sequence of frame index
//! ```
//!
//! You can specify different duration on each frame if you need to:
//! ```yaml
//! frames:
//! - index: 0
//! duration: 100
//! - index: 1
//! duration: 200
//! ```
//!
//! And then load it with bevy's `AssetServer`:
//! ```
//! # use bevy::prelude::*;
//! # use benimator::*;
//! # fn load(mut commands: Commands, asset_server: Res<AssetServer>) {
//! let handle: Handle<SpriteSheetAnimation> = asset_server.load("player_run.animation.yml");
//! # }
//! ```
//!
//! It is also possible to use `ron` instead of `yaml`.
//!
//! For more info on the format see: [`SpriteSheetAnimation::from_yaml_str`] and [`SpriteSheetAnimation::from_ron_str`].
#[cfg(test)]
#[macro_use]
extern crate rstest;
use bevy_ecs::component::SparseStorage;
use bevy_ecs::prelude::*;
use bevy_reflect::Reflect;
use std::time::Duration;
pub use animation::{Frame, SpriteSheetAnimation};
pub use state::SpriteSheetAnimationState;
#[allow(deprecated)]
pub use animation::AnimationMode;
mod animation;
mod state;
/// Plugin to enable sprite-sheet animation
///
/// See crate level documentation for usage
#[non_exhaustive]
#[cfg(feature = "bevy-app-07")]
#[derive(Default)]
pub struct AnimationPlugin;
/// Labels of systems that run during the post-update stage
#[non_exhaustive]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, SystemLabel)]
pub enum AnimationPostUpdateSystem {
/// System that update the sprite atlas textures
Animate,
}
/// Components that indicates the animation is playing
///
/// Insert the components to play the animation, and remove it to pause it.
///
/// If the animation mode is [`AnimationMode::Once`] this component is automatically removed at the end of the animation.
#[derive(Debug, Copy, Clone, Default, Reflect)]
#[reflect(Component)]
pub struct Play;
impl Component for Play {
type Storage = SparseStorage;
}
/// Component that, when applied, can change the playback's rate of the animation.
///
/// Receives a f64 multiplier which will alter the delta, speeding up or slowing down to the desired playback rate.
#[derive(Debug, Copy, Component, Clone, Reflect)]
#[reflect(Component)]
pub struct PlaySpeedMultiplier(f64);
impl PlaySpeedMultiplier {
/// Creates a new `PlaySpeedMultiplier` Component with the multiplier set as desired
#[must_use]
pub fn new(multiplier: f64) -> Self {
Self(multiplier)
}
fn transform(self, duration: Duration) -> Duration {
duration.mul_f64(self.0)
}
}
impl Default for PlaySpeedMultiplier {
fn default() -> Self {
Self(1.0)
}
}
impl From<f64> for PlaySpeedMultiplier {
fn from(mult: f64) -> Self {
Self(mult)
}
}
impl From<f32> for PlaySpeedMultiplier {
fn from(mult: f32) -> Self {
Self(mult.into())
}
}
#[cfg(feature = "bevy-app-07")]
impl bevy_app_07::Plugin for AnimationPlugin {
fn build(&self, app: &mut bevy_app_07::App) {
use bevy_asset::AddAsset;
app.add_asset::<SpriteSheetAnimation>()
.add_system_set_to_stage(bevy_app_07::CoreStage::PreUpdate, maintenance_systems())
.add_system_set_to_stage(bevy_app_07::CoreStage::Update, animation_systems());
#[cfg(feature = "unstable-load-from-file")]
app.init_asset_loader::<animation::load::SpriteSheetAnimationLoader>();
}
}
/// System set that automatically insert and remove components (i.e. [`SpriteSheetAnimationState`])
pub fn maintenance_systems() -> SystemSet {
SystemSet::new()
.with_system(state::insert)
.with_system(state::remove)
}
/// System set that animate the sprite-sheets
pub fn animation_systems() -> SystemSet {
SystemSet::new().with_system(state::animate)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn identity_transformation() {
assert_eq!(
PlaySpeedMultiplier::default().transform(Duration::from_secs(1)),
Duration::from_secs(1)
);
}
#[test]
fn double_speed() {
assert_eq!(
PlaySpeedMultiplier::from(2.0).transform(Duration::from_secs(2)),
Duration::from_secs(4)
);
}
}